On Tue, 13 Apr 2010, David E. Wheeler wrote:
> On Apr 13, 2010, at 11:18 AM, Jan Dubois wrote:
>
> > No, it doesn't. The X<> escapes are still part of the head2 element. It
> > could
> > have been written like this:
> >
> > =head2 Yada Yada Operator X<...> X<... operator> X<yada yada operator>
> >
> > Except that makes it harder to read if you just read the
> > unprocessed pod file directly.
> >
> > search.cpan.org is just using an old POD formatter. I fixed the anchor
> > generation for multi-line headX directives for Pod::Html here:
> >
> > http://perl5.git.perl.org/perl.git/commitdiff/d0ff30b50
> >
> > Seems to work fine for the current docs:
> >
> >
> > http://docs.activestate.com/activeperl/5.12/lib/pods/perlop.html#yada_yada_operator
>
> Should that not use the entire header for the location name? Something like
> #Yada_Yada_Operator_operator_yada_yada_operator?
No, all X<> elements are explicitly stripped by the de-podding, which is
done before turning it into an anchor. In addition all trailing whitespace
is trimmed too.
> Ah. Then this change needs to be made to Pod::Simple, too.
>
> pod-people, does it make sense to allow headers to be on more than one line,
> e.g.,
>
> =head2 Yada Yada Operator
> X<...> X<... operator> X<yada yada operator>
This is standard POD syntax for "command paragraphs". There is nothing
special about the headX commands that should disallow it. Amusingly
enough the section in perlpod.pod that defines this starts like this:
=head2 Command Paragraph
X<POD, command>
Also using multi-line =item paragraphs with X<> escapes on additional
lines has been used by perlfunc.pod since some 5.8.x release. If you
look closely then you'll see that my patch to fix the multi-line
de-podding in Pod::Html is from 2006, and it was indeed triggered
by this exact issue.
Cheers,
-Jan
