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<open> 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, L<Foo/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
