Subject: CJK 2.1 out (Chin/Kor/Jap for LaTeX2e)

From: Werner Lemberg <[email-masked]>
Date: Mon, 03 Oct 94 15:08:32 MEZ

In one or two days the new CJK package is available from the CTAN hosts.

You will find the package unzipped in language/chinese/CJK. Use the CTAN
packing functions to compress it again during ftp.

new:        CJK* environment added: space after CJK characters will be
            swallowed

            Utility programs hbf2hbf and hbf2cjk added
            [hbf2cjk is a patched version of hbf2pk to support CJK encoding]

changed:    new Big5 encoded fonts needed (more compressed) - saves
            about 12 TeX subfonts per Big5 encoded font

            pmC emulation will now use compatible font names, i.e.
            wcb5a1, wcb5a2 etc.

Appended you will find the readme file.

Happy TeXing!

    Werner Lemberg

This is the LaTeX2e style package CJK.zip Version 2.1 (28-Sep-1994)
===================================================================

It contains the following files:

    CJK.txt      This file
    CJK.sty      A LaTeX2e style file to enable CJK (Chinese/Japanese/Korean)
                 logographs (i.e. Hanzi/Kanji/Hangul) with LaTeX2e
    CJK.enc      Master Encoding File (at the moment only for Chinese and
                 Korean)
    standard.enc
    Bg5.enc
    hangul.enc
    pmCsmall.enc
    pmCbig.enc   Encoding scheme files
    Bg5.chr
    standard.chr
    pmC.chr      Character encoding files
    Uhangul.fd   Font definition file for standard Hangul fonts
    UBg5.fd
    UGBs.fd
    UGBt.fd      Font definition files for Chinese (examples only!)
    UpmC-Bg5.fd
    UpmC-GBs.fd
    UpmC-GBt.fd  Font definition files for (old) pmC-fonts
    vf/*.vf
    tfm/*.tfm    virtual fonts and metric files for hangul standard fonts to
                 use in combination with the font libraries lj_han and lj_han1
                 (available at the CTAN hosts)

    utils/hbf2cjk.c         Source file for hbf2cjk (at the moment only for
                            UNIX)
    utils/hbf2hbf.w         CWEB source file for hbf2hbf
    utils/hbf.h
    utils/hbf.c             Ross Paterson's HBF API (with small extensions)
    utils/Makefile          Makefile for hbf2hbf
    utils/Makefile.hbf2cjk  Makefile for hbf2cjk (only for UNIX)

This is freely distributable under the GNU Public License.

                **************************************
                *  The .fd files have been changed!  *
                **************************************

Use
---

Use CJK.sty as a package, e.g.

    \documentclass{article}
    \usepackage{CJK}            .

Two new environments \begin{CJK}{encoding}{shape} ... \end{CJK} and
\begin{CJK*}{encoding}{shape} ... \end{CJK*} are defined:

    encoding        the following coding schemes are currently implemented in
                    CJK.enc:

                        Bg5 (Big5)
                        GBs (GuoBiao with simplified characters)
                        GBt (GuoBiao with traditional characters)
                        hangul (only hangul syllables and elements, no hanja).

                    It's very easy to add different encoding schemes.

                    For compatibility with the pmC package three additional
                    encodings are defined: pmC-Bg5, pmC-GBs, and pmC-GBt. It's
                    not encouraged to use these encodings because of wasting
                    fonts. If possible, convert your original CJK-bitmaps with
                    bmf2gf or hbf2cjk (see below) to CJK-encodings.

    shape           It is impossible to know what fonts are available at your
                    site; look at the example .fd-files how to create
                    appropriate .fd-files suiting your needs. If you use the
                    hangul environment, this parameter is unused (see below).

    CJK* will swallow unprotected spaces and newlines after a CJK character,
    whereas CJK will not.

This is a very realistic example:

    \begin{CJK}{GBs}{kai}
    ...
    Text in GuoBiao encoding
    ...
    \end{CJK}

How it works
------------

Asiatic logographs can't be represented with one byte per character. (At
least) two bytes are needed, and the most common encoding schemes (GB, Big5,
JIS, KS etc.) have a certain range for the first byte (usually 0xA1-OxFE or a
part of it) which signales that this and the next byte represents an Asiatic
logograph. This means that plain ASCII-text (i.e. characters between 0x00 and
0x7F) will be left undisturbed, and most characters of the extended ASCII
character set (0x80-0xFF) will be assigned to a CJK encoding.

CJK.sty will make the characters 0xA1-OxFE active (and in the file CJK.enc you
should inactivate those characters not needed to be active if you add a new
encoding scheme) inside of an environment and assigns the macros \CJK@char and
\CJK@charx to the active characters which select the proper font. The real
mechanism is a bit more complicated to assure robustness (it was borrowed and
modified from german.sty).

The encodings
-------------

CJK.sty defines \CJK@standardEncoding, \CJK@Bg5Encoding, \CJK@hangulEncoding,
and for compatibility with pmC, \CJK@pmCsmallEncoding and \CJK@pmCbigEncoding.

\CJK@standardEncoding should be used for encodings with the second byte in the
range 0xA0-0xFE (GB, JIS etc).

\CJK@Bg5Encoding should be used for Big5 encodings (e.g. ETen fonts) with the
second byte in the range 0x40-0xFE.

\CJK@hangulEncoding is a special (and slightly modified) case of
\CJK@standardEncoding, containing only values for hangul syllables and
elements.

\CJK@pmCsmallEncoding and \CJK@pmCbigEncoding can be activated with \pmCsmall
(this is the default) and \pmCbig inside the CJK environment. Note that the
original pmC fonts have two character sizes per font (the bigger ones with an
offset of -128); pmC-Big5 encoded fonts cannot contain big characters. The
names of the fonts in the UpmC-xxx.fd files reflect the modifications added by
Marc Leisher ([email-masked]) to the original poor man's Chinese (pmC)
package written by Thomas Ridgeway ([email-masked]).

The fonts
---------

CJK.sty uses NFSS (New Font Selection Scheme) which has some advantages over
the font selection offered with pmC:

    o   TeX fonts are loaded only on demand. This is especially useful with
        Asiatic logographs. If you have e.g. three Chinese characters in your
        text, pmC must load the whole Chinese font (about 85 TeX fonts),
        whereas LaTeX2e loads three fonts normally.

    o   As long as the limit of 256 TeX fonts will not be exceeded, you can
        use as many CJK fonts as you like (e.g. simplified and traditional
        Chinese characters together with Japanese fonts in different sizes)
        --- pmC is limited to two sizes and can only have two CJK fonts at the
        same time.

        In the web2c-TeX package (for UNIX) you will find a patch which allows
        the use of more than 256 TeX fonts.

    o   You need not to care about the right size of the CJK fonts in
        footnotes etc. It will obey the NFSS (although changing the other
        attributes except font series and size will be done with \CJKenc and
        \CJKshape).

        For font selection in a hangul environment see below.

        Of course you must have proper sizes of your CJK fonts --- if you
        have, say, 48x48 and 64x64 bitmap fonts (or more), I recommend bmf2gf
        to convert them directly to .pk-fonts. If you have only 24x24 size (as
        most of the public domain fonts are), you can magnify them using
        bmf2gf but only with integer magnifications.

If you chose one font per active character as with the pmC macros, you would
waste character space (256 characters per font are possible with TeX 3).
Therefore CJK.sty expects the whole Asiatic font splitted in TeX fonts with
256 characters each.

An example:

    GuoBiao-encoded simplified characters in song style 12pt:
    ^               ^                        ^^         ^^

              first byte  second byte       TeX font  offset
              ----------------------------------------------
                 0xA1      0xA1-OxFE        gsso1201     0
                 0xA2      0xA1-0xFE        gsso1201    94
                 0xA3      0xA1-0xE4        gsso1201   188
                 0xA3      0xE5-0xFE        gsso1202     0
                 0xA4      0xA1-0xFE        gsso1202    26
                 0xA5      0xA1-0xFE        gsso1202   120
                                     .
                                     .
                                     .
                 0xFE      0xA1-OxFE        gsso1235    38

To create such splitted fonts you can use the package bmf2gf (written by me)
which should be at the same place where you've found this package (I upload my
TeX packages to the CTAN hosts). Enclosed here in the CJK package you will
find the CWEB source code of the program hbf2hbf which you should use instead
of hbf2bmf of the bmf2gf package. The latter only supports the Big5 encoding
scheme of CJK versions before 2.1 .

hbf2hbf converts HBF fonts into BMF files (plus a HBF header file) bmf2gf can
understand. See the next section for the syntax.

To make hbf2hbf, you will need the GNU C compiler and GNU make, and the CWEB
package.

For converting to .pk-files via bmf2gf, you should get the appropriate HBF
(Hanzi Bitmap Font) header files from ifcss.org (or create if you can't find
the right one); almost all Chinese bitmap fonts in the public domain together
with their HBF headers are collected there. These HBF files document the CJK
fonts completely.

Using hbf2cjk
-------------

If bmf2gf does not satisfy you, try hbf2cjk. This program is a patched version
of HBFtoPK written by S. Simpson <[email-masked]>. To execute hbf2cjk,
you additionally need pnmscale and pgmtopbm of the pbmplus package and
pbmtopk. Consider this as a beta version which works unmodified only under
UNIX.

hbf2cjk is much more slower than bmf2gf - it will call pnmscale and pgmtopbm
for each character. The advantage is that you can scale the fonts with any
(reasonable) value.

To make hbf2cjk, you will need the GNU C compiler and GNU make.
Say `make TARGET -fMakefile.hbf2cjk', where TARGET can be `unix' or
`unixdebug'.

You should first convert your original CJK font and HBF header with hbf2hbf
into a temporary font file and HBF header:

Syntax:

    hbf2hbf output_font_name_without_extension input_HBF_header

Then call hbf2cjk to build the needed TeX subfonts:

Syntax:

    hbf2cjk HBF_file fontname resolution family encoding

The `font' parameter corresponds to \CJKshape; `family' and `encoding' will
appear as identifiers in the .tfm files.

An example:

    input files: jfs56.a - jfs56.e, jfs56.hbf

    program calls: hbf2hbf temp jfs56.hbf
                   hbf2cjk temp.hbf gsfs13 300 "Jianti FanSong" "Big5"

    output files: gsfs1301.300pk  - gsfs1332.300pk
                  gsfs1301.tfm    - gsfs1332.tfm

[gsfs: GuoBiao simple encoded FanSong style]
       ^       ^              ^  ^

It's hard to overcome the DOS restriction of 8 characters in a file name if
you need two characters as a running number...

Korean input
------------

(The status of this feature is experimental. I can't speak Korean and would
 be glad to hear comments from people who have any idea what is happening
 here :-)

There are already different packages handling Hangul: hlatex, htex etc.; there
is one package which also can handle hanja: jhtex.

The great difference of the packages just mentioned compared to CJK is the use
of a preprocessor which converts text files containing KS encoded text into a
TeX file. To do so has some advantages, but the output is completely
unreadable. Additionally the output lines become rather lengthy (a two byte
character code will be converted into a string up to 11 characters), which
some editors may confuse; and if you have a text which contains Chinese or
Japanese also, you can't use KS to TeX converters because the code ranges
overlap and the converters are not able to recognize which is Korean and which
is not.

In contrast, CJK does not need a preprocessor and the problems mentioned above
are nonexistent, but you get nothing for free: CJK uses the virtual font
mechanism to map the hangul syllables onto Hangul Elements (11 virtual fonts
map to 2 real fonts), whereas preprocessors directly use the real fonts.

CJK's hangul support is thought for users who write texts in a non CJK
language and who want to input some hangul characters, possibly mixed with
Chinese or Japanese.

If you want a complete Korean environment, I recommend jhtex. There you will
also find a hangul.sty which modifies (among others) the sectioning commands
to enable Korean chapter counting and Korean headers.

To use the hangul environment, say

    \begin{CJK}{hangul}{}
    ...
    \end{CJK}       .

These font switches are available inside the environment:

    fonts from hLaTeX:

    *   \mj  MyoungJo   (default)
        \gt  Gothic
        \gs  BootGulssi
        \gr  Graphic
        \dr  Dinaru

    fonts from jhTeX:

    *   \hgt Hangul Gothic
    *   \hmj Hangul MyoungJo (MunHwaBu fonts)
    *   \hpg Hangul Pilgi
        \hol Hangul Outline (MyoungJo)

If a font is marked with a star, bold series are available.

You will find the fonts in the lj_han and lj_han1 packages. These are emTeX
libraries for 300 dpi resolution which can be easily converted back to .pk
fonts using the fontlib package of emTeX. If you need different resolutions,
you must obtain the original metafont sources of the hlatex_mf.tar.gz and the
jhtex packages. Note that the shapes of Hangul elements are not satisfactory,
and archaic hangul elements are still missing.

The .fd-files
-------------

It is now possible to define CJK fonts as easy as normal TeX fonts!

CJK.sty defines four new size commands:

    CJK         corresponds to `' (empty)
    sCJK        corresponds to s
    CJKfixed    corresponds to fixed
    sCJKfixed   corresponds to sfixed               .

The difference between these size functions and the original commands defined
by LaTeX2e is that a CJK size function defines a class of fonts.

If you say as an example

    \DeclareFontShape{U}{Bg5}{m}{song}{<6> <7> <8> sCJKfixed * b5so07}     ,

LaTeX2e searches for fonts named b5so0701 - b5so0758 if the font size is 6, 7
or 8 pt; with other words, the CJK size functions append two digits to select
the proper subfonts. These digits are defined in the \CJK@...Encoding macros;
the macro \CJK@plane holds the current value (for pmC emulation, \CJK@plane
holds hexadecimal numbers).

See the example .fd files how to define font substitutions additionally.

To use CJK fonts as defined in older versions of CJK, you must rename all .pk
and .tfm files and exchange subfont and size values:

    old name:   b5so017     new name: b5so0701
                b5so027               b5so0702
                .                     .
                .                     .
                .                     .

Caveats
-------

    o   You can of course use CJK-environments inside of a CJK-environment,
        but it is possible that you must increase the so called save size
        (with emTeX you can adjust this with -ms=...).

        The CJK package has an optional argument which controls the scope of
        CJK environments:

            global          \lccode, \uccode, \catcode and the activation of
                            the characters 0xA1-0xFE will be globally modified
                            (\lccode and \uccode reset to 0). This is the most
                            economical mode concerning save size, but you
                            can't have CJK environments inside of CJK
                            environments or other environments which
                            manipulate the character range 0xA1-0xFE.

                            Packages which change some of the above values
                            only once (e.g. in the preamble) will also not
                            work after the first use of a CJK environment.

            local           Only \lccode and \uccode will be modified
                            globally. This is the default. You can stack
                            environments.

            encapsulated    If you want to use DC fonts outside of the CJK
                            environment with \uppercase and \lowercase working
                            correctly, you must use this option. All values
                            mentioned above will be local, so you can stack
                            environments. This option probably causes an
                            overflow of the save size.

        Say

            \usepackage[option]{CJK}

        to activate 'option'.

    o   There is an other way to overcome the problem of stacked environments.
        CJK implements two low level CJK attribute switches: \CJKenc and
        \CJKshape, which take the same arguments as the corresponding values
        of the CJK environment. If you need two different encodings/shapes at
        the same output line, you must use these macros. An example:

            \begin{CJK}{GBs}{song}
            ... Text in GBs song ... \CJKenc{GBt}
            ... Text in GBt song ... \CJKshape{kai}
            ... Text in GBt kai ...
            \end{CJK}

        As with \begin{CJK}{...}{...}, you should start a new line after
        \CJKenc to assure that possibly new activated characters get their
        active meaning.

    o   The characters \, {, and } are used as second bytes in the Big5
        encoding. If you write Big5 text, you should use the Bg5text
        environment which changes the category codes of these characters. The
        command prefix is now the forward slash /, and the grouping characters
        are ( and ) respectively.

        An example:

            \begin{CJK}{Bg5}{song}
            \begin{Bg5text}
            ....
            /begin(center)
            ....
            /end(center)
            ....
            /end(Bg5text)
            \end{CJK}

        To get the /, (, and ) characters, write //, /(, and /) inside
        the Bg5text environment.

    o   Instead of using the Bg5text environment, you can protect the
        offending second bytes with a backslash, i.e. \{, \}, \\.
        This will not increase the readability of the Chinese text, but for
        short texts it's perhaps more comfortable. Alas, it doesn't work
        in page header commands because the macros \{ etc. will not be
        expanded.

    o   Be careful not to use any commands inside the Bg5text environment
        which write something into an external file (commands like \chapter
        etc.).

    o   If it's not possible to avoid Big5 character codes with \, {, or }
        outside of the Bg5text environment (e.g. having Big5-text in a
        \chapter or \section command), you can replace them with the \CJKchar
        macro manually:

            \section{This is a problematic Big5 character: \CJKchar{169}{92}}

        The parameters are the first and second byte of the Big5 character
        code. You can also use hexadecimal or octal notation.

    o   You can't use Big5 characters in any command which uses \uppercase or
        \lowercase, i.e. \chapter, \article etc. --- this affects all standard
        document classes, which convert page headers to uppercase.

        It's possible to overcome this restriction by substituting all
        affected Big5 characters with the appropriate \CJKchar, i.e. for
        \uppercase characters with the second byte in the range to a-z (and
        A-Z for \lowercase respectively).

        A quick and dirty solution to disable \uppercase is to say

            \let\uppercase\relax

        before \begin{document}, but be aware that some commands like \Roman
        will behave unexpectedly.

        The clean way would be either to use a document class which does not
        convert headers to uppercase or to write a small package modifying the
        sectioning commands to remove the \uppercase commands.

    o   The same holds for ALL CJK encoding schemes if you use DC fonts
        because these 8-bit fonts have most \lccode's and \uccode's set in the
        range 0x80-0xFF.

    o   You should define for each TeX font size a CJK font (as an example,
        use sCJKfixed for good sizes and CJKfixed for bad sizes, and LaTeX2e
        will complain loudly about wrong sizes on the screen).

        LaTeX2e will also do the job if some size definitions are missing
        (using defined sizes), but expect a font warning for each (!) CJK
        character affected in verbatim environments.

Possible errors
---------------

    o   If you write Chinese (or Japanese) text, don't forget to suppress the
        linefeed character with a trailing `%' in the CJK environment,
        otherwise you get unwanted spaces in the output. On the other side,
        say `\ ' or something similar inside the CJK* environment to get a
        space after a CJK character.

    o   If you get the error message: "\CJK@min (or \CJK@max) undefined", you
        should insert a \newpage before saying \end{CJK}. This can happen if
        LaTeX writes the headers (or footers) of a page containing Chinese
        characters after closing the CJK environment.

    o   If you get overfull hboxes caused by CJK characters, try to increase
        \CJKglue. It defines the glue between CJK characters; default value is

                \hskip 0pt plus 0.8pt   .

        A \discretionary will be inserted by CJK before a Chinese character,
        and none after. You should separate non-Chinese text from CJK
        characters with spaces to enable hyphenation.

    o   If you encounter a TeX stack overflow caused by {\CJKenc{...} ....},
        you should write

            \CJKenc{new_encoding} ... \CJKenc{old_encoding}

        instead. Or (better) increase the stack size as discussed above.

Author
------

Werner Lemberg ([email-masked])

Please report any errors or suggestions to this email-address.