Bug #20671 for podlators:

Tue Jul 25 05:52:59 2006 MARKOV [...] cpan.org - Ticket created

The following pod: (taken from my actual POD about OODoc) in the html version of these manual pages: M E<lt> perldoc E<gt> illegal: not in distribution M E<lt> OODoc::Object E<gt> OODoc::Object produces in the html version of these manual pages: M < perldoc > illegal: not in distribution M E<lt> OODoc::Object E<gt> OODoc::Object Apparently, when a verbatom block is attached to a text block, the entities do get decoded, otherwise not. This inconsistent behavior is unwanted.

Tue Jul 25 13:23:34 2006 RRA [...] cpan.org - Correspondence added

From:

RRA [...] cpan.org

On Tue Jul 25 05:52:59 2006, MARKOV wrote: Show quoted text

> The following pod: (taken from my actual POD about OODoc) > > in the html version of these manual pages: > M E<lt> perldoc E<gt> illegal: not in distribution > > M E<lt> OODoc::Object E<gt> OODoc::Object > > produces > > in the html version of these manual pages: > M < perldoc > illegal: not in distribution > > M E<lt> OODoc::Object E<gt> OODoc::Object

Well, unfortunately the first comment I have to make is that podlators doesn't do any conversion to HTML, only text and *roff, so this isn't the right package to report the bug against. That being said, I think your problem is due to the following (from perlpod): A verbatim paragraph is distinguished by having its first character be a space or a tab. (And commonly, all its lines begin with spaces and/or tabs.) It should be reproduced exactly, with tabs assumed to be on 8-column boundaries. There are no special formatting codes, so you can’t italicize or anything like that. In other words, formatting codes aren't supported in verbatim paragraphs.

Tue Jul 25 13:23:34 2006 The RT System itself - Status changed from 'new' to 'open'

Tue Jul 25 13:24:05 2006 RRA [...] cpan.org - Status changed from 'open' to 'rejected'

Tue Jul 25 16:07:44 2006 solutions [...] overmeer.net - Correspondence added

Subject:	Re: [rt.cpan.org #20671]
Date:	Tue, 25 Jul 2006 22:06:53 +0200
To:	Russ_Allbery via RT <bug-podlators [...] rt.cpan.org>
From:	Mark Overmeer <solutions [...] overmeer.net>

* Russ_Allbery via RT (bug-podlators@rt.cpan.org) [060725 17:23]: Show quoted text

> > <URL: http://rt.cpan.org/Ticket/Display.html?id=20671 > > > On Tue Jul 25 05:52:59 2006, MARKOV wrote:

> > The following pod: (taken from my actual POD about OODoc) > > > > in the html version of these manual pages: > > M E<lt> perldoc E<gt> illegal: not in distribution > > > > M E<lt> OODoc::Object E<gt> OODoc::Object > > > > produces > > > > in the html version of these manual pages: > > M < perldoc > illegal: not in distribution > > > > M E<lt> OODoc::Object E<gt> OODoc::Object

> > Well, unfortunately the first comment I have to make is that podlators > doesn't do any conversion to HTML, only text and *roff, so this isn't > the right package to report the bug against.

Well, my first line was an attempt to work around that confusion: that line with "html" is within my own text... it is part of the exerpt. Show quoted text

> That being said, I think your problem is due to the following (from > perlpod): > > A verbatim paragraph is distinguished by having its first character be > a space or a tab. (And commonly, all its lines begin with spaces > and/or tabs.) It should be reproduced exactly, with tabs assumed > to be on 8-column boundaries. There are no special formatting codes, > so you can’t italicize or anything like that. > > In other words, formatting codes aren't supported in verbatim paragraphs.

Coming to the place what I report: if the verbatim piece is part of a normal paragraph, then the formatting codes *are* interpreted. It is quite confusing to have two verbatims behave differently. For instance, I have long table and like to add a blank line... Even worse, I do understand the difference, but how can I explain this to users who use my module to generates POD? No fun! I would like to see interpretation to happen always, but am aware of breaking backwards-compatibility. -- Regards, MarkOv ------------------------------------------------------------------------ drs Mark A.C.J. Overmeer MARKOV Solutions Mark@Overmeer.net solutions@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net

Tue Jul 25 16:07:54 2006 The RT System itself - Status changed from 'rejected' to 'open'

Tue Jul 25 17:16:51 2006 RRA [...] cpan.org - Correspondence added

On Tue Jul 25 16:07:44 2006, solutions@overmeer.net wrote: Show quoted text

> Coming to the place what I report: if the verbatim piece is part of a > normal paragraph, then the formatting codes *are* interpreted.

Er, there's no such thing as a "verbatim piece [that's] part of a normal paragraph," so I really don't understand what you mean. If the first line of the paragraph doesn't begin with whitespace, the entire paragraph is not verbatim. Pod::Man has some hacks wherein it preserves line breaks for ease of writing nice-looking SYNOPSIS sections, but that doesn't make the text verbatim. Show quoted text

> I would like to see interpretation to happen always, but am aware of > breaking backwards-compatibility.

Various proposals for this have been floated, but none have been implemented. In order to have this, the Pod parser classes and specification would have to be changed; it's not something I can do in any sort of maintainable way only in podlators.

Tue Jul 25 17:17:05 2006 RRA [...] cpan.org - Status changed from 'open' to 'rejected'

Tue Jul 25 17:28:27 2006 solutions [...] overmeer.net - Correspondence added

Subject:	Re: [rt.cpan.org #20671]
Date:	Tue, 25 Jul 2006 23:28:11 +0200
To:	Russ_Allbery via RT <bug-podlators [...] rt.cpan.org>
From:	Mark Overmeer <solutions [...] overmeer.net>

* Russ_Allbery via RT (bug-podlators@rt.cpan.org) [060725 21:16]: Show quoted text

> Er, there's no such thing as a "verbatim piece [that's] part of a normal > paragraph," so I really don't understand what you mean. > > If the first line of the paragraph doesn't begin with whitespace, the > entire paragraph is not verbatim. Pod::Man has some hacks wherein it > preserves line breaks for ease of writing nice-looking SYNOPSIS > sections, but that doesn't make the text verbatim.

More than that. Try "pod2man xyz | man -l" xyz: =pod =over 4 =item hi this is a line so you can see that it is being reformated as it should be. The lines are refolded to fill-up the full screen space. and these are E<gt>E<gt> columns over multiple lines now a verbatim block without E<lt> entity translations E<gt>E<gt> =back =cut One thing I discovered writing this example, is that the "and" and "over" lines do indent with the paragraph. Without "=over" there is a more visual difference. Maybe you call the first case a table? Well, it works just like verbatim, so shouldn't format differently. -- MarkOv ------------------------------------------------------------------------ drs Mark A.C.J. Overmeer MARKOV Solutions Mark@Overmeer.net solutions@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net

Tue Jul 25 17:28:28 2006 The RT System itself - Status changed from 'rejected' to 'open'

Tue Jul 25 17:39:58 2006 RRA [...] cpan.org - Correspondence added

Yes, that's actually an accident of the implementation and is really a bug, but it has some useful properties so I've not fixed it yet. However, it is absolutely not verbatim. You could talk me into fixing it so that it wraps that paragraph like every other and just special-casing SYNOPSIS. I am not going to try to honor formatting codes in verbatim text; it is basically impossible to do this in podlators since that decision is made by the parsing module. If you want to see that changed in the POD specification, please file a bug against Pod::Simple; any changes made to it will automatically change the behavior of podlators.

Tue Jul 25 17:40:00 2006 RRA [...] cpan.org - Status changed from 'open' to 'rejected'

Wed Jul 26 02:18:40 2006 solutions [...] overmeer.net - Correspondence added

Subject:	Re: [rt.cpan.org #20671]
Date:	Wed, 26 Jul 2006 08:18:23 +0200
To:	Russ_Allbery via RT <bug-podlators [...] rt.cpan.org>
From:	Mark Overmeer <solutions [...] overmeer.net>

* Russ_Allbery via RT (bug-podlators@rt.cpan.org) [060725 21:39]: Show quoted text

> Yes, that's actually an accident of the implementation and is really a > bug, but it has some useful properties so I've not fixed it yet.

If it is useful, then over time people (like me) start depending on this. Any change to the behavior will cause people ti suffer. So, please decide per bug immediately either to fix it or to declare it an (accidental) feature of your implementation. Show quoted text

> If you want to see that changed in the POD > specification, please file a bug against Pod::Simple; any changes made > to it will automatically change the behavior of podlators.

To exclude verbatim from other than only reformatting rules has been choosen by some other text formatters as well. Other text formatters do accept markup inside verbatim. Both have its pro's and con's. Once chosen, there is no way back. -- Regards, MarkOv ------------------------------------------------------------------------ Mark Overmeer MSc MARKOV Solutions Mark@Overmeer.net solutions@overmeer.net http://Mark.Overmeer.net http://solutions.overmeer.net

Wed Jul 26 02:18:42 2006 The RT System itself - Status changed from 'rejected' to 'open'

Wed Jul 26 13:56:00 2006 RRA [...] cpan.org - Status changed from 'open' to 'rejected'