NOTES

   1 Q: Why does libiconv support encoding XXX? Why does libiconv not support
   2    encoding ZZZ?
   3
   4 A: libiconv, as an internationalization library, supports those character
   5    sets and encodings which are in wide-spread use in at least one territory
   6    of the world.
   7
   8    Hint1: On http://www.w3c.org/International/O-charset-lang.html you find a
   9    page "Languages, countries, and the charsets typically used for them".
  10    From this table, we can conclude that the following are in active use:
  11
  12      ISO-8859-1, CP1252   Afrikaans, Albanian, Basque, Catalan, Danish, Dutch,
  13                           English, Faroese, Finnish, French, Galician, German,
  14                           Icelandic, Irish, Italian, Norwegian, Portuguese,
  15                           Scottish, Spanish, Swedish
  16      ISO-8859-2           Croatian, Czech, Hungarian, Polish, Romanian, Slovak,
  17                           Slovenian
  18      ISO-8859-3           Esperanto, Maltese
  19      ISO-8859-5           Bulgarian, Byelorussian, Macedonian, Russian,
  20                           Serbian, Ukrainian
  21      ISO-8859-6           Arabic
  22      ISO-8859-7           Greek
  23      ISO-8859-8           Hebrew
  24      ISO-8859-9, CP1254   Turkish
  25      ISO-8859-10          Inuit, Lapp
  26      ISO-8859-13          Latvian, Lithuanian
  27      ISO-8859-15          Estonian
  28      KOI8-R               Russian
  29      SHIFT_JIS            Japanese
  30      ISO-2022-JP          Japanese
  31      EUC-JP               Japanese
  32
  33    Ordered by frequency on the web (1997):
  34      ISO-8859-1, CP1252   96%
  35      SHIFT_JIS             1.6%
  36      ISO-2022-JP           1.2%
  37      EUC-JP                0.4%
  38      CP1250                0.3%
  39      CP1251                0.2%
  40      CP850                 0.1%
  41      MACINTOSH             0.1%
  42      ISO-8859-5            0.1%
  43      ISO-8859-2            0.0%
  44
  45    Hint2: The character sets mentioned in the XFree86 4.0 locale.alias file.
  46
  47      ISO-8859-1           Afrikaans, Basque, Breton, Catalan, Danish, Dutch,
  48                           English, Estonian, Faroese, Finnish, French,
  49                           Galician, German, Greenlandic, Icelandic,
  50                           Indonesian, Irish, Italian, Lithuanian, Norwegian,
  51                           Occitan, Portuguese, Scottish, Spanish, Swedish,
  52                           Walloon, Welsh
  53      ISO-8859-2           Albanian, Croatian, Czech, Hungarian, Polish,
  54                           Romanian, Serbian, Slovak, Slovenian
  55      ISO-8859-3           Esperanto
  56      ISO-8859-4           Estonian, Latvian, Lithuanian
  57      ISO-8859-5           Bulgarian, Byelorussian, Macedonian, Russian,
  58                           Serbian, Ukrainian
  59      ISO-8859-6           Arabic
  60      ISO-8859-7           Greek
  61      ISO-8859-8           Hebrew
  62      ISO-8859-9           Turkish
  63      ISO-8859-14          Breton, Irish, Scottish, Welsh
  64      ISO-8859-15          Basque, Breton, Catalan, Danish, Dutch, Estonian,
  65                           Faroese, Finnish, French, Galician, German,
  66                           Greenlandic, Icelandic, Irish, Italian, Lithuanian,
  67                           Norwegian, Occitan, Portuguese, Scottish, Spanish,
  68                           Swedish, Walloon, Welsh
  69      KOI8-R               Russian
  70      KOI8-U               Russian, Ukrainian
  71      EUC-JP (alias eucJP)      Japanese
  72      ISO-2022-JP (alias JIS7)  Japanese
  73      SHIFT_JIS (alias SJIS)    Japanese
  74      U90                       Japanese
  75      S90                       Japanese
  76      EUC-CN (alias eucCN)      Chinese
  77      EUC-TW (alias eucTW)      Chinese
  78      BIG5                      Chinese
  79      EUC-KR (alias eucKR)      Korean
  80      ARMSCII-8                 Armenian
  81      GEORGIAN-ACADEMY          Georgian
  82      GEORGIAN-PS               Georgian
  83      TIS-620 (alias TACTIS)    Thai
  84      MULELAO-1                 Laothian
  85      IBM-CP1133                Laothian
  86      VISCII                    Vietnamese
  87      TCVN                      Vietnamese
  88      NUNACOM-8                 Inuktitut
  89
  90    Hint3: The character sets supported by Netscape Communicator 4.
  91
  92      Where is this documented? For the complete picture, I had to use
  93      "strings netscape" and then a lot of guesswork. For a quick take,
  94      look at the "View - Character set" menu of Netscape Communicator 4.6:
  95
  96      ISO-8859-{1,2,5,7,9,15}
  97      WINDOWS-{1250,1251,1253}
  98      KOI8-R               Cyrillic
  99      CP866                Cyrillic
 100      Autodetect           Japanese  (EUC-JP, ISO-2022-JP, ISO-2022-JP-2, SJIS)
 101      EUC-JP               Japanese
 102      SHIFT_JIS            Japanese
 103      GB2312               Chinese
 104      BIG5                 Chinese
 105      EUC-TW               Chinese
 106      Autodetect           Korean    (EUC-KR, ISO-2022-KR, but not JOHAB)
 107
 108      UTF-8
 109      UTF-7
 110
 111    Hint4: The character sets supported by Microsoft Internet Explorer 4.
 112
 113      ISO-8859-{1,2,3,4,5,6,7,8,9}
 114      WINDOWS-{1250,1251,1252,1253,1254,1255,1256,1257}
 115      KOI8-R               Cyrillic
 116      KOI8-RU              Ukrainian
 117      ASMO-708             Arabic
 118      EUC-JP               Japanese
 119      ISO-2022-JP          Japanese
 120      SHIFT_JIS            Japanese
 121      GB2312               Chinese
 122      HZ-GB-2312           Chinese
 123      BIG5                 Chinese
 124      EUC-KR               Korean
 125      ISO-2022-KR          Korean
 126      WINDOWS-874          Thai
 127      WINDOWS-1258         Vietnamese
 128
 129      UTF-8
 130      UTF-7
 131      UNICODE             actually UNICODE-LITTLE
 132      UNICODEFEFF         actually UNICODE-BIG
 133
 134      and various DOS character sets: DOS-720, DOS-862, IBM852, CP866.
 135
 136    We take the union of all these four sets. The result is:
 137
 138    European and Semitic languages
 139      * ASCII.
 140        We implement this because it is occasionally useful to know or to
 141        check whether some text is entirely ASCII (i.e. if the conversion
 142        ISO-8859-x -> UTF-8 is trivial).
 143      * ISO-8859-{1,2,3,4,5,6,7,8,9,10}
 144        We implement this because they are widely used. Except ISO-8859-4
 145        which appears to have been superseded by ISO-8859-13 in the baltic
 146        countries. But it's an ISO standard anyway.
 147      * ISO-8859-13
 148        We implement this because it's a standard in Lithuania and Latvia.
 149      * ISO-8859-14
 150        We implement this because it's an ISO standard.
 151      * ISO-8859-15
 152        We implement this because it's increasingly used in Europe, because
 153        of the Euro symbol.
 154      * ISO-8859-16
 155        We implement this because it's an ISO standard.
 156      * KOI8-R, KOI8-U
 157        We implement this because it appears to be the predominant encoding
 158        on Unix in Russia and Ukraine, respectively.
 159      * KOI8-RU
 160        We implement this because MSIE4 supports it.
 161      * CP{1250,1251,1252,1253,1254,1255,1256,1257}
 162        We implement these because they are the predominant Windows encodings
 163        in Europe.
 164      * CP850
 165        We implement this because it is mentioned as occurring in the web
 166        in the aforementioned statistics.
 167      * CP862
 168        We implement this because Ron Aaron says it is sometimes used in web
 169        pages and emails.
 170      * CP866
 171        We implement this because Netscape Communicator does.
 172      * Mac{Roman,CentralEurope,Croatian,Romania,Cyrillic,Greek,Turkish} and
 173        Mac{Hebrew,Arabic}
 174        We implement these because the Sun JDK does, and because Mac users
 175        don't deserve to be punished.
 176      * Macintosh
 177        We implement this because it is mentioned as occurring in the web
 178        in the aforementioned statistics.
 179    Japanese
 180      * EUC-JP, SHIFT-JIS, ISO-2022-JP
 181        We implement these because they are widely used. EUC-JP and SHIFT-JIS
 182        are more used for files, whereas ISO-2022-JP is recommended for email.
 183      * CP932
 184        We implement this because it is the Microsoft variant of SHIFT-JIS,
 185        used on Windows.
 186      * ISO-2022-JP-2
 187        We implement this because it's the common way to represent mails which
 188        make use of JIS X 0212 characters.
 189      * ISO-2022-JP-1
 190        We implement this because it's in the RFCs, but I don't think it is
 191        really used.
 192      * U90, S90
 193        We DON'T implement this because I have no informations about what it
 194        is or who uses it.
 195    Simplified Chinese
 196      * EUC-CN = GB2312
 197        We implement this because it is the widely used representation
 198        of simplified Chinese.
 199      * GBK
 200        We implement this because it appears to be used on Solaris and Windows.
 201      * GB18030
 202        We implement this because it is an official requirement in the
 203        People's Republic of China.
 204      * ISO-2022-CN
 205        We implement this because it is in the RFCs, but I have no idea
 206        whether it is really used.
 207      * ISO-2022-CN-EXT
 208        We implement this because it's in the RFCs, but I don't think it is
 209        really used.
 210      * HZ = HZ-GB-2312
 211        We implement this because the RFCs recommend it for Usenet postings,
 212        and because MSIE4 supports it.
 213    Traditional Chinese
 214      * EUC-TW
 215        We implement it because it appears to be used on Unix.
 216      * BIG5
 217        We implement it because it is the de-facto standard for traditional
 218        Chinese.
 219      * CP950
 220        We implement this because it is the Microsoft variant of BIG5, used
 221        on Windows.
 222      * BIG5+
 223        We DON'T implement this because it doesn't appear to be in wide use.
 224        Only the CWEX fonts use this encoding. Furthermore, the conversion
 225        tables in the big5p package are not coherent: If you convert directly,
 226        you get different results than when you convert via GBK.
 227      * BIG5HKSCS
 228        We implement it because it is the de-facto standard for traditional
 229        Chinese in Hongkong.
 230    Korean
 231      * EUC-KR
 232        We implement these because they appear to be the widely used
 233        representations for Korean.
 234      * CP949
 235        We implement this because it is the Microsoft variant of EUC-KR, used
 236        on Windows.
 237      * ISO-2022-KR
 238        We implement it because it is in the RFCs and because MSIE4 supports
 239        it, but I have no idea whether it's really used.
 240      * JOHAB
 241        We implement this because it is apparently used on Windows as a locale
 242        encoding (codepage 1361).
 243      * ISO-646-KR
 244        We DON'T implement this because although an old ASCII variant, its
 245        glyph for 0x7E is not clear: RFC 1345 and unicode.org's JOHAB.TXT
 246        say it's a tilde, but Ken Lunde's "CJKV information processing" says
 247        it's an overline. And it is not ISO-IR registered.
 248    Armenian
 249      * ARMSCII-8
 250        We implement it because XFree86 supports it.
 251    Georgian
 252      * Georgian-Academy, Georgian-PS
 253        We implement these because they appear to be both used for Georgian;
 254        Xfree86 supports them.
 255    Thai
 256      * TIS-620
 257        We implement this because it seems to be standard for Thai.
 258      * CP874
 259        We implement this because MSIE4 supports it.
 260      * MacThai
 261        We implement this because the Sun JDK does, and because Mac users
 262        don't deserve to be punished.
 263    Laotian
 264      * MuleLao-1, CP1133
 265        We implement these because XFree86 supports them. I have no idea which
 266        one is used more widely.
 267    Vietnamese
 268      * VISCII, TCVN
 269        We implement these because XFree86 supports them.
 270      * CP1258
 271        We implement this because MSIE4 supports it.
 272    Other languages
 273      * NUNACOM-8 (Inuktitut)
 274        We DON'T implement this because it isn't part of Unicode yet, and
 275        therefore doesn't convert to anything except itself.
 276    Platform specifics
 277      * HP-ROMAN8, NEXTSTEP
 278        We implement these because they were the native character set on HPs
 279        and NeXTs for a long time, and libiconv is intended to be usable on
 280        these old machines.
 281    Full Unicode
 282      * UTF-8, UCS-2, UCS-4
 283        We implement these. Obviously.
 284      * UCS-2BE, UCS-2LE, UCS-4BE, UCS-4LE
 285        We implement these because they are the preferred internal
 286        representation of strings in Unicode aware applications. These are
 287        non-ambiguous names, known to glibc. (glibc doesn't have
 288        UCS-2-INTERNAL and UCS-4-INTERNAL.)
 289      * UTF-16, UTF-16BE, UTF-16LE
 290        We implement these, because UTF-16 is still the favourite encoding of
 291        the president of the Unicode Consortium (for political reasons), and
 292        because they appear in RFC 2781.
 293      * UTF-32, UTF-32BE, UTF-32LE
 294        We implement these because they are part of Unicode 3.1.
 295      * UTF-7
 296        We implement this because it is essential functionality for mail
 297        applications.
 298      * JAVA
 299        We implement it because it's used for Java programs and because it's
 300        a nice encoding for debugging.
 301      * UNICODE (big endian), UNICODEFEFF (little endian)
 302        We DON'T implement these because they are stupid and not standardized.
 303    Full Unicode, in terms of `uint16_t' or `uint32_t'
 304    (with machine dependent endianness and alignment)
 305      * UCS-2-INTERNAL, UCS-4-INTERNAL
 306        We implement these because they are the preferred internal
 307        representation of strings in Unicode aware applications.
 308
 309 Q: Support encodings mentioned in RFC 1345 ?
 310 A: No, they are not in use any more. Supporting ISO-646 variants is pointless
 311    since ISO-8859-* have been adopted.
 312
 313 Q: Support EBCDIC ?
 314 A: No!
 315
 316 Q: How do I add a new character set?
 317 A: 1. Explain the "why" in this file, above.
 318    2. You need to have a conversion table from/to Unicode. Transform it into
 319    the format used by the mapping tables found on ftp.unicode.org: each line
 320    contains the character code, in hex, with 0x prefix, then whitespace,
 321    then the Unicode code point, in hex, 4 hex digits, with 0x prefix. '#'
 322    counts as a comment delimiter until end of line.
 323    Please also send your table to Mark Leisher <mleisher@crl.nmsu.edu> so he
 324    can include it in his collection.
 325    3. If it's an 8-bit character set, use the '8bit_tab_to_h' program in the
 326    tools directory to generate the C code for the conversion. You may tweak
 327    the resulting C code if you are not satisfied with its quality, but this
 328    is rarely needed.
 329    If it's a two-dimensional character set (with rows and columns), use the
 330    'cjk_tab_to_h' program in the tools directory to generate the C code for
 331    the conversion. You will need to modify the main() function to recognize
 332    the new character set name, with the proper dimensions, but that shouldn't
 333    be too hard. This yields the CCS. The CES you have to write by hand.
 334    4. Store the resulting C code file in the lib directory. Add a #include
 335    directive to converters.h, and add an entry to the encodings.def file.
 336    5. Compile the package, and test your new encoding using a program like
 337    iconv(1) or clisp(1).
 338    6. Augment the testsuite: Add a line to each of tests/Makefile.in,
 339    tests/Makefile.msvc and tests/Makefile.os2. For a stateless encoding,
 340    create the complete table as a TXT file. For a stateful encoding,
 341    provide a text snippet encoded using your new encoding and its UTF-8
 342    equivalent.
 343    7. Update the README and man/iconv_open.3, to mention the new encoding.
 344    Add a note in the NEWS file.
 345
 346 Q: What about bidirectional text? Should it be tagged or reversed when
 347    converting from ISO-8859-8 or ISO-8859-6 to Unicode? Qt appears to do
 348    this, see qt-2.0.1/src/tools/qrtlcodec.cpp.
 349 A: After reading RFC 1556: I don't think so. Support for ISO-8859-8-I and
 350    ISO-8859-E remains to be implemented.
 351    On the other hand, a page on www.w3c.org says that ISO-8859-8 in *email*
 352    is visually encoded, ISO-8859-8 in *HTML* is logically encoded, i.e.
 353    the same as ISO-8859-8-I. I'm confused.
 354
 355 Other character sets not implemented:
 356 "MNEMONIC" = "csMnemonic"
 357 "MNEM" = "csMnem"
 358 "ISO-10646-UCS-Basic" = "csUnicodeASCII"
 359 "ISO-10646-Unicode-Latin1" = "csUnicodeLatin1" = "ISO-10646"
 360 "ISO-10646-J-1"
 361 "UNICODE-1-1" = "csUnicode11"
 362 "csWindows31Latin5"
 363
 364 Other aliases not implemented (and not implemented in glibc-2.1 either):
 365   From MSIE4:
 366     ISO-8859-1: alias ISO8859-1
 367     ISO-8859-2: alias ISO8859-2
 368     KSC_5601: alias KS_C_5601
 369     UTF-8: aliases UNICODE-1-1-UTF-8 UNICODE-2-0-UTF-8
 370
 371
 372 Q: How can I integrate libiconv into my package?
 373 A: Just copy the entire libiconv package into a subdirectory of your package.
 374    At configuration time, call libiconv's configure script with the
 375    appropriate --srcdir option and maybe --enable-static or --disable-shared.
 376    Then "cd libiconv && make && make install-lib libdir=... includedir=...".
 377    'install-lib' is a special (not GNU standardized) target which installs
 378    only the include file - in $(includedir) - and the library - in $(libdir) -
 379    and does not use other directory variables. After "installing" libiconv
 380    in your package's build directory, building of your package can proceed.
 381
 382 Q: Why is the testsuite so big?
 383 A: Because some of the tests are very comprehensive.
 384    If you don't feel like using the testsuite, you can simply remove the
 385    tests/ directory.
 386