This is the file INSTALL of the CJK macro package ver. 4.5.1 (17-Jun-2002). Installation Guide ================== It is probably a good idea to get a packaged version of CJK -- be warned that installing CJK is *not* trivial. The easiest solution is to use the TeX Live CD which is distributed among members of TeX user groups worldwide. It comes with a ready-to-run CJK setup together with basic CJK fonts (in outline format if possible) for all encodings. Mike Fabian has bundled CJK with a lot of Asian fonts; his RPMs are available from ftp://ftp.suse.com/pub/people/mfabian/ Even if you don't use the SuSE distribution it should be straightforward to install the fonts. RPMs from the Taiwanese Linux Group for the Red Hat distribution are available here: ftp://cle.linux.org.tw/pub/CLE/i386/RedHat/RPMS/CJK-xxx.i386.rpm For FreeBSD try this: http://www.freebsd.org/ports/chinese.html MikTeX also provides packages for CJK. Here a check list for the impatient (experienced) user which tries to show 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. Detailed explanations can be found below. --- begin checklist --------------------------------------------------------- Have you installed a LaTeX 2e version newer or equal to 2001/06/01? The version of LaTeX is given in each log file produced by LaTeX. Have you removed an older version of CJK? If not, do it now but don't forget to save your FD and other files which you have 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 bitmap 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 1 package? Note that FreeType 2 won't work. Have you run ttf2tfm to create the proper TFM files from your TrueType fonts? This won't be done automatically via mktextfm or MakeTeXTFM! 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 ttf2pk's 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 (not necessary for teTeX 1.0 resp. teTeX 0.9 beta versions 1999-04-29 or newer)? If you want Thai support, have you followed the instructions given in thaifont.doc? 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 used the options --with-kpathsea-include=... and --with-kpathsea-lib=... while calling the configure script of hbf2gf (resp. ttf2pk)? Otherwise no file searching library is used which yields surprising results... Note: Don't use e.g. `/usr/include/kpathsea' but `/usr/include' as an argument to --with-kpathsea-include. To check whether kpathsea correctly finds HBF files and configuration files for hbf2gf, say: kpsewhich -progname=hbf2gf -format='misc fonts' .hbf kpsewhich -progname=hbf2gf -format='other text files' .cfg The same for TrueType fonts and the ttf2pk config file: kpsewhich -progname=ttf2pk .ttf kpsewhich -progname=ttf2pk -format='other text files' ttfonts.map Have you compiled the various *conv utility programs (like bg5conv)? Have you installed them together with the caller scripts (like bg5latex) in your path? FOR BIG 5 ENCODING YOU SHOULD ALWAYS USE bg5latex (except if you use cjk-enc.el). Have you updated and controlled the texmf.cnf configuration file or set the various environment variables? (TEXINPUTS, TFMFONTS, PKFONTS, MISCFONTS, TTFONTS, TTF2PKINPUTS, TTF2TFMINPUTS, HBF2GFINPUTS) ttf2pk and hbf2gf should be in the same directory where your TeX binaries like `texconfig' or `gftopk' 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 installed the various *conv utility programs (like bg5conv)? together with the caller scripts (like bg5latex.bat)? FOR BIG 5 ENCODING YOU SHOULD ALWAYS USE bg5latex.bat . Have you created and installed TFM files for fonts not in a CJK font package? Check whether you have 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. For hbf2gf, read hbf2gf.doc and its manual page (hbf2gf.1 or a formatted version of it). Similarly, more info on ttf2tfm and ttf2pk can be found in ttf2pk.doc resp. the manual pages ttf2pk.1 and ttf2tfm.1 (or a formatted version). --- end checklist ----------------------------------------------------------- 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 your (local) 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 :// to let TeX search the standard directories and your CJK tree, e.g. setenv TEXINPUTS :/home/joe_user/CJK/4_3.0/texinput// (Note the leading double colon to append a path, and the double slash to activate subdirectory searching -- 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 . Note: Most FD example files from the CJK package are set up for bitmap fonts. Thus, if you want to use TrueType fonts instead of bitmap fonts, you *must* either change the FD files or add new ones! 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-include= \ --with-kpathsea-lib= make make install for a normal compilation and installation. Replace `/usr/local/TeX' with a path to your TeX distribution, and with the directory one level higher than the library resp. the include files themselves. Example: libkpathsea.a is in /usr/local/TeX/lib/i686-linux, kpathsea.h is in /usr/local/TeX/include/kpathsea; then should be `/usr/local/TeX/TeX/lib/i686-linux', and should be `/usr/local/TeX/include' (and not `/usr/local/TeX/include/kpathsea). 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 particular 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. No changes to the script files are necessary for teTeX 1.0 (resp. teTeX 0.9 beta versions 1999-04-29 or newer -- this corresponds to web2c 7.3.1 or newer). 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 MISCFONTS and HBF2GFINPUTS in the texmf.cnf configuration file. Otherwise, you must set or modify the MISCFONTS/HBF2GFINPUTS environment variables to reflect the new locations of the bitmap/hbf files. Please consult hbf2gf.1 resp. hbf2gf.doc for kpathsea versions < 3.3 which uses other environment variable names. 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). Really free Chinese TrueType fonts (for both simplified and traditiional Chinese) with a license similar to the GPL can be found on ftp://ftp.gnu.org/gnu/nongnu and its mirrors worldwide. 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 lacks these features, but ttf2pt1 has). The ttf2pk package (found in the contrib/ttf2pk directory of ftp://ftp.freetype.org/ pub/freetype/unstable/freetype1-contrib-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. For compilation you also need the FreeType 1 package: ftp://ftp.freetype.org/ pub/freetype/unstable/freetype-current.tar.gz 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 Unfortunately, web2c is not always able to resolve such an entry properly. In case your font is installed into a completely unrelated directory, you must add all subfonts to `special.map', e.g. gsfs1401 gb2312 gsfs14 gsfs1402 gs2312 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 cc -O -s -o extconv extconv.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/XEmacs 21 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 -- note that the Mule version has limited capabilities compared to the Emacs 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 in CJK.doc 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/share/emacs/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 . o For Thai support please follow the instructions given in `thaifont.doc'. DOS and OS/2 (emTeX) -------------------- Note that web2c has been ported to MS-DOS. If you use this (which I recommend), follow the instructions above. 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 Compile hbf2gf. You need GNU make and either the emx (DOS and OS/2) or the djgpp (DOS and Windows) compiler. Say `make -f Makefile.gnu' to see the possible options; more info can be found in hbf2gf.doc . o Compile the utility programs. 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 cc -O -s -o extconv extconv.c 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 . Note: Currently, almost all FD example files from the CJK package are set up for bitmap fonts. Thus, if you want to use TrueType fonts instead of bitmap fonts, you *must* either change the FD files or add new ones! 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=;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:{,$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). Really free Chinese TrueType fonts (for both simplified and traditiional Chinese) with a license similar to the GPL can be found on ftp://ftp.gnu.org/gnu/nongnu and its mirrors worldwide. The ttf2pk package can be found in ftp://ftp.freetype.org/ pub/freetype/unstable/freetype1-contrib-current.tar.gz It 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. For compilation you also need the FreeType 1 package: ftp://ftp.freetype.org/ pub/freetype/unstable/freetype-current.tar.gz 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 is 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:{,$texmfdir:fonts\{modeless,cx}}\@Rrdpi\@f.pk +virtual-fonts:{,$texmfdir:fonts}\@f.vf o For Thai support please follow the instructions given in `thaifont.doc'. Other systems ------------- Recent versions of CJK have only been tested with web2c; 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 (USA). o Mule 2.3 can be found at ftp.m17n.org (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.7 or newer resp. XEmacs 21.1 or newer which is available from ftp.gnu.org (USA) resp. ftp.xemacs.org and its many mirrors.] ---End of INSTALL---