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, Xopen 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.


side note
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 
a name=anchorname.../a elements). Where Pod processors can control this 
behavior, they should use the first such anchor. That is, LFoo/Bar  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 a name=anchorname.../a 
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.
/side note

 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 shawnhco...@gmail.com [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.  Xopen  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: pod checker that finds missing internal links?

[Marc Green]

On Sun, Jan 29, 2012 at 9:31 AM, Ricardo Signes
perl@rjbs.manxome.orgwrote:

 * Patrice Dumas pertu...@free.fr [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 Xs sounds appealing to me.