AW: Fwd: [rt.cpan.org #74389] Pod::Simple::Pullparser get_title should ignore X<...>

[Marek Rouchal]

I agree... the content of X<...> is not visible text, so for

=head1 NAME
X

Pod::Simple should return "NAME" for the heading text, not
"NAME some text"

-Marek

-Ursprüngliche Nachricht-
Von: Karl Williamson [mailto:pub...@khwilliamson.com] 
Gesendet: Samstag, 28. Januar 2012 22:09
An: David E. Wheeler
Cc: pod-people@perl.org
Betreff: Re: Fwd: [rt.cpan.org #74389] Pod::Simple::Pullparser get_title
should ignore X<...>

On 01/25/2012 01:12 PM, David E. Wheeler wrote:
>
> Begin forwarded message:
>
>> Subject: [rt.cpan.org #74389] Pod::Simple::Pullparser get_title 
>> should ignore X<...>
>> Date: January 25, 2012 12:10:00 PM PST
>> Reply-To: bug-pod-sim...@rt.cpan.org
>>
>> With Pod::Simple 3.14.
>>
>> If a pod file has index entries after head:
>>
>> =head1 NAME
>> X
>>
>> Pod::Simple::Pullparser get_title expands 'Some entry' in the title.  
>> It seems to me that it should not, and instead should replace it with 
>> an empty string.  This  behaviour is also hinted in the pod
documentation.
>>
>> A look at the code in git makes me think that the same issue is still 
>> there (l. 363 and following all the text are used, X<>  text is not 
>> discarded).
>>
>> This kind of construct is not rare, for instance it is present in the 
>> main perl pod documentation.
>
> Opinions?
>
> Thanks,
>
> David
>
>

My opinion is that it should replace it with an empty string.

AW: pod checker that finds missing internal links?

[Marek Rouchal]

So your issues are with pod2html, less with Pod::Checker.
Which pod2html are you using? Likely the issues with
hyperlinks should be fixed there.

When looking at the current content of perfunc.pod, it 
looks like this:

3490 =item open FILEHANDLE,EXPR
3491 X X X X
3492 
3493 =item open FILEHANDLE,MODE,EXPR
3494 
3495 =item open FILEHANDLE,MODE,EXPR,LIST
3496 
3497 =item open FILEHANDLE,MODE,REFERENCE
3498 
3499 =item open FILEHANDLE
3500

Which means that if some other POD has L
in it, it will fail - except that we define that X
creates not only an index entry (for those formats and
tools that create an index - I did a humble attempt some
years ago with Marek::Pod::HTML), but also an anchor.

Question to all: neither perlpod nor perlpodspec seem to
be clear on whether X<...> should create an anchor at
this position for hyperlinks to reference to. I think
that would be a sensible thing to specify, since it does
not break any existing documents or their rendered
results, and it opens up opportunities to better link
between PODs, especially in target formats like HTML.

So what about adding a paragraph to perlpodspec (feel
free to improve the wording):

=item Ctopic nameE> -- an index entry

See the brief discussion in L.

This code is unusual in that most formatters completely discard
this code and its content.  Other formatters will render it with
invisible codes that can be used in building an index of
the current document.

+Formatters that support active hyperlinks (like HTML)
+should render a hyperlink anchor for C...E>
+index entries; such for example
+
+  =item open FILEHANDLE
+  X
+
+can be linked to by any of
+
+  L
+  L
+
=item CE> -- a null (zero-effect) formatting code


What do you think?

Cheers,

Marek


-Ursprüngliche Nachricht-
Von: 'Patrice Dumas' [mailto:pertu...@free.fr] 
Gesendet: Samstag, 28. Januar 2012 16:17
An: pod-people@perl.org
Betreff: Re: pod checker that finds missing internal links?

On Sat, Jan 28, 2012 at 03:38:48PM +0100, Marek Rouchal wrote:
> podchecker _does_ detect wrong internal links. If you put any of the 
> following links in the POD you quoted below, podchecker (as of 
> Pod-Parser-1.38 and higher) will flag it as an error:
> 
> L
> L<"open FILEHANDLE,MODE,EXPRESSION">
> L

I currently have perl 5.10.1 with Pod-Parser-1.37, I'll retest with
something more recent as soon as I have it.

> It is true that L will work OK, because perlfunc (at least at 
> the time when I wrote podchecker) contained many L although 
> the actual item was
> 
> =item function ARGUMENTS
> 
> and I did not want to flag dozens of errors for those.
> In other words: if the =item text matches /(\S+)\s+\S/ Then $1 is also 
> regarded as a valid reference for L<...>

I think that it is wrong, because there won't be an anchor created with that
name.

Also in all the files I read about Pod, it was nowhere said that the link
could be shortened, and instead, the link part of L<...> was always clearly
described.

> If you think that there should be something changed in podchecker, 
> then please provide a complete POD example, the podchecker output and 
> a statement on what should be changed and why.

I can only bring the result of the podchecker I have. On


=head1 aaa b

L


The result is OK.  But the corresponding HTML generated by pod2html is

aaa b
aaa


I think that podchecker should tel something here.

Also Pod::Simple should show an error too, in my opinion.

--
Pat

Re: pod checker that finds missing internal links?

['Patrice Dumas']

On Sun, Jan 29, 2012 at 09:26:31AM +0100, Marek Rouchal wrote:
> So your issues are with pod2html, less with Pod::Checker.
> Which pod2html are you using? Likely the issues with
> hyperlinks should be fixed there.

My feeling is that it is pod2html which is right and Pod::Checker
should find a missing link there.

> Question to all: neither perlpod nor perlpodspec seem to
> be clear on whether X<...> should create an anchor at
> this position for hyperlinks to reference to. I think
> that would be a sensible thing to specify, since it does
> not break any existing documents or their rendered
> results, and it opens up opportunities to better link
> between PODs, especially in target formats like HTML.

I think that it is wrong to use index entries as anchors, 
they are not the same from an editing point of view.  Index 
entries may be associated to sections where they are only 
related to incidentaly, and not the main subject, while an
anchor should be specific of a topic and be the main target 
for internal links.  For instance, X could appear in 
the section about binmode.  It is certainly not the best practice
since it is better to avoid ambiguous index entries, but 
still, it is not the same and multiple index entries are
definitely acceptable, while anchors should be unique.



As a side note, and in my opinion, having an anchor done for 
each =item in descriptions is not a very good idea since it could
lead to multiple anchors for a string, without a possibility to 
control which one has precedence.  (If it also appears in a =head* 
the =head* should certainly have precedence, for instance).
The specification instead states that the first wins, or the
precedence is left unspecified:

 This specification does not specify what behavior should be in the case of a 
given document having several things all seeming to produce the same section 
identifier (e.g., in HTML, several things all producing the same anchorname in 
... elements). Where Pod processors can control this 
behavior, they should use the first such anchor. That is, L  refers to 
the first "Bar" section in Foo.

 But for some processors/formats this cannot be easily controlled; as with the 
HTML example, the behavior of multiple ambiguous ... 
is most easily just left up to browsers to decide.

In that setting, not being able to format a description entry
without doing an anchor seems already wrong to me.


> What do you think?

My personal opinion (and it shouldn't be really surprising, since I 
also wrote a mail proposing a new command for anchors...) is that 
index entries and anchors are different, serve a different editing 
purpose and should be specified with different commands.

-- 
Pat

Re: an 'anchor' command is missing from Pod

[Ricardo Signes]

* Shawn H Corey  [2012-01-28T08:41:35]
> On 12-01-27 11:14 PM, Ricardo Signes wrote:
> >You're thinking of X<>  -- Z<>  should always be empty, and is a zero-effect
> >code.  X  is used to help indexing.  It isn't how perldoc -f works,
> >though.
> 
> No, I've encountered unempty Z<> in some PODs.

Then you have seen mistakes.

-- 
rjbs


signature.asc
Description: Digital signature

Re: Fwd: [rt.cpan.org #74389] Pod::Simple::Pullparser get_title should ignore X<...>

[Ricardo Signes]

* Marek Rouchal  [2012-01-29T03:05:50]
> I agree... the content of X<...> is not visible text, so for
> 
> =head1 NAME
> X
> 
> Pod::Simple should return "NAME" for the heading text, not
> "NAME some text"

And "NAME" and not "NAME "

It should probably not just become an empty string, but it should be collapse
whitespace around it, so pathological cases like:

=head1 NAME X THIS X TUNE
X

...should be "NAME THIS TUNE"

But in the simpler case, I think that "NAME" and not "NAME " is actually likely
to come up.

-- 
rjbs


signature.asc
Description: Digital signature

Re: pod checker that finds missing internal links?

[Ricardo Signes]

* Patrice Dumas  [2012-01-27T18:15:17]
> More precisely, podchecker coming with perl 5.10 gets it wrong, it 
> finds multiple defined labels because it takes only into account the 
> beginning of an =item, for example

podchecker is in the process of being replaced with Pod::Simple-based code.
Hopefully that will help.

Maybe Marc Green can comment...

-- 
rjbs


signature.asc
Description: Digital signature

AW: pod checker that finds missing internal links?

[Marek Rouchal]

It is nice that you are sharing your thoughts with us -
but frankly speaking I do not see any concrete point.
L<> and =head/=item may not be the perfect solution,
but it is all that's been there for years, and changing
this (by introducing a new anchor syntax) would require 
basically to rewrite all POD. Or to provide a semi-perfect 
converter... neither seems very appealing to me.
And I dare to disagree with your thoughts on index
entries and anchors - which isn't really surprising, too.
People are used to writing docs clearly, not "incidentaly";
and the same way you dislike X<> being an anchor, others
may actually like the idea; and hey - you are not forced
to link against them from elsewhere, are you?
So perhaps the concepts of POD are not perfect, but they
have been practical for a long time.
So show a patch that corrects things along the lines that
you wrote, which might be more convincing.

-Marek

-Ursprüngliche Nachricht-
Von: 'Patrice Dumas' [mailto:pertu...@free.fr] 
Gesendet: Sonntag, 29. Januar 2012 10:33
An: pod-people@perl.org
Betreff: Re: pod checker that finds missing internal links?

On Sun, Jan 29, 2012 at 09:26:31AM +0100, Marek Rouchal wrote:
> So your issues are with pod2html, less with Pod::Checker.
> Which pod2html are you using? Likely the issues with hyperlinks should 
> be fixed there.

My feeling is that it is pod2html which is right and Pod::Checker should
find a missing link there.

> Question to all: neither perlpod nor perlpodspec seem to be clear on 
> whether X<...> should create an anchor at this position for hyperlinks 
> to reference to. I think that would be a sensible thing to specify, 
> since it does not break any existing documents or their rendered 
> results, and it opens up opportunities to better link between PODs, 
> especially in target formats like HTML.

I think that it is wrong to use index entries as anchors, they are not the
same from an editing point of view.  Index entries may be associated to
sections where they are only related to incidentaly, and not the main
subject, while an anchor should be specific of a topic and be the main
target for internal links.  For instance, X could appear in the
section about binmode.  It is certainly not the best practice since it is
better to avoid ambiguous index entries, but still, it is not the same and
multiple index entries are definitely acceptable, while anchors should be
unique.



As a side note, and in my opinion, having an anchor done for each =item in
descriptions is not a very good idea since it could lead to multiple anchors
for a string, without a possibility to control which one has precedence.
(If it also appears in a =head* the =head* should certainly have precedence,
for instance).
The specification instead states that the first wins, or the precedence is
left unspecified:

 This specification does not specify what behavior should be in the case of
a given document having several things all seeming to produce the same
section identifier (e.g., in HTML, several things all producing the same
anchorname in ... elements). Where Pod processors
can control this behavior, they should use the first such anchor. That is,
L  refers to the first "Bar" section in Foo.

 But for some processors/formats this cannot be easily controlled; as with
the HTML example, the behavior of multiple ambiguous ... is most easily just left up to browsers to decide.

In that setting, not being able to format a description entry without doing
an anchor seems already wrong to me.


> What do you think?

My personal opinion (and it shouldn't be really surprising, since I also
wrote a mail proposing a new command for anchors...) is that index entries
and anchors are different, serve a different editing purpose and should be
specified with different commands.

--
Pat

Re: AW: pod checker that finds missing internal links?

[Shawn H Corey]

On 12-01-29 10:29 AM, Marek Rouchal wrote:

and the same way you dislike X<>  being an anchor


X<> has to be an anchor for the index, not that any POD parser creates 
indexes.



--
Just my 0.0002 million dollars worth,
  Shawn

Programming is as much about organization and communication
as it is about coding.

Strength is not a measure of the body.
It's a measure of the heart.

Re: pod checker that finds missing internal links?

['Patrice Dumas']

On Sun, Jan 29, 2012 at 04:29:32PM +0100, Marek Rouchal wrote:
> It is nice that you are sharing your thoughts with us -
> but frankly speaking I do not see any concrete point.
> L<> and =head/=item may not be the perfect solution,
> but it is all that's been there for years, and changing
> this (by introducing a new anchor syntax) would require 
> basically to rewrite all POD. Or to provide a semi-perfect 

Certainly not.  The new anchor would be an addition.  In case
it was not clear, the rant about =head/=item possible inconsitencies
was a side note, maybe trying to convey my ideas on a suboptimal
design of the language that I think should not be carried on
in further changes in the language.

And I think that the L<> semantics is powerful enough to do
any kind of link.

> and the same way you dislike X<> being an anchor, others
> may actually like the idea; and hey - you are not forced
> to link against them from elsewhere, are you?

I do not disagree on X being rendered as an anchor, but
it should be an index entry anchor, not a label anchor.

> So perhaps the concepts of POD are not perfect, but they
> have been practical for a long time.

But maybe there is room for improvement?

> So show a patch that corrects things along the lines that
> you wrote, which might be more convincing.

I am ready to do some patches, but that's not the point here.
There are design issues too, on the language itself.

-- 
Pat

Re: pod checker that finds missing internal links?

[Marc Green]

On Sun, Jan 29, 2012 at 9:31 AM, Ricardo Signes
wrote:

> * Patrice Dumas  [2012-01-27T18:15:17]
> > More precisely, podchecker coming with perl 5.10 gets it wrong, it
> > finds multiple defined labels because it takes only into account the
> > beginning of an =item, for example
>
> podchecker is in the process of being replaced with Pod::Simple-based code.
> Hopefully that will help.
>
> Maybe Marc Green can comment...
>
>
If I am understanding the situation correctly, the problem is that
Pod::Checker does not issue an "unresolved internal link" warning when the
target of an L<> formatting code does not exist in the document *if* the
target is the prefix of another node in the document (i.e., is a prefix of
a =head or =item directive).

This functionality still exists in the Pod::Simple-based code, so the issue
won't be taken care of when Pod::Checker is replaced. Thus, we need to
decide whether or not the "L<> target shortcut" behavior should stay (and
perhaps be documented better) or go.

I think Marek suggested that X<> can serve as a way to create an anchor
that can be linked to as a fix for the problem, because if that
functionality is implemented, then the "L<> target shortcut" behavior can
be removed.

As Shawn said, there aren't many (if any) POD parsers that create indexes,
so X<> is not being used as much as the designer of the formatting code
thought it would be. (Note that I may be mistaken here. I am talking from
limited personal experience, so let me know if this is not the case.) Thus,
letting L<> targets link to X<>s sounds appealing to me.

Re: [rt.cpan.org #74389] Pod::Simple::Pullparser get_title should ignore X<...>

[David E. Wheeler]

On Jan 29, 2012, at 6:29 AM, Ricardo Signes wrote:

> And "NAME" and not "NAME "
> 
> It should probably not just become an empty string, but it should be collapse
> whitespace around it, so pathological cases like:
> 
> =head1 NAME X THIS X TUNE
> X
> 
> ...should be "NAME THIS TUNE"
> 
> But in the simpler case, I think that "NAME" and not "NAME " is actually 
> likely
> to come up.

Okay, so if I follow this thread correctly, the upshot is that:

• Pod::Simple::HTML needs to be fixed so that it does not include the contents 
of X<>
• The parser overall should be adjusted to remove superfluous whitespace

Correct?

David

Re: pod checker that finds missing internal links?

[Patrice Dumas]

On Sun, Jan 29, 2012 at 03:14:16PM -0500, Marc Green wrote:
> >
> If I am understanding the situation correctly, the problem is that
> Pod::Checker does not issue an "unresolved internal link" warning when the
> target of an L<> formatting code does not exist in the document *if* the
> target is the prefix of another node in the document (i.e., is a prefix of
> a =head or =item directive).

Exactly.

> This functionality still exists in the Pod::Simple-based code, so the issue
> won't be taken care of when Pod::Checker is replaced. Thus, we need to
> decide whether or not the "L<> target shortcut" behavior should stay (and
> perhaps be documented better) or go.

Yep.  My opinion is that it is better to have it go, it seems wrong to me.
But I guess that my opinion does not count that much ;-).

> I think Marek suggested that X<> can serve as a way to create an anchor
> that can be linked to as a fix for the problem, because if that
> functionality is implemented, then the "L<> target shortcut" behavior can
> be removed.
> 
> As Shawn said, there aren't many (if any) POD parsers that create indexes,
> so X<> is not being used as much as the designer of the formatting code
> thought it would be. (Note that I may be mistaken here. I am talking from
> limited personal experience, so let me know if this is not the case.) Thus,
> letting L<> targets link to X<>s sounds appealing to me.

Then, in my opinion, in that case the pod specification should be changed 
such that X<..> is not referred to as index entries, but anchors 
(or labels).  I think that it certainly makes more sense to have labels 
than index entries in Pod since there is no command to actually print the 
index while there is a good support for any kind of links with L<>.  Still,
I think that it should be one or the other since index entries and anchors
are really distinct things.  

In fact, in general, anchors could be considered automatically as index 
entries, but the reverse is not true, as I argument in another mail.
Thus it would not be that wrong if converters always automatically added 
index entries where there are link targets, in =head, =item 
(and X<..>).



NOTE: in the converter to Texinfo I am doing, I used X<..> to do index 
entries, though the command that prints the index is not issued.  In 
any case, the converter is not released yet, so it doesn't count...

I guess that candidate converters that could use X<..> are converters to
formats where index entries exist, such as DocBook and maybe LaTeX.

-- 
Pat

Re: pod checker that finds missing internal links?

[Russ Allbery]

Patrice Dumas  writes:

> Then, in my opinion, in that case the pod specification should be
> changed such that X<..> is not referred to as index entries, but anchors
> (or labels).  I think that it certainly makes more sense to have labels
> than index entries in Pod since there is no command to actually print
> the index while there is a good support for any kind of links with L<>.
> Still, I think that it should be one or the other since index entries
> and anchors are really distinct things.

I believe roffitall in the Perl source does attempt to generate an index.

> I guess that candidate converters that could use X<..> are converters to
> formats where index entries exist, such as DocBook and maybe LaTeX.

And *roff, although admittedly there probably aren't that many people who
use Pod::Man to generate printable documents rather than the online man
pages.

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

Re: pod checker that finds missing internal links?

[Karl Williamson]

On 01/29/2012 05:31 PM, Russ Allbery wrote:

Patrice Dumas  writes:


Then, in my opinion, in that case the pod specification should be
changed such that X<..>  is not referred to as index entries, but anchors
(or labels).  I think that it certainly makes more sense to have labels
than index entries in Pod since there is no command to actually print
the index while there is a good support for any kind of links with L<>.
Still, I think that it should be one or the other since index entries
and anchors are really distinct things.


I believe roffitall in the Perl source does attempt to generate an index.


I guess that candidate converters that could use X<..>  are converters to
formats where index entries exist, such as DocBook and maybe LaTeX.


And *roff, although admittedly there probably aren't that many people who
use Pod::Man to generate printable documents rather than the online man
pages.



I believe that O'Reilly publishing uses X<> to help generate their 
indices.  I could find out for sure if people desire that info.