I actually wrote this proposal several months ago, after an earlier discussion about difficulties with L<>. However, it appears that I never posted it anywhere. I would appreciate feedback on this idea. I think it would make L<> much more useable. The previous discussion is at http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2001-04/msg01017.html thanks, Ronald A new syntax for the L<> sequence in pod. Rationale: The current syntax for the L<> sequence in pod has several acknowledged drawbacks: First, there is ambiguity when linking to sections and items. Second, the characters |, /, and possibly " must be encoded with E<>. Third, it is not currently possible to specify an item within a section. Proposal: I propose the following new syntax for pod links: L< p<page> s<section> i<item> t<text> > At least one of p<>, s<>, or i<> must appear; t<> is optional. If p<> is not specified, the current page is assumed. Whitespace may be used around the attributes to improve readability; it will be ignored by the parser. This solution addresses all of the aforementioned drawbacks: There is no ambiguity as to which part of the link is a section and which is an item. Additionally, the parts may be specified in whatever order the author finds most appropriate for the given link. Any character may be used without being encoded. The characters < and > may be used via the same approach as the new C<< >> syntax: L< p<perlvar> i<< $< >> > Specifying both a section and an item is trivial. Additionally, further attributes may be added later without complicating the syntax (e.g. d<> for diagram, to link to a specific diagram in a page). The use of lowercase letters for the attributes avoids conflict and confusion with already existing sequences, such as I<> for italic and S<> for text with non-breaking spaces. Transition: Changing the syntax in this way raises the issue of transitioning from the current syntax. There are several approaches that could be taken: Outlaw the existing syntax, and force all pod documents and parsers to be updated. This approach is unreasonable, particularly because people will end up using new parsers on existing pod, or existing parsers on new pod. Deprecate the existing syntax, encourage the updating of all pod documents, and update the parsers to produce warnings for the old syntax. Accept both syntaxes as equally acceptable, while reminding authors that the new syntax is more flexible and less ambiguous. Either of the last two approaches would work well. Pod parsers should be able to easily distinguish between the existing and the new syntax. I personally prefer the solution of deprecating the existing syntax. That will lead to the cleanest state of affairs: having a single supported syntax for links in pod.
