1Pod::ParseLink(3pm)    Perl Programmers Reference Guide    Pod::ParseLink(3pm)
2
3
4

NAME

6       Pod::ParseLink - Parse an L<> formatting code in POD text
7

SYNOPSIS

9           use Pod::ParseLink;
10           my ($text, $inferred, $name, $section, $type) = parselink ($link);
11

DESCRIPTION

13       This module only provides a single function, parselink(), which takes
14       the text of an L<> formatting code and parses it.  It returns the
15       anchor text for the link (if any was given), the anchor text possibly
16       inferred from the name and section, the name or URL, the section if
17       any, and the type of link.  The type will be one of "url", "pod", or
18       "man", indicating a URL, a link to a POD page, or a link to a Unix
19       manual page.
20
21       Parsing is implemented per perlpodspec.  For backward compatibility,
22       links where there is no section and name contains spaces, or links
23       where the entirety of the link (except for the anchor text if given) is
24       enclosed in double-quotes are interpreted as links to a section
25       (L</section>).
26
27       The inferred anchor text is implemented per perlpodspec:
28
29           L<name>         =>  L<name|name>
30           L</section>     =>  L<"section"|/section>
31           L<name/section> =>  L<"section" in name|name/section>
32
33       The name may contain embedded E<> and Z<> formatting codes, and the
34       section, anchor text, and inferred anchor text may contain any
35       formatting codes.  Any double quotes around the section are removed as
36       part of the parsing, as is any leading or trailing whitespace.
37
38       If the text of the L<> escape is entirely enclosed in double quotes,
39       it's interpreted as a link to a section for backward compatibility.
40
41       No attempt is made to resolve formatting codes.  This must be done
42       after calling parselink() (since E<> formatting codes can be used to
43       escape characters that would otherwise be significant to the parser and
44       resolving them before parsing would result in an incorrect parse of a
45       formatting code like:
46
47           L<verticalE<verbar>barE<sol>slash>
48
49       which should be interpreted as a link to the "vertical|bar/slash" POD
50       page and not as a link to the "slash" section of the "bar" POD page
51       with an anchor text of "vertical".  Note that not only the anchor text
52       will need to have formatting codes expanded, but so will the target of
53       the link (to deal with E<> and Z<> formatting codes), and special
54       handling of the section may be necessary depending on whether the
55       translator wants to consider markup in sections to be significant when
56       resolving links.  See perlpodspec for more information.
57

SEE ALSO

59       Pod::Parser
60
61       The current version of this module is always available from its web
62       site at <http://www.eyrie.org/~eagle/software/podlators/>.
63

AUTHOR

65       Russ Allbery <rra@stanford.edu>.
66

68       Copyright 2001, 2008 Russ Allbery <rra@stanford.edu>.
69
70       This program is free software; you may redistribute it and/or modify it
71       under the same terms as Perl itself.
72
73
74
75perl v5.10.1                      2009-02-12               Pod::ParseLink(3pm)
Impressum