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<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
