+=head1 CUSTOM ALIASES
+
+This version of charnames supports three mechanisms of adding local
+or customized aliases to standard Unicode naming conventions (:full).
+
+Note that an alias should not be something that is a legal curly
+brace-enclosed quantifier (see L<perlreref/QUANTIFIERS>). For example
+C<\N{123}> means to match 123 non-newline characters, and is not treated as an
+alias. Aliases are discouraged from beginning with anything other than an
+alphabetic character and from containing anything other than alphanumerics,
+spaces, dashes, colons, parentheses, and underscores. Currently they must be
+ASCII.
+
+=head2 Anonymous hashes
+
+ use charnames ":full", ":alias" => {
+ e_ACUTE => "LATIN SMALL LETTER E WITH ACUTE",
+ };
+ my $str = "\N{e_ACUTE}";
+
+=head2 Alias file
+
+ use charnames ":full", ":alias" => "pro";
+
+ will try to read "unicore/pro_alias.pl" from the @INC path. This
+ file should return a list in plain perl:
+
+ (
+ A_GRAVE => "LATIN CAPITAL LETTER A WITH GRAVE",
+ A_CIRCUM => "LATIN CAPITAL LETTER A WITH CIRCUMFLEX",
+ A_DIAERES => "LATIN CAPITAL LETTER A WITH DIAERESIS",
+ A_TILDE => "LATIN CAPITAL LETTER A WITH TILDE",
+ A_BREVE => "LATIN CAPITAL LETTER A WITH BREVE",
+ A_RING => "LATIN CAPITAL LETTER A WITH RING ABOVE",
+ A_MACRON => "LATIN CAPITAL LETTER A WITH MACRON",
+ );
+
+=head2 Alias shortcut
+
+ use charnames ":alias" => ":pro";
+
+ works exactly the same as the alias pairs, only this time,
+ ":full" is inserted automatically as first argument (if no
+ other argument is given).
+
+=head1 charnames::viacode(code)
+
+Returns the full name of the character indicated by the numeric code.
+The example
+
+ print charnames::viacode(0x2722);
+
+prints "FOUR TEARDROP-SPOKED ASTERISK".
+
+Returns undef if no name is known for the code.
+
+This works only for the standard names, and does not yet apply
+to custom translators.
+
+Notice that the name returned for of U+FEFF is "ZERO WIDTH NO-BREAK
+SPACE", not "BYTE ORDER MARK".
+
+=head1 charnames::vianame(name)
+
+Returns the code point indicated by the name.
+The example
+
+ printf "%04X", charnames::vianame("FOUR TEARDROP-SPOKED ASTERISK");
+
+prints "2722".
+
+Returns undef if the name is unknown.
+
+This works only for the standard names, and does not yet apply
+to custom translators.
+
+=head1 CUSTOM TRANSLATORS
+
+The mechanism of translation of C<\N{...}> escapes is general and not
+hardwired into F<charnames.pm>. A module can install custom
+translations (inside the scope which C<use>s the module) with the
+following magic incantation:
+
+ sub import {
+ shift;
+ $^H{charnames} = \&translator;
+ }
+
+Here translator() is a subroutine which takes C<CHARNAME> as an
+argument, and returns text to insert into the string instead of the
+C<\N{CHARNAME}> escape. Since the text to insert should be different
+in C<bytes> mode and out of it, the function should check the current
+state of C<bytes>-flag as in:
+
+ use bytes (); # for $bytes::hint_bits
+ sub translator {
+ if ($^H & $bytes::hint_bits) {
+ return bytes_translator(@_);
+ }
+ else {
+ return utf8_translator(@_);
+ }
+ }
+
+See L</CUSTOM ALIASES> above for restrictions on C<CHARNAME>.
+