local-lib5/man/man3/Pod::ParseLink.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Pod::ParseLink 3"
 132 .TH Pod::ParseLink 3 "2008-10-05" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Pod::ParseLink \- Parse an L<> formatting code in POD text
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 2
 138 \&    use Pod::ParseLink;
 139 \&    my ($text, $inferred, $name, $section, $type) = parselink ($link);
 140 .Ve
 141 .SH "DESCRIPTION"
 142 .IX Header "DESCRIPTION"
 143 This module only provides a single function, \fIparselink()\fR, which takes the
 144 text of an L<> formatting code and parses it.  It returns the
 145 anchor text for the link (if any was given), the anchor text possibly
 146 inferred from the name and section, the name or \s-1URL\s0, the section if any,
 147 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,
 148 indicating a \s-1URL\s0, a link to a \s-1POD\s0 page, or a link to a Unix manual page.
 149 .PP
 150 Parsing is implemented per perlpodspec.  For backward compatibility,
 151 links where there is no section and name contains spaces, or links where the
 152 entirety of the link (except for the anchor text if given) is enclosed in
 153 double-quotes are interpreted as links to a section (L</section>).
 154 .PP
 155 The inferred anchor text is implemented per perlpodspec:
 156 .PP
 157 .Vb 3
 158 \&    L<name>         =>  L<name|name>
 159 \&    L</section>     =>  L<"section"|/section>
 160 \&    L<name/section> =>  L<"section" in name|name/section>
 161 .Ve
 162 .PP
 163 The name may contain embedded E<> and Z<> formatting codes,
 164 and the section, anchor text, and inferred anchor text may contain any
 165 formatting codes.  Any double quotes around the section are removed as part
 166 of the parsing, as is any leading or trailing whitespace.
 167 .PP
 168 If the text of the L<> escape is entirely enclosed in double
 169 quotes, it's interpreted as a link to a section for backward
 170 compatibility.
 171 .PP
 172 No attempt is made to resolve formatting codes.  This must be done after
 173 calling \fIparselink()\fR (since E<> formatting codes can be used to
 174 escape characters that would otherwise be significant to the parser and
 175 resolving them before parsing would result in an incorrect parse of a
 176 formatting code like:
 177 .PP
 178 .Vb 1
 179 \&    L<verticalE<verbar>barE<sol>slash>
 180 .Ve
 181 .PP
 182 which should be interpreted as a link to the \f(CW\*(C`vertical|bar/slash\*(C'\fR \s-1POD\s0 page
 183 and not as a link to the \f(CW\*(C`slash\*(C'\fR section of the \f(CW\*(C`bar\*(C'\fR \s-1POD\s0 page with an
 184 anchor text of \f(CW\*(C`vertical\*(C'\fR.  Note that not only the anchor text will need to
 185 have formatting codes expanded, but so will the target of the link (to deal
 186 with E<> and Z<> formatting codes), and special handling of
 187 the section may be necessary depending on whether the translator wants to
 188 consider markup in sections to be significant when resolving links.  See
 189 perlpodspec for more information.
 190 .SH "SEE ALSO"
 191 .IX Header "SEE ALSO"
 192 Pod::Parser
 193 .PP
 194 The current version of this module is always available from its web site at
 195 <http://www.eyrie.org/~eagle/software/podlators/>.
 196 .SH "AUTHOR"
 197 .IX Header "AUTHOR"
 198 Russ Allbery <rra@stanford.edu>.
 199 .SH "COPYRIGHT AND LICENSE"
 200 .IX Header "COPYRIGHT AND LICENSE"
 201 Copyright 2001, 2008 Russ Allbery <rra@stanford.edu>.
 202 .PP
 203 This program is free software; you may redistribute it and/or modify it
 204 under the same terms as Perl itself.