1Pod::Escapes(3)       User Contributed Perl Documentation      Pod::Escapes(3)
2
3
4

NAME

6       Pod::Escapes - for resolving Pod E<...> sequences
7

SYNOPSIS

9         use Pod::Escapes qw(e2char);
10         ...la la la, parsing POD, la la la...
11         $text = e2char($e_node->label);
12         unless(defined $text) {
13           print "Unknown E sequence \"", $e_node->label, "\"!";
14         }
15         ...else print/interpolate $text...
16

DESCRIPTION

18       This module provides things that are useful in decoding Pod E<...>
19       sequences.  Presumably, it should be used only by Pod parsers and/or
20       formatters.
21
22       By default, Pod::Escapes exports none of its symbols.  But you can
23       request any of them to be exported.  Either request them individually,
24       as with "use Pod::Escapes qw(symbolname symbolname2...);", or you can
25       do "use Pod::Escapes qw(:ALL);" to get all exportable symbols.
26

GOODIES

28       e2char($e_content)
29           Given a name or number that could appear in a "E<name_or_num>"
30           sequence, this returns the string that it stands for.  For example,
31           e2char('sol'), e2char('47'), e2char('0x2F'), and e2char('057') all
32           return "/", because "E<sol>", "E<47>", "E<0x2f>", and "E<057>", all
33           mean "/".  If the name has no known value (as with a name of
34           "qacute") or is syntactically invalid (as with a name of "1/4"),
35           this returns undef.
36
37       e2charnum($e_content)
38           Given a name or number that could appear in a "E<name_or_num>"
39           sequence, this returns the number of the Unicode character that
40           this stands for.  For example, e2char('sol'), e2char('47'),
41           e2char('0x2F'), and e2char('057') all return 47, because "E<sol>",
42           "E<47>", "E<0x2f>", and "E<057>", all mean "/", whose Unicode
43           number is 47.  If the name has no known value (as with a name of
44           "qacute") or is syntactically invalid (as with a name of "1/4"),
45           this returns undef.
46
47       $Name2character{name}
48           Maps from names (as in "E<name>") like "eacute" or "sol" to the
49           string that each stands for.  Note that this does not include
50           numerics (like "64" or "x981c").  Under old Perl versions (before
51           5.7) you get a "?" in place of characters whose Unicode value is
52           over 255.
53
54       $Name2character_number{name}
55           Maps from names (as in "E<name>") like "eacute" or "sol" to the
56           Unicode value that each stands for.  For example,
57           $Name2character_number{'eacute'} is 201, and
58           $Name2character_number{'eacute'} is 8364.  You get the correct
59           Unicode value, regardless of the version of Perl you're using --
60           which differs from %Name2character's behavior under pre-5.7 Perls.
61
62           Note that this hash does not include numerics (like "64" or
63           "x981c").
64
65       $Latin1Code_to_fallback{integer}
66           For numbers in the range 160 (0x00A0) to 255 (0x00FF), this maps
67           from the character code for a Latin-1 character (like 233 for
68           lowercase e-acute) to the US-ASCII character that best aproximates
69           it (like "e").  You may find this useful if you are rendering POD
70           in a format that you think deals well only with US-ASCII
71           characters.
72
73       $Latin1Char_to_fallback{character}
74           Just as above, but maps from characters (like "\xE9", lowercase
75           e-acute) to characters (like "e").
76
77       $Code2USASCII{integer}
78           This maps from US-ASCII codes (like 32) to the corresponding
79           character (like space, for 32).  Only characters 32 to 126 are
80           defined.  This is meant for use by e2char($x) when it senses that
81           it's running on a non-ASCII platform (where chr(32) doesn't get you
82           a space -- but $Code2USASCII{32} will).  It's documented here just
83           in case you might find it useful.
84

CAVEATS

86       On Perl versions before 5.7, Unicode characters with a value over 255
87       (like lambda or emdash) can't be conveyed.  This module does work under
88       such early Perl versions, but in the place of each such character, you
89       get a "?".  Latin-1 characters (characters 160-255) are unaffected.
90
91       Under EBCDIC platforms, e2char($n) may not always be the same as
92       "chr(e2charnum($n))", and ditto for $Name2character{$name} and
93       chr($Name2character_number{$name}), because the strings are returned as
94       native, and the numbers are returned as Unicode.  However, for Perls
95       starting with v5.8, e2char($n) is the same as
96       "chr(utf8::unicode_to_native(e2charnum($n)))", and ditto for
97       $Name2character{$name} and
98       "chr(utf8::unicode_to_native($Name2character_number{$name}))".
99

SEE ALSO

101       Pod::Browser - a pod web server based on Catalyst.
102
103       Pod::Checker - check pod documents for syntax errors.
104
105       Pod::Coverage - check if the documentation for a module is
106       comprehensive.
107
108       perlpod - description of pod format (for people documenting with pod).
109
110       perlpodspec - specification of pod format (for people processing it).
111
112       Text::Unidecode - ASCII transliteration of Unicode text.
113

REPOSITORY

115       <https://github.com/neilbowers/Pod-Escapes>
116
118       Copyright (c) 2001-2004 Sean M. Burke.  All rights reserved.
119
120       This library is free software; you can redistribute it and/or modify it
121       under the same terms as Perl itself.
122
123       This program is distributed in the hope that it will be useful, but
124       without any warranty; without even the implied warranty of
125       merchantability or fitness for a particular purpose.
126
127       Portions of the data tables in this module are derived from the entity
128       declarations in the W3C XHTML specification.
129
130       Currently (October 2001), that's these three:
131
132        http://www.w3.org/TR/xhtml1/DTD/xhtml-lat1.ent
133        http://www.w3.org/TR/xhtml1/DTD/xhtml-special.ent
134        http://www.w3.org/TR/xhtml1/DTD/xhtml-symbol.ent
135

AUTHOR

137       Sean M. Burke "sburke@cpan.org"
138
139       Now being maintained by Neil Bowers <neilb@cpan.org>
140
141
142
143perl v5.36.0                      2023-01-20                   Pod::Escapes(3)
Impressum