This is the file INSTALL of the CJK macro package ver. 4.2.0 (13-Dec-1998).

Installation Guide
==================

First a check list where you can see whether you've done all steps to
install the CJK package and fonts. It is assumed that you want to install
both ttf2pk and hbf2gf.

    Have you installed a LaTeX 2e version newer or equal to 1996/12/01?
    For MULEenc.sty, even 1998/06/01 is necessary.

    Have you removed an older version of CJK? If not, do it now but don't
    forget to save your FD and other files you've changed! Don't forget
    also to remove the ttf2pk and hbf2gf binaries.

    Can the texinput tree of the CJK package be found by your TeX
    implementation? Have you activated subdirectory searching?

    Have you downloaded the needed fonts (either hbf or ttf)?

    If you have downloaded CJK font packages, have you moved the TFM files
    into your TFM-tree (or updated TFMINPUTS accordingly)? Ditto for VF
    files if needed (Korean only).

    Have you installed ttf2pk and ttf2tfm from the FreeType package?

    Have you run ttf2tfm to create the proper TFM files from your TrueType
    fonts?

    Have you updated the ttfonts.map file for ttf2pk? Have you updated the
    various hbf2gf config files? Have you copied them to the right places?
    Don't forget to install the SFD and other data files which define the
    various CJK subfonts and encodings.

    Have you modified and installed the script files for automatic font
    generation?

web2c/teTeX/NTeX users:

    Do you have a C compiler and a make program available for compilation?
    GNU gcc and GNU make are recommended.

    Have you updated special.map?

    Have you updated texmf.cnf or set the various environment variables?
    (TEXINPUTS, TFMFONTS, PKFONTS, T1FONTS, TTFONTS, TTF2PKINPUTS,
    TTF2TFMINPUTS, HBF2GFINPUTS)

    ttf2pk and hbf2gf should be in the same directory where your TeX
    binaries are (or you must set TEXMFCNF and probably TEXMF in the
    environment). Soft links won't work!

    Finally, have you run texhash (resp. mktexlsr) after finishing all other
    things?

emTeX users:

    Have you created a LaTeX format file which allows plain 8bit input and
    output without using any TeX Code Page (tcp)?

    Have you installed 4DOS (4OS2 resp. Take Command) for running the
    dvidrv.btm?

    Have you configured dvidrv.btm?

    Have you created and installed TFM files for fonts not in a CJK font
    package?

    Check whether you've updated all needed environment variables (TEXINPUT,
    TEXTFM, TTFONTS, TTFCFG, HBFONTS, HBFCFG) and your dvidrv configuration
    file or files (+font-files, +virtual-fonts).
    

In case of errors, verify the list step by step. Detailed information for
each step can be found in the documentation files of CJK. Under web2c or
teTeX, you can set the KPATHSEA_DEBUG environment variable to -1, then all
debugging info is shown and sent to stderr; it is *highly* recommended that
you read the kpathsea.info files (some nodes are broken in certain teTeX
versions/patchlevels, so check the INFO files directly for the missing
information in that case). Under emTeX, read the various documentation
files, especially dvidrv.doc and tex.doc, and check the log file of your dvi
driver.

    

UNIX (web2c and teTeX)
----------------------

o   If you can become root, rename the `texinput' directory tree of CJK
    into `CJK' or something else and add it to the web2c texinput tree
    (usually /usr/local/lib/texmf/tex/...)

    If you can't become root, modify the TEXINPUTS environment variable
    instead so that it includes the CJK directory; use a command similar to

        setenv TEXINPUTS :<your CJK directory>//

    to let TeX search the standard directories and your CJK tree, e.g.

        setenv TEXINPUTS :/home/joe_user/CJK/4_2.0/texinput//

    (Note the leading double colon -- for details see the kpathsea info
    files.)

o   Edit the FD files of the encodings you want to use to specify the fonts
    you have. An explanation of the additional size commands CJK provides
    can be found in fonts.doc .

    If you use the CJK font packages (see below) no changes are needed.

o   If necessary, create TFM (and PK) files from CJK bitmaps with hbf2gf
    (found in utils/hbf2gf). This program comes with a configure script; say
    `./configure --help' in the utils/hbf2gf directory for configuration
    options. You need a compiled kpathsea library and its header files; in
    most cases you will say

      ./configure --prefix=/usr/local/TeX --with-kpathsea-dir=<DIR>
      make
      make install

    for a normal compilation and installation. Replace `/usr/local/TeX' with
    a path to your TeX distribution, and <DIR> with the directory one level
    higher than the library resp. the include files themselves. Example:
    libkpathsea.a is in /usr/local/TeX/lib, kpathsea.h is in
    /usr/local/TeX/include; then <DIR> should be `/usr/local/TeX'.

    For teTeX 0.4, which comes with statically linked binaries only, read
    hbf2gf.doc how to compile kpathsea -- you will need kpathsea 2.6 and not
    a newer version for this teTeX version!

    See hbf2gf.doc, the man page (hbf2gf.1), and the documentation of the
    source file (hbf2gf.dvi) for further details. Usually it is sufficient
    to let hbf2gf create a complete set of TFM files; PK fonts will then be
    created on demand. To do this you need a patched MakeTeXPK resp. mktexpk
    script; you should apply the proper patch(es) from utils/hbf2gf/scripts.

    The CJK font packages already contain TFM (and VF) files arranged for
    the (new) TDS directory structure (e.g.
    texmf/fonts/tfm/gb2312/gsfs14/gsfs1401.tfm ...); add it directly to your
    texmf tree if you can become superuser and adjust T1FONTS and TEXCONFIG
    in the texmf.cnf configuration file. If not, you must set or modify the
    T1FONTS/TEXCONFIG environment variables to reflect the new locations of
    the bitmap/hbf files. For kpathsea 2.6 (used teTeX 0.4), specify
    DVIPSHEADERS instead of T1FONTS.

o   Free CJK TrueType fonts (for non-commercial use) are available at
    ftp.ifcss.org (and its mirrors) in /pub/software/fonts/... and some
    other places (you can e.g. consult ftp archives of major companies
    offering WWW browsers with support for Asian languages).

    Please note that many CJK TrueType fonts only have a Unicode mapping
    table -- the best solution is to add a language specific cmap (Big5, KS,
    etc.) tuned to the glyphs in the font. In case you want to use the
    uw*.ttf fonts from ftp.ifcss.org, this work has already be done; you can
    download and apply the uwpatch package (from the CJK font directory) and
    ask Richard Kinch (kinch@holonet.net) for his ttf_edit program.
    Richard's program will add resp. replace such character map tables. Use
    this package as a guide for adding cmaps to other CJK TrueType fonts.

    An easier solution is to use the SFD files from the ttf2pk package
    starting with the letter `U' (e.g. UKS.sfd) which will map Unicode fonts
    to language specific encoded subfonts as needed by the CJK package
    (ttf2pfb still lacks these features).

    The ttf2pk package (found in the contrib/ttf2pk directory of
    ftp://ftp.freetype.org/pub/freetype/devel/freetype-current.tar.gz)
    contains the two programs ttf2tfm and ttf2pk for converting TrueType
    fonts into TFM and PK fonts respectively (note that this package is
    not restricted to CJK TrueType fonts; it will work with all TT fonts).
    Read the manual pages and the documentation for further information.

    The ttf2pfb package (found in the contrib/ttf2pfb directory of
    ftp://ftp.freetype.org/pub/freetype/devel/freetype-current.tar.gz)
    contains programs to convert CJK TrueType fonts to PostScript fonts (it
    doesn't work well currently for non-CJK fonts and has slight problems
    with composite fonts).

    Note: In previous versions of CJK you could find the utility programs
          ttf2pk and ntu2cjk which have been moved to extra archives. These
          programs are no longer supported resp. developed further; the
          above mentioned programs ttf2pk and ttf2pfb do a much better job.

    Choose the method you prefer.

o   The so-called `Jackson' font, a freely available, Big 5 encoded
    PostScript font (which is incomplete unfortunately), can be converted
    into a form usable by the CJK package with tools in the ntu2cjk archive.

o   It is recommended to add the CJK fonts you use to the file special.map:
    Assuming that your font will be installed to

      $TEXMF/fonts/pk/modeless/gb2312/gsfs14/

    the proper entry would be

      gsfs14  gb2312  gsfs14
 
o   Compile the small preprocessors in the utils subdirectories with

        cc -O -s -o bg5conv bg5conv.c
        cc -O -s -o sjisconv sjisconv.c
        cc -O -s -o cefconv cefconv.c
        cc -O -s -o cef5conv cef5conv.c
        cc -O -s -o cefsconv cefsconv.c

    and move them into TeX's bin directory (together with the shell scripts)
    or modify the PATH environment variable appropriately. (`cc' can be
    any C compiler.)

    The script files `...latex' make the use of these programs transparent.

o   Move the man pages into your man directory tree.

o   If you want to use Mule/emacs 20 together with the CJK package, you
    should install cjk-enc.el (in utils/lisp). See cjk-enc.doc for
    documentation.  Choose the correct cjk-enc.el version.

    Move cjk-enc.el to a place which will be searched by Mule (e.g.
    /usr/local/lib/mule/site-lisp) and put the following line into your
    .emacs file:

        (load-library "cjk-enc")

    The default directory for emacs 20 is /usr/local/share/emacs/site-lisp.

o   If you mainly write Chinese or Japanese with Emacs or Mule, consider the
    use of cjktilde.el (in utils/lisp). This file contains a minor mode
    which exchanges the tilde key with the space key. See the documentation
    of \CJKtilde for the reasons to use `~' in most cases instead of ` '.

    To install, move cjktilde.el to a place which will be searched by Emacs
    or Mule (e.g. /usr/local/lib/mule/site-lisp) and put the following line
    into your .emacs file:

        (load-library "cjktilde")

    To toggle the CJK tilde mode say

        M-x cjk-tilde-mode

    You can then assign cjk-tilde-mode to a key, e.g. shift-insert.

o   If you use AUCTeX you can try cjkspace.el instead of cjktilde.el; it
    works in a similar (but not identical) way and is special to LaTeX
    buffers. Move the file to the local lisp directory and put the following
    lines into your .emacs file:

        (autoload 'CJK-insert-space "cjkspace"
          "Insert tildes appropriately in CJK document." t)
        (defun my-LaTeX-mode-hook ()
          "My personal key definitions for LaTeX mode."
          (define-key LaTeX-mode-map "\ " 'CJK-insert-space)
          )
        (add-hook 'LaTeX-mode-hook 'my-LaTeX-mode-hook)

    Please read the documentation in the file cjkspace.el .


DOS and OS/2 (emTeX)
--------------------

o   Precompiled binaries are available in the CJK-4.2.0.bin.zip package.

o   Note that some UNIX specific shell scripts and other files have names
    longer than 8 characters. You will not need them. Some of the TeX input
    files have lower and uppercase characters in its filenames, but none of
    the filenames will collide under DOS.

o   Move the `texinput' directory tree to a place where TeX scans for input
    files (and rename it to `cjk' or something else). Note that its
    subdirectories are specific to encoding schemes. emTeX allows for
    recursively scanned search paths, thus retaining the directory tree is
    possible.

    Example:

      CJK files:      c:\emtex\texinput\cjk\...
      environment:    set emtexdir=c:\emtex
                      set texinput=%emtexdir%\texinput!!

o   Move the various EXE files into a directory in the path (e.g.
    c:\emtex\bin). They have been compiled with the emx compiler; the
    executables will run under both DOS and OS/2 (also under Windows). You
    need the emxrsx.zip package of emTeX (available on CTAN) additionally
    for the runtime library.

o   Move the various BAT files (for DOS) and/or the CMD REXX scripts (for
    OS/2) into a directory in the path (e.g. c:\emtex\bin).

o   Edit the FD files of your encoding(s) to specify the fonts you have. An
    explanation of the additional size commands CJK provides can be found
    in fonts.doc .

    If you use the CJK font packages (see below) no changes are needed.

o   If necessary, create TFM (and PK) files from CJK bitmaps with hbf2gf
    (found in utils\hbf2gf). See hbf2gf.doc and the documentation of the
    source file (hbf2gf.dvi) for explanation. Usually it is sufficient to
    let hbf2gf create a complete set of TFM files; PK fonts will then be
    created on demand (this is done with the dvidrv.btm shell script of
    the CJK package).

    You need 4DOS or 4OS/2 (these are shareware replacements for
    command.com) to run dvidrv.btm.

    dvidrv.btm should also work with Take Command/16, Take Command/32, or
    Take Command for OS/2.

    The CJK font packages already contain TFM (and VF) files (arranged for
    the (new) TDS directory structure, e.g.
    texmf\fonts\tfm\gb2312\gsfs14\gsfs1401.tfm ...); unpack the font
    packages in the root directory with

        gzip -d CJK_font_archive.tgz
        tar xvf CJK_font_archive.tar        ,

    and rearrange the directory structure as suggested below (to make the
    file search mechanism of emTeX faster) and modify the appropriate
    environment variables to include the additional directories. The same
    holds for the CJK bitmap fonts, its HBF header files and the hbf2gf
    configuration files.

    [Note: Binaries for the gzip and tar archive programs can be found on
    CTAN in the utils subdirectory.]

    Example: 

        jfs56.tar.gz (should be ftp'ed as jfs56.tgz if you work under DOS
                      since two dots are not allowed)

      suggested final directory structure (after unpacking and rearranging):

        c:\texmf\fonts\tfm\gsfs1401.tfm ...
        c:\texmf\hbf2gf\gsfs14.cfg
        c:\texmf\fonts\hbf\gb2312\jfs56\jfs56.a ...
      [ c:\texmf\fonts\pk\modeless\XXXdpi\gsfs1401.pk ... ]

      Add these lines to the end of autoexec.bat:

        set texmfdir=c:\texmf
        set cjkpk=%texmfdir%\fonts\pk
        set textfm=%textfm%;%texmfdir%\fonts\tfm

      Under OS/2, add similar lines (but with expanded pathnames) to the end
      of config.sys:

        set texmfdir=c:\texmf
        set cjkpk=c:\texmf\fonts\pk
        set textfm=<your old textfm path>;c:\texmf\fonts\tfm

      Changes in gsfs14.cfg:

        pk_directory  $texmfdir\fonts\pk\modeless\432dpi\
        tfm_directory $texmfdir\fonts\tfm\

      Changes in dvidrv.btm:

        set pkdir=%texmfdir%\fonts\pk
        set ttfcfg=%texmfdir%\ttf2pk
        set hbfcfg=%texmfdir%\hbf2gf

        set pre_dpi=
        set post_dpi=dpi

      Changes in a dvi driver configuration file (.cnf) for emTeX:

        +font-files:{<your old pk path>,$texmfdir:fonts\modeless}\@Rrdpi\@f.pk

o   Free CJK TrueType fonts (for non-commercial use only) are available at
    ftp.ifcss.org (and its mirrors) in /pub/software/fonts/... and some
    other places (you can e.g. consult ftp archives of major companies
    offering WWW browsers with support for Asian languages).

    The ttf2pk package (found in the contrib/ttf2pk directory of
    ftp://ftp.freetype.org/pub/freetype/devel/freetype-current.tar.gz)
    contains the two programs ttf2tfm and ttf2pk for converting TrueType
    fonts into TFM and PK fonts respectively (note that this package is
    not restricted to CJK TrueType fonts; it will work with all TT fonts).
    Read the manual pages and the documentation for further information.

    The ttf2pfb package (found in the contrib/ttf2pfb directory of
    ftp://ftp.freetype.org/pub/freetype/devel/freetype-current.tar.gz)
    contains programs to convert CJK TrueType fonts into PostScript fonts
    usable by dvips.

    Note 1: In previous versions of CJK you could find the utility programs
            ttf2pk and ntu2cjk which have been moved to extra archives.
            These programs are no longer supported resp. developed further;
            the above mentioned programs ttf2pk and ttf2pfb do a much better
            job.

    Note 2: Binaries can be also found at ftp.freetype.org .

    Choose the method you prefer.

o   The so-called `Jackson' font, a freely available, Big 5 encoded
    PostScript font (which is incomplete unfortunately), can be converted
    into a form usable by the CJK package with tools in the ntu2cjk package.
 
o   You will find the standard hangul fonts for 300dpi (cx) and 600dpi
    (ljfour) resolution in the following archives:

        han.300.tar.gz
        han1.300.tar.gz
        han.600.tar.gz
        han1.600.tar.gz
        han.tfmvf.tar.gz
        han1.tfmvf.tar.gz       ;

    it's necessary to rearrange not only the directory structure but the
    names of the dpi directories too: the TeX directory standards specifies
    `dpiXXX', but emTeX provides by default `XXXdpi'.

    The final locations of the packages' files should be

        c:\texmf\fonts\tfm\
        c:\texmf\fonts\vf\
        c:\texmf\fonts\pk\{cx,ljfour}\XXXdpi\

    Additionally to the above example you should add this to the end of
    autoexec.bat:

      set cjkvf=%texmfdir%\fonts\vf

    or config.sys for OS/2:

      set cjkvf=c:\texmf\fonts\vf

    Assuming that you use the 300 dpi Hangul fonts (for a cx printer) you
    should do the following changes in your dvi driver configuration file
    (suffix `.cnf') for emTeX (still continuing the above example):

      +font-files:{<your old pk path>,$texmfdir:fonts\{modeless,cx}}\@Rrdpi\@f.pk
      +virtual-fonts:{<your old vf path>,$texmfdir:fonts}\@f.vf


Other systems
-------------

CJK has only been tested with web2c and emTeX; nevertheless, it should run
on other systems too:

    First of all, try to compile hbf2gf. Since it is written in ANSI C it
    should be fairly portable (if patches are needed please send them to the
    author; most likely you have to modify the file operating routines). If
    this fails it is necessary to build the various PK fonts on a different
    machine. It has been reported that older GNU compilers on the NeXT have
    difficulties with `%i' formatting parameters in the HBF API (hbf.c):
    replace all occurrences of `%i' with `%d'.

    If there exists an equivalent to MakeTeXPK (or dvidrv.btm), try to
    modify it similar to CJK's changes so that CJK fonts can be created on
    the fly. If this fails you can only use precompiled sets of CJK fonts.

    The rest should be rather trivial for the experienced user; again,
    please write the author if you have successfully installed the package
    and send a report how to install.


How to get CJK and related software
-----------------------------------

    o   You will find CJK and software related to TeX at the CTAN hosts
        (Comprehensive TeX Archive Network). These completely identical ftp
        servers (concerning TeX software) are

            ftp.dante.de    DANTE (Deutsche Anwendervereinigung fuer TeX)
                            Heidelberg (Germany)
            ftp.tex.ac.uk   Cambridge University
                            Cambridge (England)
            ctan.tug.org    TUG (TeX Users Group)
                            Massachusetts (USA)

        You should use the nearest one, or even better, a local mirror of a
        CTAN host (say `finger ctan@ftp.dante.de' to get a list of all
        known mirrors).

        CJK will be found unpacked. To receive the complete package, go to
        the parent directory of CJK and say

            get CJK.zip
          or                (whatever is appropriate for your system)
            get CJK.tar.gz 

        The CJK directory and all its subdirectories will be sent to you in
        compressed form. Be aware that not all mirrors of CTAN sites support
        compression of directories.

    o   The main site for Chinese related software is ftp.ifcss.org (USA).
        Mirrors are ftp.edu.tw (Taiwan), ftp.cnd.org (USA), and
        ftp.mpi-sb.mpg.de (Germany) together with some others in Asia. There
        you find free Chinese fonts, text editors, etc.

    o   The main site for Korean related software is
        cair-archive.kaist.ac.kr (Korea). A German mirror site is
        ftp.linguistik.uni-erlangen.de/pub/MIRROR.ftp.kaist.ac.kr/hangul. A
        65x65 pixel Hanja font (hanja65) can be found at ftp.ifcss.org too.

    o   Unicode fonts and utilities can also be found at ftp.ifcss.org
        (USA); mapping tables are available at unicode.org .

    o   Mule 2.3 can be found at etlport.etl.go.jp (Japan); European mirrors
        are

           ftp.funet.fi (Finland, sometimes out of date),
           ftp.linguistik.uni-erlangen.de (Germany), and
           ftp.lrz-muenchen.de/pub/culture/ (Germany).

        [Note: You will need Mule 2.3 only for right-to-left scripts like
        Arabic or Hebrew which aren't yet supported in emacs 20. Otherwise,
        I strongly recommend to get FSF emacs 20.3 or newer which is
        available from ftp.gnu.org (USA) and its many mirrors.]


---End of INSTALL---
