\cfg{man-identity}{cvt-utf8}{1}{2004-03-24}{Simon Tatham}{Simon Tatham}
-\cfg{man-mindepth}{1}
-\C{cvt-utf8-manpage} Man page for \cw{cvt-utf8}
+\define{dash} \u2013{-}
-\H{cvt-utf8-manpage-name} NAME
+\title Man page for \cw{cvt-utf8}
-\cw{cvt-utf8} - convert between UTF-8 and Unicode, and analyse Unicode
+\U NAME
-\H{cvt-utf8-manpage-synopsis} SYNOPSIS
+\cw{cvt-utf8} \dash convert between UTF-8 and Unicode, and analyse Unicode
-\c cvt-utf8 [flags] [hex UTF-8 bytes and/or U+codepoints]
-\e bbbbbbbb iiiii iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
+\U SYNOPSIS
-\H{cvt-utf8-manpage-description} DESCRIPTION
+\c cvt-utf8 [flags] [hex UTF-8 bytes, U+codepoints, SGML entities]
+\e bbbbbbbb iiiii iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii
+
+\U DESCRIPTION
\cw{cvt-utf8} is a tool for manipulating and analysing UTF-8 and
Unicode data. Its functions include:
\b Look up Unified Han characters in the \q{Unihan} database and
provide their translation text.
-By default, \cw{cvt-utf8} expects to receive hex numbers (either
-UTF-8 bytes or Unicode code points) on the command line, and it will
-print out a verbose analysis of the input data. If you need it to
-read UTF-8 from standard input or to write pure UTF-8 to standard
-output, you can do so using command-line options.
+By default, \cw{cvt-utf8} expects to receive character data on the
+command line (as a mixture of UTF-8 bytes, Unicode code points and
+SGML numeric character entities), and it will print out a verbose
+analysis of the input data. If you need it to read UTF-8 from
+standard input or to write pure UTF-8 to standard output, you can do
+so using command-line options.
-\H{cvt-utf8-manpage-options} OPTIONS
+\U OPTIONS
\dt \cw{-i}
\dd Look up each code point in the Unihan database as well as the
main Unicode character database.
-\H{cvt-utf8-manpage-examples} EXAMPLES
+\U EXAMPLES
In \cw{cvt-utf8}'s native mode, it simply analyses input Unicode or
UTF-8 data. For example, you can give a list of Unicode code
... and \cw{cvt-utf8} gives you the UTF-8 encodings plus the
character definitions.
+If it's more convenient, you can specify those characters as SGML
+numeric entity references (for example if you're cutting and pasting
+out of a web page):
+
+\c $ cvt-utf8 '€' '–'
+\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+\c U-000020AC E2 82 AC EURO SIGN
+\c U-00002013 E2 80 93 EN DASH
+
Alternatively, you can supply a list of UTF-8 bytes...
\c $ cvt-utf8 D0 A0 D1 83 D1 81 D1 81 D0 BA D0 B8 D0 B9
\c midst of; hit (target); attain
\c U-00006587 E6 96 87 <han> literature, culture, writing
-\H{cvt-utf8-manpage-bugs} BUGS
+\U ADMINISTRATION
+
+In order to print the \cw{unicode.org} official name of each
+character, \cw{cvt-utf8} requires a file mapping code points to
+names. This file is in DBM database format, for rapid lookup.
+
+This database file is accessed using the Python \cw{anydbm} module,
+so its precise file name will vary depending on what flavours of DBM
+you have installed. The name Python knows it by is \cq{unicode}; it
+may actually be called \cq{unicode.db} or something similar.
+
+\cw{cvt-utf8} generates this DBM file itself starting from the
+Unicode Character Database, in the form of the file
+\cw{UnicodeData.txt} supplied by \cw{unicode.org}. It supports two
+administrative options for this purpose:
+
+\c cvt-utf8 --build /path/to/UnicodeData.txt /path/to/unicode
+
+Given a copy of \cw{UnicodeData.txt} on disk, this mode will create
+the DBM file and store it in a place of your choice.
+
+\c cvt-utf8 --fetch-build /path/to/unicode
+
+If you have a direct Internet connection, this will automatically
+download the text file from \cw{unicode.org} and process it straight
+into the DBM file.
+
+There is a second DBM file, known to Python as \cw{unihan}, which is
+required to support the \cw{-h} option. This one is built from the
+Unihan Database, distributed by \cw{unicode.org} as a zip file
+containing a text file \cw{Unihan.txt}.
+
+If you already have \cw{Unihan.txt} on your system, you can build
+\cw{cvt-utf8}'s \cw{unihan} DBM file like this:
+
+\c cvt-utf8 --build-unihan /path/to/Unihan.txt /path/to/unihan
+
+Or, again, \cw{cvt-utf8} can automatically download it from
+\cw{unicode.org}, unpack the zip file on the fly, and write the DBM
+straight out:
+
+\c cvt-utf8 --fetch-build-unihan /path/to/unihan
+
+\cw{cvt-utf8} expects to find these database files in one of the
+following locations:
+
+\c /usr/share/unicode
+\c /usr/lib/unicode
+\c /usr/local/share/unicode
+\c /usr/local/lib/unicode
+\c $HOME/share/unicode
+\e iiiii
+\c $HOME/lib/unicode
+\e iiiii
+
+If either of these files is not found, \cw{cvt-utf8} will still
+perform the rest of its functions.
+
+\U LICENCE
+
+\cw{cvt-utf8} is free software, distributed under the MIT licence.
+Type \cw{cvt-utf8 --licence} to see the full licence text.
-Command-line option processing is very basic. In particular, \cw{-h}
-must come before \cw{-i} or it will not be recognised.
+\versionid $Id$
~mdw / sgt / utils / blobdiff