Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[Russ Allbery]

Allison Randal  writes:
> Russ Allbery wrote:

>> This is not the sort of thing that one gets to change retroactively,
>> I'm afraid, no matter how nice it would be for consistency.

> Agreed on keeping Perl 5 pod changes minimal, but I thought it always
> worked that way. Does anyone have an old pod parser around to test?

tribes:~> cat test.pod
=head1 TEST NESTED C

C<< this should be I >>
C<< this should not need escaping: $x > L->blort >>
tribes:~> perl /usr/local/bin/pod2man test.pod | grep should
\&\f(CW\*(C`this should be \f(CIitalic\f(CW\*(C'\fR
\&\f(CW\*(C`this should not need escaping: $x > Foo\->blort\*(C'\fR
tribes:~> perl -v | head -2

This is perl, v5.8.6 built for sun4-solaris
tribes:~> perl -MPod::Man -e 'print $INC{"Pod/Man.pm"}, "\n"'
/usr/local/lib/perl5/5.8.6/Pod/Man.pm
tribes:~> grep ^'use Pod' /usr/local/lib/perl5/5.8.6/Pod/Man.pm
use Pod::ParseLink qw(parselink);
use Pod::Parser ();

So this is how it worked in Perl 5.8 with Pod::Parser.

-- 
Russ Allbery (r...@stanford.edu) 

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[Allison Randal]

Russ Allbery wrote:

This is not the sort of thing that one gets to change retroactively, I'm
afraid, no matter how nice it would be for consistency.


Agreed on keeping Perl 5 pod changes minimal, but I thought it always 
worked that way. Does anyone have an old pod parser around to test?


Where the spec is unclear, either the (prior) implementation is the 
spec, or we create the spec.


Allison

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[Russ Allbery]

Allison Randal  writes:
> Ricardo Signes wrote:

>> The bug report from CJM seems correct: formatting codes should work
>> inside C<<>>.  There is nothing about that change which would require
>> escpaing -> or other non-formatting-code uses of angle brackets.

> H... that does put a different light on it... But, I still think
> it's more useful and less confusing as an absolute escape on all angle
> brackets within the region. So either a) every angle is literal:

>   C<< $x > L->blort >>

> or b) escape all non-special angles:

>   C<$x E LEFooE-Eblort>

This is all fine and good if we were designing POD from scratch at this
point, and I'd probably agree with you.  However, we're not.  Formatting
codes should work inside C<>, including C<< >>, at this point because they
always have since the syntax was introduced, and changing that is a huge
failure of backward compatibility with existing documents.  Likewise with
not forcing people to escape every angle bracket, only the ones that look
like formatting codes.

This is not the sort of thing that one gets to change retroactively, I'm
afraid, no matter how nice it would be for consistency.

-- 
Russ Allbery (r...@stanford.edu) 

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[David E. Wheeler]

On Mar 16, 2010, at 6:07 AM, Allison Randal wrote:

> H... that does put a different light on it... But, I still think it's 
> more useful and less confusing as an absolute escape on all angle brackets 
> within the region. So either a) every angle is literal:
> 
>  C<< $x > L->blort >>
> 
> or b) escape all non-special angles:
> 
>  C<$x E LEFooE-Eblort>
> 
> The alternatives suggested:
> 
>  C<< $x > LZ<>->blort >>
>  C<< $x > LEFooE->blort >>
> 
> Have a design taste of hacks required by a formatting language that's too 
> limited and inconsistent.
> 
> The bug reporter asked how to write:
> 
>  S<< C<< name => value >> >>
> 
> That's just:
> 
>  S< C<< name => value >> >
> 
> The non-interpolation rule doesn't apply until you get to the double-angles.

++Consistency. This is why I went with Schwern's original suggestion, in 
consultation with Allison (we had a Pod::Simple hackathon before 3.09 and fixed 
all the bugs we could). To me it's much simpler the way it is.

Best,

David

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[Allison Randal]

Ricardo Signes wrote:

* Allison Randal  [2010-03-16T08:01:49]

David E. Wheeler wrote:

My interpretation of that was that any angle brackets inside should be
considered literal, and thus escaped. The whole point of `<<   >>` AFAICS
was to allow one to use literal brackets without escaping them, as one must
do in `<>`.

That's my interpretation too. If you have to escape every angle
bracket inside doubled-up C<<>> tags, there's really no point in
even having the doubled-up tags.


No one is saying that you have to escape every angle bracket inside anything.

For example, these should all be fine:

  The ->, or dereference, operator...

  Call C<< $object->foo >>

  If x > 10

  All items where C<< $x > 10 >>

  In the event that C<< $x > L->blort >>

In the first four, there is no ambiguity.  We don't have something in the form
X<...> where X is [A-Z].  The only thing in question is the last one.  The
question is whether all characters until the matching \s>> are considered
literally or whether they're still Pod.

The bug report from CJM seems correct: formatting codes should work inside
C<<>>.  There is nothing about that change which would require escpaing -> or
other non-formatting-code uses of angle brackets.


H... that does put a different light on it... But, I still think 
it's more useful and less confusing as an absolute escape on all angle 
brackets within the region. So either a) every angle is literal:


  C<< $x > L->blort >>

or b) escape all non-special angles:

  C<$x E LEFooE-Eblort>

The alternatives suggested:

  C<< $x > LZ<>->blort >>
  C<< $x > LEFooE->blort >>

Have a design taste of hacks required by a formatting language that's 
too limited and inconsistent.


The bug reporter asked how to write:

  S<< C<< name => value >> >>

That's just:

  S< C<< name => value >> >

The non-interpolation rule doesn't apply until you get to the double-angles.

Allison

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[Ricardo Signes]

* Allison Randal  [2010-03-16T08:01:49]
> David E. Wheeler wrote:
> >
> >My interpretation of that was that any angle brackets inside should be
> >considered literal, and thus escaped. The whole point of `<<   >>` AFAICS
> >was to allow one to use literal brackets without escaping them, as one must
> >do in `<>`.
> 
> That's my interpretation too. If you have to escape every angle
> bracket inside doubled-up C<<>> tags, there's really no point in
> even having the doubled-up tags.

No one is saying that you have to escape every angle bracket inside anything.

For example, these should all be fine:

  The ->, or dereference, operator...

  Call C<< $object->foo >>

  If x > 10

  All items where C<< $x > 10 >>

  In the event that C<< $x > L->blort >>

In the first four, there is no ambiguity.  We don't have something in the form
X<...> where X is [A-Z].  The only thing in question is the last one.  The
question is whether all characters until the matching \s>> are considered
literally or whether they're still Pod.

The bug report from CJM seems correct: formatting codes should work inside
C<<>>.  There is nothing about that change which would require escpaing -> or
other non-formatting-code uses of angle brackets.

-- 
rjbs

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[Allison Randal]

David E. Wheeler wrote:


My interpretation of that was that any angle brackets inside should be considered literal, and 
thus escaped. The whole point of `<<   >>` AFAICS was to allow one to use literal 
brackets without escaping them, as one must do in `<>`.


That's my interpretation too. If you have to escape every angle bracket 
inside doubled-up C<<>> tags, there's really no point in even having the 
doubled-up tags.


I think the latest bug report is wrong.

Allison

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[David E. Wheeler]

On Mar 15, 2010, at 6:08 PM, Ricardo Signes wrote:

> ...and clearly I agreed!  I'm not sure whether I misunderstood or was just
> wrong.  Either way, I think the change was incorrect.
> 
> I will try to write an update for the spec soon.

Okay. Once that's done and we have consensus, I'll try to find the tuits to 
make it match the spec.

Best,

David

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[Ricardo Signes]

* "David E. Wheeler"  [2010-03-15T19:28:15]
> Well, should it change to that? If we can all agree on a proper solution and
> update the spec to be specific, I'm happy to modify Pod::Simple (if I can
> find the tuits) to match that.
> 
> FWIW, I blogged about this when 3.09 came out:
> http://www.justatheory.com/computers/programming/perl/modules/new-pod-simple.html

...and clearly I agreed!  I'm not sure whether I misunderstood or was just
wrong.  Either way, I think the change was incorrect.

I will try to write an update for the spec soon.

-- 
rjbs

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[Ronald J Kimball]

On Mon, Mar 15, 2010 at 04:28:15PM -0700, David E. Wheeler wrote:
> On Mar 15, 2010, at 12:19 PM, Ricardo Signes wrote:
> 
> > In other words, the only change /C<{2,}\s+/ has over /C<{1}/ is that it 
> > changes
> > the number of >'s that are needed to close that code.  Fewer >'s than that 
> > are
> > just text.
> > 
> > Frustrating.
> 
> Well, should it change to that? If we can all agree on a proper solution
> and update the spec to be specific, I'm happy to modify Pod::Simple (if I
> can find the tuits) to match that.

I think it should be changed back to the original behavior.  The new
behavior was based on a misreading of the spec.

Ronald

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[David E. Wheeler]

On Mar 15, 2010, at 12:19 PM, Ricardo Signes wrote:

> In other words, the only change /C<{2,}\s+/ has over /C<{1}/ is that it 
> changes
> the number of >'s that are needed to close that code.  Fewer >'s than that are
> just text.
> 
> Frustrating.

Well, should it change to that? If we can all agree on a proper solution and 
update the spec to be specific, I'm happy to modify Pod::Simple (if I can find 
the tuits) to match that.

FWIW, I blogged about this when 3.09 came out: 
http://www.justatheory.com/computers/programming/perl/modules/new-pod-simple.html

Everyone I heard from as a result of that post thought it made sense. :-(

Best,

David

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[Ricardo Signes]

* "David E. Wheeler"  [2010-03-15T14:56:48]
> > 
> >C<<< open(X, ">>thing.dat") || die $! >>>
> >C<< $foo−>bar(); >>
> > 
> >which is presumably easier to read than the old way:
> > 
> >CEthing.dat") || die $!>
> >C<$foo−Ebar();>
> 
> My interpretation of that was that any angle brackets inside should be
> considered literal, and thus escaped. The whole point of `<<   >>` AFAICS was
> to allow one to use literal brackets without escaping them, as one must do in
> `<>`.

Right -- but that's because they're potentially-matching right brackets.  For
example, this line is valid Pod with no formatting codes:

  "Hello world." >> cout;

We don't need to use EE because there's no open quote to give the
closing one special significance.  If we did this, though:

  C<"Hello world." >> cout;>

...then the first > closes the C<>.

What if we wanted:

  C<< ls > F >>

In other words, the only change /C<{2,}\s+/ has over /C<{1}/ is that it changes
the number of >'s that are needed to close that code.  Fewer >'s than that are
just text.

Frustrating.

-- 
rjbs

RE: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[Jan Dubois]

On Mon, 15 Mar 2010, David E. Wheeler wrote:
> 
> On Mar 15, 2010, at 10:57 AM, Ricardo Signes wrote:
> 
> > Is there anyone who can provide a reading of the spec to support the change?
> > Do you (David) remember what part of the spec convinced you?
> 
> When I made the change, I wasn't aware of the spec, but based the
> change on `perlpod`, particularly this bit:
> 
> >C<<< $a <=> $b >>>
> >C  $a <=> $b 
> >
> >And they all mean exactly the same as this:
> >
> >C<$a E=E $b>
> >
> >As a further example, this means that if you wanted to put these bits
> >of code in "C" (code) style:
> >
> >open(X, ">>thing.dat") || die $!
> >$foo−>bar();
> >
> >you could do it like so:
> >
> >C<<< open(X, ">>thing.dat") || die $! >>>
> >C<< $foo−>bar(); >>
> >
> >which is presumably easier to read than the old way:
> >
> >CEthing.dat") || die $!>
> >C<$foo−Ebar();>
> 
> My interpretation of that was that any angle brackets inside should be
> considered literal, and thus escaped. The whole point of `<< >>`
> AFAICS was to allow one to use literal brackets without escaping them,
> as one must do in `<>`.

It is really just about not having to escape the *closing* '>' because you
could always include '<' without escaping unless it was ambiguous with the
start of another formatting sequence.

And anyways, I doubt there are many documents that would want to show
literal POD formatting sequences inside a C<< >> block (if we ignore the
POD specs and documentation of POD modules themselves for a moment). So
it seems generally much more useful to still be able to use nested
formatting while simultaneously not having to escape most '<' and '>'
characters.

Cheers,
-Jan

Re: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[David E. Wheeler]

On Mar 15, 2010, at 10:57 AM, Ricardo Signes wrote:

> Is there anyone who can provide a reading of the spec to support the change?
> Do you (David) remember what part of the spec convinced you?

When I made the change, I wasn't aware of the spec, but based the change on 
`perlpod`, particularly this bit:

>C<<< $a <=> $b >>>
>C  $a <=> $b 
> 
>And they all mean exactly the same as this:
> 
>C<$a E=E $b>
> 
>As a further example, this means that if you wanted to put these bits
>of code in "C" (code) style:
> 
>open(X, ">>thing.dat") || die $!
>$foo−>bar();
> 
>you could do it like so:
> 
>C<<< open(X, ">>thing.dat") || die $! >>>
>C<< $foo−>bar(); >>
> 
>which is presumably easier to read than the old way:
> 
>CEthing.dat") || die $!>
>C<$foo−Ebar();>

My interpretation of that was that any angle brackets inside should be 
considered literal, and thus escaped. The whole point of `<<   >>` AFAICS was 
to allow one to use literal brackets without escaping them, as one must do in 
`<>`.

Best,

David

RE: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[Jan Dubois]

On Mon, 15 Mar 2010, David E. Wheeler wrote:
> 
> Comments?

I agree with the bug report, FWIW (just based on reading the
report,  I haven't verified that nested formatting has been
broken).

Cheers,
-Jan


> Begin forwarded message:
> 
> > From: "Christopher J. Madsen via RT" 
> > Date: March 15, 2010 10:09:12 AM PDT
> > To: undisclosed-recipients:;
> > Subject: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting 
> > codes)
> > Reply-To: bug-pod-sim...@rt.cpan.org
> >
> > Mon Mar 15 13:09:05 2010: Request 55602 was acted upon.
> > Transaction: Ticket created by CJM
> >   Queue: Pod-Simple
> > Subject: Bug #12239 was a mistake (nested formatting codes)
> >   Broken in: 3.09
> >Severity: Important
> >   Owner: Nobody
> >  Requestors: p...@cjmweb.net
> >  Status: new
> > Ticket https://rt.cpan.org/Ticket/Display.html?id=55602 >
> >
> >
> > In bug #12239, Schwern expected "C<<< C<> >>>" to render as a
> > literal "C<>", and you changed Pod-Simple to make that happen.  But
> > I disagree with this interpretation of the spec, and consider it a
> > serious loss of functionality.
> >
> > Where exactly in perlpod or perlpodspec does it suggest that characters
> > inside C<> are treated differently than those inside C<< >>?  As I read
> > the spec, the only difference is in how the end of the code is located.
> > Once you've located the end of the content (and stripped the mandatory
> > whitespace from the C<< >> version), it's rendered the same.
> >
> > That is, I claim that "C<<< C<> >>>" is a C<> nested inside a C<>,
> > and Schwern should have written ""C<<< CZ<><> >>>" or "C<<<
> > CE> >>>".
> >
> > perlpod clearly states that "C<$a E=E $b>" is rendered as "$a
> > <=> $b".  You're saying that
> >
> >C<$a E=E $b>
> >  C<< $a E=E $b >>
> >
> > mean two completely different things, and I don't see where the spec
> > supports that.
> >
> > Otherwise, how am I supposed to write:
> >
> > S<< C<< name => value >> >>
> >
> > or
> >
> > S<< C<<  >> >>
> >

Re: Fwd: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[Ricardo Signes]

* "David E. Wheeler"  [2010-03-15T13:32:28]
> Comments?

>From perlpodspec (presented as verbatim text):

=item C<< $thing->stuff(I) >>

Further, I see nothing that implies that C<< C >> should be rendered as
"C" rather than "foo"

I don't know that I realized this was the change, although I remember talking
about it.  I thought the change was to fix C<< ... >> to require the spaces.
I am willing to believe that previously I openly and clearly agreed with this
change, but I'm not sure I do.

Is there anyone who can provide a reading of the spec to support the change?
Do you (David) remember what part of the spec convinced you?

-- 
rjbs

Fwd: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting codes)

[David E. Wheeler]

Comments?

Best,

David

Begin forwarded message:

> From: "Christopher J. Madsen via RT" 
> Date: March 15, 2010 10:09:12 AM PDT
> To: undisclosed-recipients:;
> Subject: [rt.cpan.org #55602] Bug #12239 was a mistake (nested formatting 
> codes) 
> Reply-To: bug-pod-sim...@rt.cpan.org
> 
> Mon Mar 15 13:09:05 2010: Request 55602 was acted upon.
> Transaction: Ticket created by CJM
>   Queue: Pod-Simple
> Subject: Bug #12239 was a mistake (nested formatting codes)
>   Broken in: 3.09
>Severity: Important
>   Owner: Nobody
>  Requestors: p...@cjmweb.net
>  Status: new
> Ticket https://rt.cpan.org/Ticket/Display.html?id=55602 >
> 
> 
> In bug #12239, Schwern expected "C<<< C<> >>>" to render as a
> literal "C<>", and you changed Pod-Simple to make that happen.  But
> I disagree with this interpretation of the spec, and consider it a
> serious loss of functionality.
> 
> Where exactly in perlpod or perlpodspec does it suggest that characters
> inside C<> are treated differently than those inside C<< >>?  As I read
> the spec, the only difference is in how the end of the code is located.
> Once you've located the end of the content (and stripped the mandatory
> whitespace from the C<< >> version), it's rendered the same.
> 
> That is, I claim that "C<<< C<> >>>" is a C<> nested inside a C<>,
> and Schwern should have written ""C<<< CZ<><> >>>" or "C<<<
> CE> >>>".
> 
> perlpod clearly states that "C<$a E=E $b>" is rendered as "$a
> <=> $b".  You're saying that
> 
>C<$a E=E $b>
>  C<< $a E=E $b >>
> 
> mean two completely different things, and I don't see where the spec
> supports that.
> 
> Otherwise, how am I supposed to write:
> 
> S<< C<< name => value >> >>
> 
> or 
> 
> S<< C<<  >> >>
>