README for Pod::Escapes
                                        Time-stamp: "2001-12-14 00:27:57 MST"

NAME
    Pod::Escapes -- for resolving Pod E<...> sequences

SYNOPSIS
      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_node->label, "\"!";
      }
      ...else print/interpolate $text...

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.

    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 `use Pod::Escapes qw(symbolname
    symbolname2...);', or you can do `use Pod::Escapes qw(:ALL);' to
    get all exportable symbols.

GOODIES
    e2char($e_content)

        Given a name or number that could appear in a `E<name_or_num>'
        sequence, this returns the string that it stands for. For
        example, `e2char('sol')', `e2char('47')', `e2char('x2F')', and
        `e2char('057')' all return "/", because `E<sol>', `E<47>',
        `E<x2f>', and `E<057>', all mean "/". If the name has no known
        value (as with a name of "qacute") or is syntactally invalid
        (as with a name of "1/4"), this returns undef.

    e2charnum($e_content)

        Given a name or number that could appear in a `E<name_or_num>'
        sequence, this returns the number of the Unicode character
        that this stands for. For example, `e2char('sol')',
        `e2char('47')', `e2char('x2F')', and `e2char('057')' all
        return 47, because `E<sol>', `E<47>', `E<x2f>', and `E<057>',
        all mean "/", whose Unicode number is 47. If the name has no
        known value (as with a name of "qacute") or is syntactally
        invalid (as with a name of "1/4"), this returns undef.

    $Name2character{*name*}

        Maps from names (as in `E<*name'>*) 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.

    $Name2character_number{*name*}

        Maps from names (as in `E<*name'>*) like "eacute" or "sol" to
        the Unicode value that each stands for. For example,
        `$Name2character_number{'eacute'}' is 201, and
        `$Name2character_number{'eacute'}' is 8364. You get the
        correct Unicode value, regardless of the version of Perl
        you're using -- which differs from `%Name2character''s
        behavior under pre-5.7 Perls.

        Note that this hash does not include numerics (like "64" or "x981c").

    $Name2character{*name*}

        Maps from names (as in `E<*name'>*) like "eacute" or "sol" to
        the string that each stands for. Note that this does not
        include numerics (like "64" or "x981c").

    $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.

    $Latin1Char_to_fallback{*character*}

        Just as above, but maps from characters (like "\xE9",
        lowercase e-acute) to characters (like "e").

    $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 `e2char($x)' when it senses
        that it's running on a non- ASCII platform (where chr(32)
        doesn't get you a space -- but $Code2USASCII{32} will). It's
        documented here just in case you might find it useful.

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.

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.

    Under EBCDIC platforms, `e2char($n)' may not always be the same as
    `chr(e2charnum($n))', and ditto for `$Name2character{$name}' and
    `chr($Name2character_number{$name})'.

SEE ALSO
    perlpod

    perlpodspec

    Text::Unidecode

COPYRIGHT AND DISCLAIMERS
    Copyright (c) 2001 Sean M. Burke. All rights reserved.

    This library is free software; you can redistribute it and/or
    modify it under the same terms as Perl itself.

    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.

    Portions of the data tables in this module are derived from the
    entity declarations in the W3C XHTML specification.

    Currently (October 2001), that's these three:

     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

AUTHOR
    Sean M. Burke `sburke@cpan.org'




PREREQUISITES

This suite requires Perl 5.

Pod::Escapes doesn't use any nonstandard modules.


INSTALLATION

You install Pod::Escapes, as you would install any perl module
library, by running these commands:

   perl Makefile.PL
   make
   make test
   make install

If you want to install a private copy of Pod::Escapes in your home
directory, then you should try to produce the initial Makefile with
something like this command:

  perl Makefile.PL LIB=~/perl


DOCUMENTATION

POD-format documentation is included in Escapes.pm.  POD is readable
with the 'perldoc' utility.  See ChangeLog for recent changes.


MACPERL INSTALLATION NOTES

Don't bother with the makefiles.  Just make a Pod directory in your
MacPerl site_lib or lib directory, and move Escapes.pm into there.


SUPPORT

Questions, bug reports, useful code bits, and suggestions for
Pod::Escapes should just be sent to me at sburke@cpan.org


AVAILABILITY

The latest version of Pod::Escapes is available from the
Comprehensive Perl Archive Network (CPAN).  Visit
<http://www.perl.com/CPAN/> to find a CPAN site near you.
