local-lib5/man/man3/Pod::Escapes.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::Escapes 3"
 132 .TH Pod::Escapes 3 "2004-05-07" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Pod::Escapes \-\- for resolving Pod E<...> sequences
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 7
 138 \&  use Pod::Escapes qw(e2char);
 139 \&  ...la la la, parsing POD, la la la...
 140 \&  $text = e2char($e_node\->label);
 141 \&  unless(defined $text) {
 142 \&    print "Unknown E sequence \e"", $e_node\->label, "\e"!";
 143 \&  }
 144 \&  ...else print/interpolate $text...
 145 .Ve
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 This module provides things that are useful in decoding
 149 Pod E<...> sequences.  Presumably, it should be used
 150 only by Pod parsers and/or formatters.
 151 .PP
 152 By default, Pod::Escapes exports none of its symbols.  But
 153 you can request any of them to be exported.
 154 Either request them individually, as with
 155 \&\f(CW\*(C`use Pod::Escapes qw(symbolname symbolname2...);\*(C'\fR,
 156 or you can do \f(CW\*(C`use Pod::Escapes qw(:ALL);\*(C'\fR to get all
 157 exportable symbols.
 158 .SH "GOODIES"
 159 .IX Header "GOODIES"
 160 .IP "e2char($e_content)" 4
 161 .IX Item "e2char($e_content)"
 162 Given a name or number that could appear in a
 163 \&\f(CW\*(C`E<name_or_num>\*(C'\fR sequence, this returns the string that
 164 it stands for.  For example, \f(CW\*(C`e2char('sol')\*(C'\fR, \f(CW\*(C`e2char('47')\*(C'\fR,
 165 \&\f(CW\*(C`e2char('0x2F')\*(C'\fR, and \f(CW\*(C`e2char('057')\*(C'\fR all return \*(L"/\*(R",
 166 because \f(CW\*(C`E<sol>\*(C'\fR, \f(CW\*(C`E<47>\*(C'\fR, \f(CW\*(C`E<0x2f>\*(C'\fR,
 167 and \f(CW\*(C`E<057>\*(C'\fR, all mean \*(L"/\*(R".  If
 168 the name has no known value (as with a name of \*(L"qacute\*(R") or is
 169 syntactally invalid (as with a name of \*(L"1/4\*(R"), this returns undef.
 170 .IP "e2charnum($e_content)" 4
 171 .IX Item "e2charnum($e_content)"
 172 Given a name or number that could appear in a
 173 \&\f(CW\*(C`E<name_or_num>\*(C'\fR sequence, this returns the number of
 174 the Unicode character that this stands for.  For example,
 175 \&\f(CW\*(C`e2char('sol')\*(C'\fR, \f(CW\*(C`e2char('47')\*(C'\fR,
 176 \&\f(CW\*(C`e2char('0x2F')\*(C'\fR, and \f(CW\*(C`e2char('057')\*(C'\fR all return 47,
 177 because \f(CW\*(C`E<sol>\*(C'\fR, \f(CW\*(C`E<47>\*(C'\fR, \f(CW\*(C`E<0x2f>\*(C'\fR,
 178 and \f(CW\*(C`E<057>\*(C'\fR, all mean \*(L"/\*(R", whose Unicode number is 47.  If
 179 the name has no known value (as with a name of \*(L"qacute\*(R") or is
 180 syntactally invalid (as with a name of \*(L"1/4\*(R"), this returns undef.
 181 .IP "$Name2character{\fIname\fR}" 4
 182 .IX Item "$Name2character{name}"
 183 Maps from names (as in \f(CW\*(C`E<\f(CIname\f(CW>\*(C'\fR) like \*(L"eacute\*(R" or \*(L"sol\*(R"
 184 to the string that each stands for.  Note that this does not
 185 include numerics (like \*(L"64\*(R" or \*(L"x981c\*(R").  Under old Perl versions
 186 (before 5.7) you get a \*(L"?\*(R" in place of characters whose Unicode
 187 value is over 255.
 188 .IP "$Name2character_number{\fIname\fR}" 4
 189 .IX Item "$Name2character_number{name}"
 190 Maps from names (as in \f(CW\*(C`E<\f(CIname\f(CW>\*(C'\fR) like \*(L"eacute\*(R" or \*(L"sol\*(R"
 191 to the Unicode value that each stands for.  For example,
 192 \&\f(CW$Name2character_number{'eacute'}\fR is 201, and
 193 \&\f(CW$Name2character_number{'eacute'}\fR is 8364.  You get the correct
 194 Unicode value, regardless of the version of Perl you're using \*(--
 195 which differs from \f(CW%Name2character\fR's behavior under pre\-5.7 Perls.
 196 .Sp
 197 Note that this hash does not
 198 include numerics (like \*(L"64\*(R" or \*(L"x981c\*(R").
 199 .IP "$Latin1Code_to_fallback{\fIinteger\fR}" 4
 200 .IX Item "$Latin1Code_to_fallback{integer}"
 201 For numbers in the range 160 (0x00A0) to 255 (0x00FF), this maps
 202 from the character code for a Latin\-1 character (like 233 for
 203 lowercase e\-acute) to the US-ASCII character that best aproximates
 204 it (like \*(L"e\*(R").  You may find this useful if you are rendering
 205 \&\s-1POD\s0 in a format that you think deals well only with US-ASCII
 206 characters.
 207 .IP "$Latin1Char_to_fallback{\fIcharacter\fR}" 4
 208 .IX Item "$Latin1Char_to_fallback{character}"
 209 Just as above, but maps from characters (like \*(L"\exE9\*(R",
 210 lowercase e\-acute) to characters (like \*(L"e\*(R").
 211 .IP "$Code2USASCII{\fIinteger\fR}" 4
 212 .IX Item "$Code2USASCII{integer}"
 213 This maps from US-ASCII codes (like 32) to the corresponding
 214 character (like space, for 32).  Only characters 32 to 126 are
 215 defined.  This is meant for use by \f(CW\*(C`e2char($x)\*(C'\fR when it senses
 216 that it's running on a non-ASCII platform (where chr(32) doesn't
 217 get you a space \*(-- but \f(CW$Code2USASCII\fR{32} will).  It's
 218 documented here just in case you might find it useful.
 219 .SH "CAVEATS"
 220 .IX Header "CAVEATS"
 221 On Perl versions before 5.7, Unicode characters with a value
 222 over 255 (like lambda or emdash) can't be conveyed.  This
 223 module does work under such early Perl versions, but in the
 224 place of each such character, you get a \*(L"?\*(R".  Latin\-1
 225 characters (characters 160\-255) are unaffected.
 226 .PP
 227 Under \s-1EBCDIC\s0 platforms, \f(CW\*(C`e2char($n)\*(C'\fR may not always be the
 228 same as \f(CW\*(C`chr(e2charnum($n))\*(C'\fR, and ditto for
 229 \&\f(CW$Name2character{$name}\fR and
 230 \&\f(CW\*(C`chr($Name2character_number{$name})\*(C'\fR.
 231 .SH "SEE ALSO"
 232 .IX Header "SEE ALSO"
 233 perlpod
 234 .PP
 235 perlpodspec
 236 .PP
 237 Text::Unidecode
 238 .SH "COPYRIGHT AND DISCLAIMERS"
 239 .IX Header "COPYRIGHT AND DISCLAIMERS"
 240 Copyright (c) 2001\-2004 Sean M. Burke.  All rights reserved.
 241 .PP
 242 This library is free software; you can redistribute it and/or modify
 243 it under the same terms as Perl itself.
 244 .PP
 245 This program is distributed in the hope that it will be useful, but
 246 without any warranty; without even the implied warranty of
 247 merchantability or fitness for a particular purpose.
 248 .PP
 249 Portions of the data tables in this module are derived from the
 250 entity declarations in the W3C \s-1XHTML\s0 specification.
 251 .PP
 252 Currently (October 2001), that's these three:
 253 .PP
 254 .Vb 3
 255 \& http://www.w3.org/TR/xhtml1/DTD/xhtml\-lat1.ent
 256 \& http://www.w3.org/TR/xhtml1/DTD/xhtml\-special.ent
 257 \& http://www.w3.org/TR/xhtml1/DTD/xhtml\-symbol.ent
 258 .Ve
 259 .SH "AUTHOR"
 260 .IX Header "AUTHOR"
 261 Sean M. Burke \f(CW\*(C`sburke@cpan.org\*(C'\fR