   This file documents the `recode' command, which has the purpose of
converting files between various character sets and surfaces.

   Copyright (C) 1990, 93, 94, 96, 97, 98, 99, 00 Free Software
Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Foundation.

Handling errors
===============

   The `recode' program, while using the `recode' library, needs to
control whether recoding problems are reported or not, and then reflect
these in the exit status.  The program should also instruct the library
whether the recoding should be abruptly interrupted when an error is
met (so sparing processing when it is known in advance that a wrong
result would be discarded anyway), or if it should proceed nevertheless.
Here is how the library groups errors into levels, listed here in order
of increasing severity.

`RECODE_NO_ERROR'
     No error was met on previous library calls.

`RECODE_NOT_CANONICAL'
     The input text was using one of the many alternative codings for
     some phenomenon, but not the one `recode' would have canonically
     generated.  So, if the reverse recoding is later attempted, it
     would produce a text having the same _meaning_ as the original
     text, yet not being byte identical.

     For example, a `Base64' block in which end-of-lines appear
     elsewhere that at every 76 characters is not canonical.  An
     e-circumflex in TeX which is coded as `\^{e}' instead of `\^e' is
     not canonical.

`RECODE_AMBIGUOUS_OUTPUT'
     It has been discovered that if the reverse recoding was attempted
     on the text output by this recoding, we would not obtain the
     original text, only because an ambiguity was generated by accident
     in the output text.  This ambiguity would then cause the wrong
     interpretation to be taken.

     Here are a few examples.  If the `Latin-1' sequence `e^' is
     converted to Easy French and back, the result will be interpreted
     as e-circumflex and so, will not reflect the intent of the
     original two characters.  Recoding an `IBM-PC' text to `Latin-1'
     and back, where the input text contained an isolated `LF', will
     have a spurious `CR' inserted before the `LF'.

     Currently, there are many cases in the library where the
     production of ambiguous output is not properly detected, as it is
     sometimes a difficult problem to accomplish this detection, or to
     do it speedily.

`RECODE_UNTRANSLATABLE'
     One or more input character could not be recoded, because there is
     just no representation for this character in the output charset.

     Here are a few examples.  Non-strict mode often allows `recode' to
     compute on-the-fly mappings for unrepresentable characters, but
     strict mode prohibits such attribution of reversible translations:
     so strict mode might often trigger such an error.  Most `UCS-2'
     codes used to represent Asian characters cannot be expressed in
     various Latin charsets.

`RECODE_INVALID_INPUT'
     The input text does not comply with the coding it is declared to
     hold.  So, there is no way by which a reverse recoding would
     reproduce this text, because `recode' should never produce invalid
     output.

     Here are a few examples.  In strict mode, `ASCII' text is not
     allowed to contain characters with the eight bit set.  `UTF-8'
     encodings ought to be minimal(1).

`RECODE_SYSTEM_ERROR'
     The underlying system reported an error while the recoding was
     going on, likely an input/output error.  (This error symbol is
     currently unused in the library.)

`RECODE_USER_ERROR'
     The programmer or user requested something the recoding library is
     unable to provide, or used the API wrongly.  (This error symbol is
     currently unused in the library.)

`RECODE_INTERNAL_ERROR'
     Something really wrong, which should normally never happen, was
     detected within the recoding library.  This might be due to
     genuine bugs in the library, or maybe due to un-initialised or
     overwritten arguments to the API.  (This error symbol is currently
     unused in the library.)

`RECODE_MAXIMUM_ERROR'
     This error code should never be returned, it is only internally
     used as a sentinel for the list of all possible error codes.

   One should be able to set the error level threshold for returning
failure at end of recoding, and also the threshold for immediate
interruption.  If many errors occur while the recoding proceed, which
are not severe enough to interrupt the recoding, then the most severe
error is retained, while others are forgotten(2).  So, in case of an
error, the possible actions currently are:

   * do nothing and let go, returning success at end of recoding,

   * just let go for now, but return failure at end of recoding,

   * interrupt recoding right away and return failure now.

See Task level, and particularly the description of the fields
`fail_level', `abort_level' and `error_so_far', for more information
about how errors are handled.

   ---------- Footnotes ----------

   (1) The minimality of an `UTF-8' encoding is guaranteed on output,
but currently, it is not checked on input.

   (2) Another approach would have been to define the level symbols as
masks instead, and to give masks to threshold setting routines, and to
retain all errors--yet I never met myself such a need in practice, and
so I fear it would be overkill.  On the other hand, it might be
interesting to maintain counters about how many times each kind of
error occurred.

The universal charset
*********************

   Standard ISO 10646 defines a universal character set, intended to
encompass in the long run all languages written on this planet.  It is
based on wide characters, and offer possibilities for two billion
characters (2^31).

   This charset was to become available in `recode' under the name
`UCS', with many external surfaces for it.  But in the current version,
only surfaces of `UCS' are offered, each presented as a genuine charset
rather than a surface.  Such surfaces are only meaningful for the `UCS'
charset, so it is not that useful to draw a line between the surfaces
and the only charset to which they may apply.

   `UCS' stands for Universal Character Set.  `UCS-2' and `UCS-4' are
fixed length encodings, using two or four bytes per character
respectively.  `UTF' stands for `UCS' Transformation Format, and are
variable length encodings dedicated to `UCS'.  `UTF-1' was based on
ISO 2022, it did not succeed(1).  `UTF-2' replaced it, it has been
called `UTF-FSS' (File System Safe) in Unicode or Plan9 context, but is
better known today as `UTF-8'.  To complete the picture, there is
`UTF-16' based on 16 bits bytes, and `UTF-7' which is meant for
transmissions limited to 7-bit bytes.  Most often, one might see
`UTF-8' used for external storage, and `UCS-2' used for internal
storage.

   When `recode' is producing any representation of `UCS', it uses the
replacement character `U+FFFD' for any _valid_ character which is not
representable in the goal charset(2).  This happens, for example, when
`UCS-2' is not capable to echo a wide `UCS-4' character, or for a
similar reason, an `UTF-8' sequence using more than three bytes.  The
replacement character is meant to represent an existing character.  So,
it is never produced to represent an invalid sequence or ill-formed
character in the input text.  In such cases, `recode' just gets rid of
the noise, while taking note of the error in its usual ways.

   Even if `UTF-8' is an encoding, really, it is the encoding of a
single character set, and nothing else.  It is useful to distinguish
between an encoding (a _surface_ within `recode') and a charset, but
only when the surface may be applied to several charsets.  Specifying a
charset is a bit simpler than specifying a surface in a `recode'
request.  There would not be a practical advantage at imposing a more
complex syntax to `recode' users, when it is simple to assimilate
`UTF-8' to a charset.  Similar considerations apply for `UCS-2',
`UCS-4', `UTF-16' and `UTF-7'.  These are all considered to be charsets.

   ---------- Footnotes ----------

   (1) It is not probable that `recode' will ever support `UTF-1'.

   (2) This is when the goal charset allows for 16-bits.  For shorter
charsets, the `--strict' (`-s') option decides what happens: either the
character is dropped, or a reversible mapping is produced on the fly.

Universal Character Set, 2 bytes
================================

   One surface of `UCS' is usable for the subset defined by its first
sixty thousand characters (in fact, 31 * 2^11 codes), and uses exactly
two bytes per character.  It is a mere dump of the internal memory
representation which is _natural_ for this subset and as such, conveys
with it endianness problems.

   A non-empty `UCS-2' file normally begins with a so called "byte
order mark", having value `0xFEFF'.  The value `0xFFFE' is not an `UCS'
character, so if this value is seen at the beginning of a file,
`recode' reacts by swapping all pairs of bytes.  The library also
properly reacts to other occurrences of `0xFEFF' or `0xFFFE' elsewhere
than at the beginning, because concatenation of `UCS-2' files should
stay a simple matter, but it might trigger a diagnostic about non
canonical input.

   By default, when producing an `UCS-2' file, `recode' always outputs
the high order byte before the low order byte.  But this could be
easily overridden through the `21-Permutation' surface (see
Permutations).  For example, the command:

     recode u8..u2/21 < INPUT > OUTPUT

asks for an `UTF-8' to `UCS-2' conversion, with swapped byte output.

   Use `UCS-2' as a genuine charset.  This charset is available in
`recode' under the name `ISO-10646-UCS-2'.  Accepted aliases are
`UCS-2', `BMP', `rune' and `u2'.

   The `recode' library is able to combine `UCS-2' some sequences of
codes into single code characters, to represent a few diacriticized
characters, ligatures or diphtongs which have been included to ease
mapping with other existing charsets.  It is also able to explode such
single code characters into the corresponding sequence of codes.  The
request syntax for triggering such operations is rudimentary and
temporary.  The `combined-UCS-2' pseudo character set is a special form
of `UCS-2' in which known combinings have been replaced by the simpler
code.  Using `combined-UCS-2' instead of `UCS-2' in an _after_ position
of a request forces a combining step, while using `combined-UCS-2'
instead of `UCS-2' in a _before_ position of a request forces an
exploding step.  For the time being, one has to resort to advanced
request syntax to achieve other effects.  For example:

     recode u8..co,u2..u8 < INPUT > OUTPUT

copies an `UTF-8' INPUT over OUTPUT, still to be in `UTF-8', yet
merging combining characters into single codes whenever possible.

Universal Character Set, 4 bytes
================================

   Another surface of `UCS' uses exactly four bytes per character, and
is a mere dump of the internal memory representation which is _natural_
for the whole charset and as such, conveys with it endianness problems.

   Use it as a genuine charset.  This charset is available in `recode'
under the name `ISO-10646-UCS-4'.  Accepted aliases are `UCS', `UCS-4',
`ISO_10646', `10646' and `u4'.

Universal Transformation Format, 7 bits
=======================================

   `UTF-7' comes from IETF rather than ISO, and is described by
RFC 2152, in the MIME series.  The `UTF-7' encoding is meant to fit
`UCS-2' over channels limited to seven bits per byte.  It proceeds from
a mix between the spirit of `Quoted-Printable' and methods of `Base64',
adapted to Unicode contexts.

   This charset is available in `recode' under the name
`UNICODE-1-1-UTF-7'.  Accepted aliases are `UTF-7', `TF-7' and `u7'.

Universal Transformation Format, 8 bits
=======================================

   Even if `UTF-8' does not originally come from IETF, there is now
RFC 2279 to describe it.  In letters sent on 1995-01-21 and 1995-04-20,
Markus Kuhn writes:

     `UTF-8' is an `ASCII' compatible multi-byte encoding of the
     ISO 10646 universal character set (`UCS').  `UCS' is a 31-bit
     superset of all other character set standards.  The first 256
     characters of `UCS' are identical to those of ISO 8859-1
     (Latin-1).  The `UCS-2' encoding of UCS is a sequence of bigendian
     16-bit words, the `UCS-4' encoding is a sequence of bigendian
     32-bit words.  The `UCS-2' subset of ISO 10646 is also known as
     "Unicode".  As both `UCS-2' and `UCS-4' require heavy
     modifications to traditional `ASCII' oriented system designs (e.g.
     Unix), the `UTF-8' encoding has been designed for these
     applications.

     In `UTF-8', only `ASCII' characters are encoded using bytes below
     128.  All other non-ASCII characters are encoded as multi-byte
     sequences consisting only of bytes in the range 128-253.  This
     avoids critical bytes like `NUL' and `/' in `UTF-8' strings, which
     makes the `UTF-8' encoding suitable for being handled by the
     standard C string library and being used in Unix file names.
     Other properties include the preserved lexical sorting order and
     that `UTF-8' allows easy self-synchronisation of software
     receiving `UTF-8' strings.

   `UTF-8' is the most common external surface of `UCS', each character
uses from one to six bytes, and is able to encode all 2^31 characters
of the `UCS'.  It is implemented as a charset, with the following
properties:

   * Strict 7-bit `ASCII' is completely invariant under `UTF-8', and
     those are the only one-byte characters.  `UCS' values and `ASCII'
     values coincide.  No multi-byte characters ever contain bytes less
     than 128.  `NUL' _is_ `NUL'.  A multi-byte character always starts
     with a byte of 192 or more, and is always followed by a number of
     bytes between 128 to 191.  That means that you may read at random
     on disk or memory, and easily discover the start of the current,
     next or previous character.  You can count, skip or extract
     characters with this only knowledge.

   * If you read the first byte of a multi-byte character in binary, it
     contains many `1' bits in successions starting with the most
     significant one (from the left), at least two.  The length of this
     `1' sequence equals the byte size of the character.  All
     succeeding bytes start by `10'.  This is a lot of redundancy,
     making it fairly easy to guess that a file is valid `UTF-8', or to
     safely state that it is not.

   * In a multi-byte character, if you remove all leading `1' bits of
     the first byte of a multi-byte character, and the initial `10'
     bits of all remaining bytes (so keeping 6 bits per byte for
     those), the remaining bits concatenated are the UCS value.

These properties also have a few nice consequences:

   * Conversion to/from values is algorithmically simple, and
     reasonably speedy.

   * A sequence of N bytes can hold characters needing up to 2 + 5N
     bits in their `UCS' representation.  Here, N is a number between 1
     and 6.  So, `UTF-8' is most economical when mapping ASCII (1 byte),
     followed by `UCS-2' (1 to 3 bytes) and `UCS-4' (1 to 6 bytes).

   * The lexicographic sorting order of `UCS' strings is preserved.

   * Bytes with value 254 or 255 never appear, and because of that,
     these are sometimes used when escape mechanisms are needed.

   In some case, when little processing is done on a lot of strings,
one may choose for efficiency reasons to handle `UTF-8' strings
directly even if variable length, as it is easy to get start of
characters.  Character insertion or replacement might require moving
the remainder of the string in either direction.  In most cases, it is
faster and easier to convert from `UTF-8' to `UCS-2' or `UCS-4' prior
to processing.

   This charset is available in `recode' under the name `UTF-8'.
Accepted aliases are `UTF-2', `UTF-FSS', `FSS_UTF', `TF-8' and `u8'.

Universal Transformation Format, 16 bits
========================================

   Another external surface of `UCS' is also variable length, each
character using either two or four bytes.  It is usable for the subset
defined by the first million characters (17 * 2^16) of `UCS'.

   Martin J. Du"rst writes (to `comp.std.internat', on 1995-03-28):

     `UTF-16' is another method that reserves two times 1024 codepoints
     in Unicode and uses them to index around one million additional
     characters.  `UTF-16' is a little bit like former multibyte codes,
     but quite not so, as both the first and the second 16-bit code
     clearly show what they are.  The idea is that one million
     codepoints should be enough for all the rare Chinese ideograms and
     historical scripts that do not fit into the Base Multilingual
     Plane of ISO 10646 (with just about 63,000 positions available,
     now that 2,000 are gone).

   This charset is available in `recode' under the name `UTF-16'.
Accepted aliases are `Unicode', `TF-16' and `u6'.

Frequency count of characters
=============================

   A device may be used to obtain a list of characters in a file, and
how many times each character appears.  Each count is followed by the
`UCS-2' value of the character and, when known, the RFC 1345 mnemonic
for that character.

   This charset is available in `recode' under the name
`count-characters'.

   This `count' feature has been implemented as a charset.  This may
change in some later version, as it would sometimes be convenient to
count original bytes, instead of their `UCS-2' equivalent.

Fully interpreted UCS dump
==========================

   Another device may be used to get fully interpreted dumps of an
`UCS-2' stream of characters, with one `UCS-2' character displayed on a
full output line.  Each line receives the RFC 1345 mnemonic for the
character if it exists, the `UCS-2' value of the character, and a
descriptive comment for that character.  As each input character
produces its own output line, beware that the output file from this
conversion may be much, much bigger than the input file.

   This charset is available in `recode' under the name
`dump-with-names'.

   This `dump-with-names' feature has been implemented as a charset
rather than a surface.  This is surely debatable.  The current
implementation allows for dumping charsets other than `UCS-2'.  For
example, the command `recode l2..full < INPUT' implies a necessary
conversion from `Latin-2' to `UCS-2', as `dump-with-names' is only
connected out from `UCS-2'.  In such cases, `recode' does not display
the original `Latin-2' codes in the dump, only the corresponding
`UCS-2' values.  To give a simpler example, the command

     echo 'Hello, world!' | recode us..dump

produces the following output:

     UCS2   Mne   Description

     0048   H     latin capital letter h
     0065   e     latin small letter e
     006C   l     latin small letter l
     006C   l     latin small letter l
     006F   o     latin small letter o
     002C   ,     comma
     0020   SP    space
     0077   w     latin small letter w
     006F   o     latin small letter o
     0072   r     latin small letter r
     006C   l     latin small letter l
     0064   d     latin small letter d
     0021   !     exclamation mark
     000A   LF    line feed (lf)

   The descriptive comment is given in English and `ASCII', yet if the
English description is not available but a French one is, then the
French description is given instead, using `Latin-1'.  However, if the
`LANGUAGE' or `LANG' environment variable begins with the letters `fr',
then listing preference goes to French when both descriptions are
available.

   Here is another example.  To get the long description of the code
237 in Latin-5 table, one may use the following command.

     echo -n 237 | recode l5/d..dump

If your `echo' does not grok `-n', use `echo 237\c' instead.  Here is
how to see what Unicode `U+03C6' means, while getting rid of the title
lines.

     echo -n 0x03C6 | recode u2/x2..dump | tail +3

The `iconv' library
*******************

   The `recode' library itself contains most code and tables from the
portable `iconv' library, written by Bruno Haible.  In fact, many
capabilities of the `recode' library are duplicated because of this
merging, as the older `recode' and `iconv' libraries share many
charsets.  We discuss, here, the issues related to this duplication, and
other peculiarities specific to the `iconv' library.  The plan is to
remove duplications and better merge specificities, as `recode' evolves.

   As implemented, if a recoding request can be satisfied by the
`recode' library both with and without its `iconv' library part, it is
likely that the `iconv' library will be used.  To sort out if the
`iconv' is indeed used of not, just use the `-v' or `--verbose' option,
see Recoding.

   The `:libiconv:' charset represents a conceptual pivot charset
within the `iconv' part of the `recode' library (in fact, this pivot
exists, but is not directly reachable).  This charset has a mere `:' (a
colon) for an alias.  It is not allowed to recode from or to this
charset directly.  But when this charset is selected as an
intermediate, usually by automatic means, then the `iconv' part of the
`recode' library is called to handle the transformations.  By using an
`--ignore=:libiconv:' option on the `recode' call or equivalently, but
more simply, `-x:', `recode' is instructed to fully avoid this charset
as an intermediate, with the consequence that the `iconv' part of the
library is defeated.  Consider these two calls:

     recode l1..1250 < INPUT > OUTPUT
     recode -x: l1..1250 < INPUT > OUTPUT

Both should transform INPUT from `ISO-8859-1' to `CP1250' on OUTPUT.
The first call uses the `iconv' part of the library, while the second
call avoids it.  Whatever the path used, the results should normally be
identical.  However, there might be observable differences.  Most of
them might result from reversibility issues, as the `iconv' engine,
which the `recode' library directly uses for the time being, does not
address reversibility.  Even if much less likely, some differences
might result from slight errors in the tables used, such differences
should then be reported as bugs.

   Other irregularities might be seen in the area of error detection and
recovery.  The `recode' library usually tries to detect canonicity
errors in input, and production of ambiguous output, but the `iconv'
part of the library currently does not.  Input is always validated,
however.  The `recode' library may not always react properly when its
`iconv' part has no translation for a given character.

   Within a collection of names for a single charset, the `recode'
library distinguishes one of them as being the genuine charset name,
while the others are said to be aliases.  When `recode' lists all
charsets, for example with the `-l' or `--list' option, the list
integrates all `iconv' library charsets.  The selection of one of the
aliases as the genuine charset name is an artifact added by `recode',
it does not come from `iconv'.  Moreover, the `recode' library
dynamically resolves some conflicts when it initialises itself at
runtime.  This might explain some discrepancies in the table below, as
for what is the genuine charset name.

   * General character sets
    `US-ASCII'
          `ASCII', `ISO646-US', `ISO_646.IRV:1991', `ISO-IR-6',
          `ANSI_X3.4-1968', `CP367', `IBM367', `US', `csASCII' and
          `ISO646.1991-IRV' are aliases for this charset.

   * General multi-byte encodings
    `UTF-8'
          `UTF8' is an alias for this charset.

    `UCS-2'
          `ISO-10646-UCS-2' and `csUnicode' are aliases for this
          charset.

    `UCS-2BE'
          `UNICODEBIG', `UNICODE-1-1' and `csUnicode11' are aliases for
          this charset.

    `UCS-2LE'
          `UNICODELITTLE' is an alias for this charset.

    `UCS-4'
          `ISO-10646-UCS-4' and `csUCS4' are aliases for this charset.

    `UCS-4BE'

    `UCS-4LE'

    `UTF-16'

    `UTF-16BE'

    `UTF-16LE'

    `UTF-7'
          `UNICODE-1-1-UTF-7' and `csUnicode11UTF7' are aliases for
          this charset.

    `UCS-2-INTERNAL'

    `UCS-2-SWAPPED'

    `UCS-4-INTERNAL'

    `UCS-4-SWAPPED'

    `JAVA'
   * Standard 8-bit encodings
    `ISO-8859-1'
          `ISO_8859-1', `ISO_8859-1:1987', `ISO-IR-100', `CP819',
          `IBM819', `LATIN1', `L1', `csISOLatin1', `ISO8859-1' and
          `ISO8859_1' are aliases for this charset.

    `ISO-8859-2'
          `ISO_8859-2', `ISO_8859-2:1987', `ISO-IR-101', `LATIN2',
          `L2', `csISOLatin2', `ISO8859-2' and `ISO8859_2' are aliases
          for this charset.

    `ISO-8859-3'
          `ISO_8859-3', `ISO_8859-3:1988', `ISO-IR-109', `LATIN3',
          `L3', `csISOLatin3', `ISO8859-3' and `ISO8859_3' are aliases
          for this charset.

    `ISO-8859-4'
          `ISO_8859-4', `ISO_8859-4:1988', `ISO-IR-110', `LATIN4',
          `L4', `csISOLatin4', `ISO8859-4' and `ISO8859_4' are aliases
          for this charset.

    `ISO-8859-5'
          `ISO_8859-5', `ISO_8859-5:1988', `ISO-IR-144', `CYRILLIC',
          `csISOLatinCyrillic', `ISO8859-5' and `ISO8859_5' are aliases
          for this charset.

    `ISO-8859-6'
          `ISO_8859-6', `ISO_8859-6:1987', `ISO-IR-127', `ECMA-114',
          `ASMO-708', `ARABIC', `csISOLatinArabic', `ISO8859-6' and
          `ISO8859_6' are aliases for this charset.

    `ISO-8859-7'
          `ISO_8859-7', `ISO_8859-7:1987', `ISO-IR-126', `ECMA-118',
          `ELOT_928', `GREEK8', `GREEK', `csISOLatinGreek', `ISO8859-7'
          and `ISO8859_7' are aliases for this charset.

    `ISO-8859-8'
          `ISO_8859-8', `ISO_8859-8:1988', `ISO-IR-138', `HEBREW',
          `csISOLatinHebrew', `ISO8859-8' and `ISO8859_8' are aliases
          for this charset.

    `ISO-8859-9'
          `ISO_8859-9', `ISO_8859-9:1989', `ISO-IR-148', `LATIN5',
          `L5', `csISOLatin5', `ISO8859-9' and `ISO8859_9' are aliases
          for this charset.

    `ISO-8859-10'
          `ISO_8859-10', `ISO_8859-10:1992', `ISO-IR-157', `LATIN6',
          `L6', `csISOLatin6' and `ISO8859-10' are aliases for this
          charset.

    `ISO-8859-13'
          `ISO_8859-13', `ISO-IR-179', `LATIN7' and `L7' are aliases
          for this charset.

    `ISO-8859-14'
          `ISO_8859-14', `ISO_8859-14:1998', `ISO-IR-199', `LATIN8' and
          `L8' are aliases for this charset.

    `ISO-8859-15'
          `ISO_8859-15', `ISO_8859-15:1998' and `ISO-IR-203' are
          aliases for this charset.

    `ISO-8859-16'
          `ISO_8859-16', `ISO_8859-16:2000' and `ISO-IR-226' are
          aliases for this charset.

    `KOI8-R'
          `csKOI8R' is an alias for this charset.

    `KOI8-U'

    `KOI8-RU'
   * Windows 8-bit encodings
    `CP1250'
          `WINDOWS-1250' and `MS-EE' are aliases for this charset.

    `CP1251'
          `WINDOWS-1251' and `MS-CYRL' are aliases for this charset.

    `CP1252'
          `WINDOWS-1252' and `MS-ANSI' are aliases for this charset.

    `CP1253'
          `WINDOWS-1253' and `MS-GREEK' are aliases for this charset.

    `CP1254'
          `WINDOWS-1254' and `MS-TURK' are aliases for this charset.

    `CP1255'
          `WINDOWS-1255' and `MS-HEBR' are aliases for this charset.

    `CP1256'
          `WINDOWS-1256' and `MS-ARAB' are aliases for this charset.

    `CP1257'
          `WINDOWS-1257' and `WINBALTRIM' are aliases for this charset.

    `CP1258'
          `WINDOWS-1258' is an alias for this charset.

   * DOS 8-bit encodings
    `CP850'
          `IBM850', `850' and `csPC850Multilingual' are aliases for
          this charset.

    `CP866'
          `IBM866', `866' and `csIBM866' are aliases for this charset.

   * Macintosh 8-bit encodings
    `MacRoman'
          `Macintosh', `MAC' and `csMacintosh' are aliases for this
          charset.

    `MacCentralEurope'

    `MacIceland'

    `MacCroatian'

    `MacRomania'

    `MacCyrillic'

    `MacUkraine'

    `MacGreek'

    `MacTurkish'

    `MacHebrew'

    `MacArabic'

    `MacThai'
   * Other platform specific 8-bit encodings
    `HP-ROMAN8'
          `ROMAN8', `R8' and `csHPRoman8' are aliases for this charset.

    `NEXTSTEP'
   * Regional 8-bit encodings used for a single language
    `ARMSCII-8'

    `Georgian-Academy'

    `Georgian-PS'

    `MuleLao-1'

    `CP1133'
          `IBM-CP1133' is an alias for this charset.

    `TIS-620'
          `TIS620', `TIS620-0', `TIS620.2529-1', `TIS620.2533-0',
          `TIS620.2533-1' and `ISO-IR-166' are aliases for this charset.

    `CP874'
          `WINDOWS-874' is an alias for this charset.

    `VISCII'
          `VISCII1.1-1' and `csVISCII' are aliases for this charset.

    `TCVN'
          `TCVN-5712', `TCVN5712-1' and `TCVN5712-1:1993' are aliases
          for this charset.

   * CJK character sets (not documented)
    `JIS_C6220-1969-RO'
          `ISO646-JP', `ISO-IR-14', `JP' and `csISO14JISC6220ro' are
          aliases for this charset.

    `JIS_X0201'
          `JISX0201-1976', `X0201', `csHalfWidthKatakana',
          `JISX0201.1976-0' and `JIS0201' are aliases for this charset.

    `JIS_X0208'
          `JIS_X0208-1983', `JIS_X0208-1990', `JIS0208', `X0208',
          `ISO-IR-87', `csISO87JISX0208', `JISX0208.1983-0',
          `JISX0208.1990-0' and `JIS0208' are aliases for this charset.

    `JIS_X0212'
          `JIS_X0212.1990-0', `JIS_X0212-1990', `X0212', `ISO-IR-159',
          `csISO159JISX02121990', `JISX0212.1990-0' and `JIS0212' are
          aliases for this charset.

    `GB_1988-80'
          `ISO646-CN', `ISO-IR-57', `CN' and `csISO57GB1988' are
          aliases for this charset.

    `GB_2312-80'
          `ISO-IR-58', `csISO58GB231280', `CHINESE' and `GB2312.1980-0'
          are aliases for this charset.

    `ISO-IR-165'
          `CN-GB-ISOIR165' is an alias for this charset.

    `KSC_5601'
          `KS_C_5601-1987', `KS_C_5601-1989', `ISO-IR-149',
          `csKSC56011987', `KOREAN', `KSC5601.1987-0' and
          `KSX1001:1992' are aliases for this charset.

   * CJK encodings
    `EUC-JP'
          `EUCJP', `Extended_UNIX_Code_Packed_Format_for_Japanese',
          `csEUCPkdFmtJapanese' and `EUC_JP' are aliases for this
          charset.

    `SJIS'
          `SHIFT_JIS', `SHIFT-JIS', `MS_KANJI' and `csShiftJIS' are
          aliases for this charset.

    `CP932'

    `ISO-2022-JP'
          `csISO2022JP' and `ISO2022JP' are aliases for this charset.

    `ISO-2022-JP-1'

    `ISO-2022-JP-2'
          `csISO2022JP2' is an alias for this charset.

    `EUC-CN'
          `EUCCN', `GB2312', `CN-GB', `csGB2312' and `EUC_CN' are
          aliases for this charset.

    `GBK'
          `CP936' is an alias for this charset.

    `GB18030'

    `ISO-2022-CN'
          `csISO2022CN' and `ISO2022CN' are aliases for this charset.

    `ISO-2022-CN-EXT'

    `HZ'
          `HZ-GB-2312' is an alias for this charset.

    `EUC-TW'
          `EUCTW', `csEUCTW' and `EUC_TW' are aliases for this charset.

    `BIG5'
          `BIG-5', `BIG-FIVE', `BIGFIVE', `CN-BIG5' and `csBig5' are
          aliases for this charset.

    `CP950'

    `BIG5HKSCS'

    `EUC-KR'
          `EUCKR', `csEUCKR' and `EUC_KR' are aliases for this charset.

    `CP949'
          `UHC' is an alias for this charset.

    `JOHAB'
          `CP1361' is an alias for this charset.

    `ISO-2022-KR'
          `csISO2022KR' and `ISO2022KR' are aliases for this charset.

    `CHAR'

    `WCHAR_T'