develooper Front page | perl.perl5.porters | Postings from August 2001

Proposed new syntax for L<> in POD

Ronald J Kimball
August 21, 2001 07:39
Proposed new syntax for L<> in POD
Message ID:

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


A new syntax for the L<> sequence in pod.


The current syntax for the L<> sequence in pod has several acknowledged

  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.


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.


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. Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at | Group listing | About