|
As you can tell from a glance at perlpod,
the L<...> code is the most complex of the Pod formatting codes. The points below will
hopefully clarify what it means and how processors should deal with it.
-
In parsing an L<...> code, Pod parsers must distinguish at least four attributes:
- First:
- The link-text. If there is none, this must be undef. (E.g., in "L<Perl
Functions|perlfunc>", the link-text is "Perl Functions". In
"L<Time::HiRes>" and even "L<|Time::HiRes>", there is no
link text. Note that link text may contain formatting.)
- Second:
- The possibly inferred link-text -- i.e., if there was no real link text, then this is
the text that we'll infer in its place. (E.g., for "L<Getopt::Std>", the
inferred link text is "Getopt::Std".)
- Third:
- The name or URL, or undef if none. (E.g., in "L<Perl Functions|perlfunc>",
the name -- also sometimes called the page -- is "perlfunc". In
"L</CAVEATS>", the name is undef.)
- Fourth:
- The section (AKA "item" in older perlpods), or undef if none. E.g., in Getopt::Std/DESCRIPTION, "DESCRIPTION"
is the section. (Note that this is not the same as a manpage section like the
"5" in "man 5 crontab". "Section Foo" in the Pod sense
means the part of the text that's introduced by the heading or item whose text is "Foo".)
Pod parsers may also note additional attributes including:
- Fifth:
- A flag for whether item 3 (if present) is a URL (like "http://lists.perl.org"
is), in which case there should be no section attribute; a Pod name (like "perldoc"
and "Getopt::Std" are); or possibly a man page name (like
"crontab(5)" is).
- Sixth:
- The raw original L<...> content, before text is split on "|",
"/", etc, and before E<...> codes are expanded.
(The above were numbered only for concise reference below. It is not a requirement that
these be passed as an actual list or array.)
For example:
L<Foo::Bar>
=> undef, # link text
"Foo::Bar", # possibly inferred link text
"Foo::Bar", # name
undef, # section
'pod', # what sort of link
"Foo::Bar" # original content
L<Perlport's section on NL's|perlport/Newlines>
=> "Perlport's section on NL's", # link text
"Perlport's section on NL's", # possibly inferred link text
"perlport", # name
"Newlines", # section
'pod', # what sort of link
"Perlport's section on NL's|perlport/Newlines" # orig. content
L<perlport/Newlines>
=> undef, # link text
'"Newlines" in perlport', # possibly inferred link text
"perlport", # name
"Newlines", # section
'pod', # what sort of link
"perlport/Newlines" # original content
L<crontab(5)/"DESCRIPTION">
=> undef, # link text
'"DESCRIPTION" in crontab(5)', # possibly inferred link text
"crontab(5)", # name
"DESCRIPTION", # section
'man', # what sort of link
'crontab(5)/"DESCRIPTION"' # original content
L</Object Attributes>
=> undef, # link text
'"Object Attributes"', # possibly inferred link text
undef, # name
"Object Attributes", # section
'pod', # what sort of link
"/Object Attributes" # original content
L<http://www.perl.org/>
=> undef, # link text
"http://www.perl.org/", # possibly inferred link text
"http://www.perl.org/", # name
undef, # section
'url', # what sort of link
"http://www.perl.org/" # original content
|
|
Note that you can distinguish URL-links from anything else by the fact that they match m/\A\w+:[^:\s]\S*\z/.
So L<http://www.perl.com> is a URL, but L<HTTP::Response>
isn't.
-
In case of L<...> codes with no "text|" part in them, older formatters
have exhibited great variation in actually displaying the link or cross reference. For
example, L<crontab(5)> would render as "the crontab(5) manpage",
or "in the crontab(5) manpage" or just "crontab(5)".
Pod processors must now treat "text|"-less links as follows:
L<name> => L<name|name>
L</section> => L<"section"|/section>
L<name/section> => L<"section" in name|name/section>
|
|
-
Note that section names might contain markup. I.e., if a section starts with:
=head2 About the C<-M> Operator
|
|
or with:
=item About the C<-M> Operator
|
|
then a link to it would look like this:
L<somedoc/About the C<-M> Operator>
|
|
Formatters may choose to ignore the markup for purposes of resolving the link and use
only the renderable characters in the section name, as in:
<h1><a name="About_the_-M_Operator">About the <code>-M</code>
Operator</h1>
...
<a href="somedoc#About_the_-M_Operator">About the <code>-M</code>
Operator" in somedoc</a>
|
|
-
Previous versions of perlpod distinguished L<name/"section">
links from L<name/item> links (and their targets). These have been merged
syntactically and semantically in the current specification, and section can refer
either to a "=headn Heading Content" command or to a "=item Item
Content" command. 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.
- Authors wanting to link to a particular (absolute) URL, must do so only with
"L<scheme:...>" codes (like L<http://www.perl.org>), and must not
attempt "L<Some Site Name|scheme:...>" codes. This restriction avoids many
problems in parsing and rendering L<...> codes.
-
In a L<text|...> code, text may contain formatting codes for
formatting or for E<...> escapes, as in:
For L<...> codes without a "name|" part, only E<...>
and Z<> codes may occur -- no other formatting codes. That is, authors
should not use "L<B<Foo::Bar>>".
Note, however, that formatting codes and Z<>'s can occur in any and all parts of an
L<...> (i.e., in name, section, text, and url).
Authors must not nest L<...> codes. For example, "L<The L<Foo::Bar>
man page>" should be treated as an error.
-
Note that Pod authors may use formatting codes inside the "text" part of
"L<text|name>" (and so on for L<text|/"sec">).
In other words, this is valid:
Go read L<the docs on C<$.>|perlvar/"$.">
|
|
Some output formats that do allow rendering "L<...>" codes as hypertext,
might not allow the link-text to be formatted; in that case, formatters will have to just
ignore that formatting.
- At time of writing,
L<name> values are of two types: either the name of
a Pod page like L<Foo::Bar> (which might be a real Perl module or program
in an @INC / PATH directory, or a .pod file in those places); or the name of a UNIX man
page, like L<crontab(5)>. In theory, L<chmod> in
ambiguous between a Pod page called "chmod", or the Unix man page "chmod"
(in whatever man-section). However, the presence of a string in parens, as in
"crontab(5)", is sufficient to signal that what is being discussed is not a Pod
page, and so is presumably a UNIX man page. The distinction is of no importance to many Pod
processors, but some processors that render to hypertext formats may need to distinguish
them in order to know how to render a given L<foo> code.
- Previous versions of perlpod allowed for a
L<section> syntax (as in
"L<Object Attributes>"), which was not easily distinguishable
from L<name> syntax. This syntax is no longer in the specification, and
has been replaced by the L<"section"> syntax (where the quotes
were formerly optional). Pod parsers should tolerate the L<section>
syntax, for a while at least. The suggested heuristic for distinguishing L<section>
from L<name> is that if it contains any whitespace, it's a section.
Pod processors may warn about this being deprecated syntax.
|
|
