Debian Codegraph @

upstream/opensuse-tumbleweed/man3/Pod::ParseLink.3pm

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "Pod::ParseLink 3pm"
61 .TH Pod::ParseLink 3pm 2026-03-09 "perl v5.42.1" "Perl Programmers Reference Guide"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 Pod::ParseLink \- Parse an L<> formatting code in POD text
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 3
71 \& use Pod::ParseLink;
72 \& my $link = get_link();
73 \& my ($text, $inferred, $name, $section, $type) = parselink($link);
74 .Ve
75 .SH DESCRIPTION
76 .IX Header "DESCRIPTION"
77 This module only provides a single function, \fBparselink()\fR, which takes the
78 text of an L<> formatting code and parses it. It returns the
79 anchor text for the link (if any was given), the anchor text possibly
80 inferred from the name and section, the name or URL, the section if any,
81 and the type of link. The type will be one of \f(CW\*(C`url\*(C'\fR, \f(CW\*(C`pod\*(C'\fR, or \f(CW\*(C`man\*(C'\fR,
82 indicating a URL, a link to a POD page, or a link to a Unix manual page.
83 .PP
84 Parsing is implemented per perlpodspec. For backward compatibility,
85 links where there is no section and name contains spaces, or links where the
86 entirety of the link (except for the anchor text if given) is enclosed in
87 double\-quotes are interpreted as links to a section (L</section>).
88 .PP
89 The inferred anchor text is implemented per perlpodspec:
90 .PP
91 .Vb 3
92 \& L<name> => L<name|name>
93 \& L</section> => L<"section"|/section>
94 \& L<name/section> => L<"section" in name|name/section>
95 .Ve
96 .PP
97 The name may contain embedded E<> and Z<> formatting codes,
98 and the section, anchor text, and inferred anchor text may contain any
99 formatting codes. Any double quotes around the section are removed as part
100 of the parsing, as is any leading or trailing whitespace.
101 .PP
102 If the text of the L<> escape is entirely enclosed in double
103 quotes, it\*(Aqs interpreted as a link to a section for backward
104 compatibility.
105 .PP
106 No attempt is made to resolve formatting codes. This must be done after
107 calling \fBparselink()\fR (since E<> formatting codes can be used to
108 escape characters that would otherwise be significant to the parser and
109 resolving them before parsing would result in an incorrect parse of a
110 formatting code like:
111 .PP
112 .Vb 1
113 \& L<verticalE<verbar>barE<sol>slash>
114 .Ve
115 .PP
116 which should be interpreted as a link to the \f(CW\*(C`vertical|bar/slash\*(C'\fR POD page
117 and not as a link to the \f(CW\*(C`slash\*(C'\fR section of the \f(CW\*(C`bar\*(C'\fR POD page with an
118 anchor text of \f(CW\*(C`vertical\*(C'\fR. Note that not only the anchor text will need to
119 have formatting codes expanded, but so will the target of the link (to deal
120 with E<> and Z<> formatting codes), and special handling of
121 the section may be necessary depending on whether the translator wants to
122 consider markup in sections to be significant when resolving links. See
123 perlpodspec for more information.
124 .SH AUTHOR
125 .IX Header "AUTHOR"
126 Russ Allbery <[email protected]>
127 .SH "COPYRIGHT AND LICENSE"
128 .IX Header "COPYRIGHT AND LICENSE"
129 Copyright 2001, 2008, 2009, 2014, 2018\-2019, 2022, 2024 Russ Allbery
130 <[email protected]>
131 .PP
132 This program is free software; you may redistribute it and/or modify it
133 under the same terms as Perl itself.
134 .SH "SEE ALSO"
135 .IX Header "SEE ALSO"
136 Pod::Parser
137 .PP
138 The current version of this module is always available from its web site at
139 <https://www.eyrie.org/~eagle/software/podlators/>.