Re: Yada Yada Operator Link Broken
On Apr 13, 2010, at 11:54 AM, Graham Barr wrote: >> Should that not use the entire header for the location name? Something like >> #Yada_Yada_Operator_operator_yada_yada_operator? > > no. The content of the X< > in not visible to the end user so using it to > generate the anchor would be confusing IMO Makes sense to me. >> Ah. Then this change needs to be made to Pod::Simple, too. > > Pod::Simple currently generates an anchor of #Yada_Yada_Operator___ > > I think what needs to happen is that the spaces around the X<> need to be > removed, or maybe section_name_tidy just needs to remove trailing _'s Yes, perhaps removing trailing whitespace as Jan suggested. I'll file a bug report. >> 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 > > POD is paragraph based so that whole paragraph is the head2, I do not think > we could (or should) go changing that now. Great. Best, David
Re: Yada Yada Operator Link Broken
On Apr 13, 2010, at 1:32 PM, 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 >> >> 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. The content of the X< > in not visible to the end user so using it to generate the anchor would be confusing IMO > Ah. Then this change needs to be made to Pod::Simple, too. Pod::Simple currently generates an anchor of #Yada_Yada_Operator___ I think what needs to happen is that the spaces around the X<> need to be removed, or maybe section_name_tidy just needs to remove trailing _'s > > 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 POD is paragraph based so that whole paragraph is the head2, I do not think we could (or should) go changing that now. Graham.
RE: Yada Yada Operator Link Broken
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 > > > > 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 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 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
Re: Yada Yada Operator Link Broken
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 > > 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? 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 Thanks, David
