.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" 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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 2024-05-30 "perl v5.38.2" "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(CWe2char(\*(Aqsol\*(Aq)\fR, \f(CWe2char(\*(Aq47\*(Aq)\fR, \&\f(CWe2char(\*(Aq0x2F\*(Aq)\fR, and \f(CWe2char(\*(Aq057\*(Aq)\fR all return "/", 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 "/". If the name has no known value (as with a name of "qacute") or is syntactically invalid (as with a name of "1/4"), 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(CWe2char(\*(Aqsol\*(Aq)\fR, \f(CWe2char(\*(Aq47\*(Aq)\fR, \&\f(CWe2char(\*(Aq0x2F\*(Aq)\fR, and \f(CWe2char(\*(Aq057\*(Aq)\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 "/", whose Unicode number is 47. If the name has no known value (as with a name of "qacute") or is syntactically invalid (as with a name of "1/4"), 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<\fR\f(CIname\fR\f(CW>\*(C'\fR) like "eacute" or "sol" to the string that each stands for. Note that this does not include numerics (like "64" or "x981c"). Under old Perl versions (before 5.7) you get a "?" 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<\fR\f(CIname\fR\f(CW>\*(C'\fR) like "eacute" or "sol" 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 "64" or "x981c"). .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 "e"). You may find this useful if you are rendering POD 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 "\exE9", lowercase e\-acute) to characters (like "e"). .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(CWe2char($x)\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 "?". Latin\-1 characters (characters 160\-255) are unaffected. .PP Under EBCDIC platforms, \f(CWe2char($n)\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(CWchr($Name2character_number{$name})\fR, because the strings are returned as native, and the numbers are returned as Unicode. However, for Perls starting with v5.8, \f(CWe2char($n)\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 \- ASCII 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 XHTML 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