.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Pod::Escapes 3perl" .TH Pod::Escapes 3perl "2021-09-24" "perl v5.32.1" "Perl Programmers Reference Guide" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Pod::Escapes \- for resolving Pod E<...> sequences .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 7 \& use Pod::Escapes qw(e2char); \& ...la la la, parsing POD, la la la... \& $text = e2char($e_node\->label); \& unless(defined $text) { \& print "Unknown E sequence \e"", $e_node\->label, "\e"!"; \& } \& ...else print/interpolate $text... .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module provides things that are useful in decoding Pod E<...> sequences. Presumably, it should be used only by Pod parsers and/or formatters. .PP By default, Pod::Escapes exports none of its symbols. But you can request any of them to be exported. Either request them individually, as with \&\f(CW\*(C`use Pod::Escapes qw(symbolname symbolname2...);\*(C'\fR, or you can do \f(CW\*(C`use Pod::Escapes qw(:ALL);\*(C'\fR to get all exportable symbols. .SH "GOODIES" .IX Header "GOODIES" .IP "e2char($e_content)" 4 .IX Item "e2char($e_content)" Given a name or number that could appear in a \&\f(CW\*(C`E\*(C'\fR sequence, this returns the string that it stands for. For example, \f(CW\*(C`e2char(\*(Aqsol\*(Aq)\*(C'\fR, \f(CW\*(C`e2char(\*(Aq47\*(Aq)\*(C'\fR, \&\f(CW\*(C`e2char(\*(Aq0x2F\*(Aq)\*(C'\fR, and \f(CW\*(C`e2char(\*(Aq057\*(Aq)\*(C'\fR all return \*(L"/\*(R", because \f(CW\*(C`E\*(C'\fR, \f(CW\*(C`E<47>\*(C'\fR, \f(CW\*(C`E<0x2f>\*(C'\fR, and \f(CW\*(C`E<057>\*(C'\fR, all mean \*(L"/\*(R". If the name has no known value (as with a name of \*(L"qacute\*(R") or is syntactically invalid (as with a name of \*(L"1/4\*(R"), this returns undef. .IP "e2charnum($e_content)" 4 .IX Item "e2charnum($e_content)" Given a name or number that could appear in a \&\f(CW\*(C`E\*(C'\fR sequence, this returns the number of the Unicode character that this stands for. For example, \&\f(CW\*(C`e2char(\*(Aqsol\*(Aq)\*(C'\fR, \f(CW\*(C`e2char(\*(Aq47\*(Aq)\*(C'\fR, \&\f(CW\*(C`e2char(\*(Aq0x2F\*(Aq)\*(C'\fR, and \f(CW\*(C`e2char(\*(Aq057\*(Aq)\*(C'\fR all return 47, because \f(CW\*(C`E\*(C'\fR, \f(CW\*(C`E<47>\*(C'\fR, \f(CW\*(C`E<0x2f>\*(C'\fR, and \f(CW\*(C`E<057>\*(C'\fR, all mean \*(L"/\*(R", whose Unicode number is 47. If the name has no known value (as with a name of \*(L"qacute\*(R") or is syntactically invalid (as with a name of \*(L"1/4\*(R"), this returns undef. .ie n .IP "$Name2character{\fIname\fR}" 4 .el .IP "\f(CW$Name2character\fR{\fIname\fR}" 4 .IX Item "$Name2character{name}" Maps from names (as in \f(CW\*(C`E<\f(CIname\f(CW>\*(C'\fR) like \*(L"eacute\*(R" or \*(L"sol\*(R" to the string that each stands for. Note that this does not include numerics (like \*(L"64\*(R" or \*(L"x981c\*(R"). Under old Perl versions (before 5.7) you get a \*(L"?\*(R" in place of characters whose Unicode value is over 255. .ie n .IP "$Name2character_number{\fIname\fR}" 4 .el .IP "\f(CW$Name2character_number\fR{\fIname\fR}" 4 .IX Item "$Name2character_number{name}" Maps from names (as in \f(CW\*(C`E<\f(CIname\f(CW>\*(C'\fR) like \*(L"eacute\*(R" or \*(L"sol\*(R" to the Unicode value that each stands for. For example, \&\f(CW$Name2character_number{\*(Aqeacute\*(Aq}\fR is 201, and \&\f(CW$Name2character_number{\*(Aqeacute\*(Aq}\fR is 8364. You get the correct Unicode value, regardless of the version of Perl you're using \*(-- which differs from \f(CW%Name2character\fR's behavior under pre\-5.7 Perls. .Sp Note that this hash does not include numerics (like \*(L"64\*(R" or \*(L"x981c\*(R"). .ie n .IP "$Latin1Code_to_fallback{\fIinteger\fR}" 4 .el .IP "\f(CW$Latin1Code_to_fallback\fR{\fIinteger\fR}" 4 .IX Item "$Latin1Code_to_fallback{integer}" For numbers in the range 160 (0x00A0) to 255 (0x00FF), this maps from the character code for a Latin\-1 character (like 233 for lowercase e\-acute) to the US-ASCII character that best aproximates it (like \*(L"e\*(R"). You may find this useful if you are rendering \&\s-1POD\s0 in a format that you think deals well only with US-ASCII characters. .ie n .IP "$Latin1Char_to_fallback{\fIcharacter\fR}" 4 .el .IP "\f(CW$Latin1Char_to_fallback\fR{\fIcharacter\fR}" 4 .IX Item "$Latin1Char_to_fallback{character}" Just as above, but maps from characters (like \*(L"\exE9\*(R", lowercase e\-acute) to characters (like \*(L"e\*(R"). .ie n .IP "$Code2USASCII{\fIinteger\fR}" 4 .el .IP "\f(CW$Code2USASCII\fR{\fIinteger\fR}" 4 .IX Item "$Code2USASCII{integer}" This maps from US-ASCII codes (like 32) to the corresponding character (like space, for 32). Only characters 32 to 126 are defined. This is meant for use by \f(CW\*(C`e2char($x)\*(C'\fR when it senses that it's running on a non-ASCII platform (where chr(32) doesn't get you a space \*(-- but \f(CW$Code2USASCII\fR{32} will). It's documented here just in case you might find it useful. .SH "CAVEATS" .IX Header "CAVEATS" On Perl versions before 5.7, Unicode characters with a value over 255 (like lambda or emdash) can't be conveyed. This module does work under such early Perl versions, but in the place of each such character, you get a \*(L"?\*(R". Latin\-1 characters (characters 160\-255) are unaffected. .PP Under \s-1EBCDIC\s0 platforms, \f(CW\*(C`e2char($n)\*(C'\fR may not always be the same as \f(CW\*(C`chr(e2charnum($n))\*(C'\fR, and ditto for \&\f(CW$Name2character{$name}\fR and \&\f(CW\*(C`chr($Name2character_number{$name})\*(C'\fR, because the strings are returned as native, and the numbers are returned as Unicode. However, for Perls starting with v5.8, \f(CW\*(C`e2char($n)\*(C'\fR is the same as \&\f(CW\*(C`chr(utf8::unicode_to_native(e2charnum($n)))\*(C'\fR, and ditto for \&\f(CW$Name2character{$name}\fR and \&\f(CW\*(C`chr(utf8::unicode_to_native($Name2character_number{$name}))\*(C'\fR. .SH "SEE ALSO" .IX Header "SEE ALSO" Pod::Browser \- a pod web server based on Catalyst. .PP Pod::Checker \- check pod documents for syntax errors. .PP Pod::Coverage \- check if the documentation for a module is comprehensive. .PP perlpod \- description of pod format (for people documenting with pod). .PP perlpodspec \- specification of pod format (for people processing it). .PP Text::Unidecode \- \s-1ASCII\s0 transliteration of Unicode text. .SH "REPOSITORY" .IX Header "REPOSITORY" .SH "COPYRIGHT AND DISCLAIMERS" .IX Header "COPYRIGHT AND DISCLAIMERS" Copyright (c) 2001\-2004 Sean M. Burke. All rights reserved. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. .PP This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. .PP Portions of the data tables in this module are derived from the entity declarations in the W3C \s-1XHTML\s0 specification. .PP Currently (October 2001), that's these three: .PP .Vb 3 \& http://www.w3.org/TR/xhtml1/DTD/xhtml\-lat1.ent \& http://www.w3.org/TR/xhtml1/DTD/xhtml\-special.ent \& http://www.w3.org/TR/xhtml1/DTD/xhtml\-symbol.ent .Ve .SH "AUTHOR" .IX Header "AUTHOR" Sean M. Burke \f(CW\*(C`sburke@cpan.org\*(C'\fR .PP Now being maintained by Neil Bowers