diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/CJK/doc/CJK.txt')
-rw-r--r-- | Master/texmf-dist/doc/latex/CJK/doc/CJK.txt | 1149 |
1 files changed, 1149 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/CJK/doc/CJK.txt b/Master/texmf-dist/doc/latex/CJK/doc/CJK.txt new file mode 100644 index 00000000000..d0fa784ca84 --- /dev/null +++ b/Master/texmf-dist/doc/latex/CJK/doc/CJK.txt @@ -0,0 +1,1149 @@ + +This is the LaTeX2e style package CJK Version 4.6.0 (11-Aug-2005) +================================================================= + +It is freely distributable under the GNU Public License. + + + ************************************************** + * * + * You need LaTeX 2e version 2001/06/01 or newer! * + * * + ************************************************** + + +Usage +----- + +Use CJK.sty as a package, e.g., + + \documentclass{article} + \usepackage[<option>]{CJK} . + +See section `Caveats' below for the available options. Normally, you don't +need them. + +Two new environments, + + \begin{CJK}[<fontencoding>]{<encoding>}{<family>} + ... + \end{CJK} + +and + + \begin{CJK*}[<fontencoding>]{<encoding>}{<family>} + ... + \end{CJK*} + +are defined. The parameters have the following meaning: + + <encoding> These character sets and encodings are currently + implemented in CJK.enc: + + Bg5 (For traditional Chinese. Mainly used in Taiwan. + Character set: Big 5. + Encoding: Big 5.) + Bg5+ (For Chinese. An extension of Big 5. Obsolete. + Character set: Big 5+. + Encoding: Big 5+.) + + GB (For simplified Chinese. Mainly used in + PR China. Also called `EUC-CN'. + Character set: GB 2312-1980. + Encoding: EUC.) + GBt (For traditional Chinese. Rarely used in + PR China. + Character set: GB/T 12345-1990. + Encoding: EUC.) + GBK (For Chinese. An extension of GB 2312. + Character set: GBK. + Encoding: GBK.) + + JIS (For Japanese. + Character set: JIS X 0208:1997. + Encoding: EUC.) + JIS2 (Japanese supplementary character set, + Character set: JIS X 0212-1990. + Encoding: EUC.) + SJIS (For Japanese. Used mainly on PCs. Also known + as `MS Kanji'. + Character sets: + 1-byte characters from JIS X 0201-1997 + (half-width katakana), + 2-byte characters from JIS X 0208:1997. + Encoding: SJIS.) + + KS (For Korean. Also called `EUC-KR'. + Character set: KS X 1001:1992 = KS C 5601-1992. + Encoding: EUC.) + + UTF8 (Unicode Transformation format 8, also called + `UTF-2' or `FSS-UTF'. + Character set: Unicode. + Encoding: UTF-8.) + + CNS1 (Chinese National Standard Plane 1, + Character set: CNS 11643-1992 plane 1. + Encoding: EUC.) + CNS2 + ... + CNS7 (Character set: CNS 11643-1992 plane 2 - 7. + Encoding: EUC.) + + CEFX (reserved CEF character set for IRIZ. + Encoding: EUC.) + CEFY (private CEF character set. + Encoding: EUC.) + + These encodings (except Big 5, Big 5+, GBK, SJIS, and + UTF-8) are simplified EUC (Extended Unix Code) character + sets without single shifts. The used character set slot + G1 stands for two-byte encodings with byte values taken + from the GR (Graphic Right) character range 0xA1-0xFE + (as defined in ISO 2022). + + Note that CNS1 and CNS2 contain almost the same + characters in the same order as Big 5 (but in EUC). + + For CEF and CNS character sets see CEF.txt also. + + Big 5+ and GBK have exactly the same encoding layout + (but their origins differ). + + Additionally, the following encodings *with* single + shifts are implemented, using some of the above defined + character sets: + + EUC-JP (for Japanese. + Character sets: + Half-width katakana (from JIS X 0201-1997), + JIS X 0208:1997, + JIS X 0212-1992.) + + EUC-TW (for traditional Chinese. + Character sets: + CNS 11643-1992 planes 1-7.) + + EUC-JP, EUC-TW, and UTF-8 encodings can't be used in + preprocessed mode (see below) because it makes no sense. + + + If you use this parameter it is the same as you would + have used \CJKenc: Writing e.g., + + \begin{CJK}{Bg5}{...} + ... + + is identical to + + \begin{CJK}{}{...} + \CJKenc{Bg5} + ... + + Note: A `character set' is an ordered collection of + glyphs. The order of the glyphs is just for + defining purposes and for reference. + + An `encoding' is an ordering scheme to access a + character set. LaTeX 2e also uses the term `input + encoding'. + + A character set can have many encodings + (cf. JIS X 0208 -> EUC, SJIS). + + An encoding can be used for many character sets + (cf. EUC -> KS X 1001, GB 2312, etc.). + + Sometimes, the character set has the same name + as the encoding (Big 5, Big 5+, GBK). + + For more details I suggest to read the document + cjk.inf from Ken Lunde; it is available from + + ftp://ftp.ora.com/pub/examples/cjkvinfo/ + doc/cjk.inf + + A really thorough reference is his latest book + `CJKV Information Processing' (O'Reilly). + + Throughout this CJK documentation, `encoding' + refers to the valid encoding/character set + combinations defined just above. + + <fontencoding> These font encodings are currently defined: `' (empty; + the default), `pmC' (available for Bg5, GB, GBt, JIS, + and KS), `dnp' (for JIS and SJIS), `wn' (for JIS), and + `HL' (for KS). + + `Font encoding' means the order of characters in the + subfonts itselves. A change of the font encoding neither + alters the meaning of a CJK character nor changes the + character code in the selected encoding. + + The font encoding `pmC' is defined for compatibility + with the pmC package (which is obsolete). It is not + encouraged to use this font encoding because of wasting + subfonts. If possible, convert your original CJK bitmap + fonts with hbf2gf (see hbf2gf.txt) or other tools to CJK + encodings. + + `dnp' implements the character order of the Dai Nippon + Printing fonts and is only available for JIS and SJIS + encoding. `wn' (only available for JIS) is the font + encoding for watanabe jfonts. There exists a linking + package which maps the watanabe jfonts onto the dnp + naming scheme (thus you can use the real dnp fonts for + printing and the mapped jfonts for previewing). See the + documentation files in the `japanese' subdirectory for + further details. + + `HL' allows the use of the new HLaTeX fonts (starting + with version 1.0); note that the definition of fonts is + rather different compared to HLaTeX. See the section + `Korean input' below for a detailed description. + + You can change the font encoding per encoding with the + command \CJKfontenc; the first parameter is the + encoding, the second the font encoding. + + <family> It is impossible to know in advance what fonts are + available at your site; look at the example FD (font + definition) files how to create or modify appropriate FD + files suiting your needs. See fonts.txt also for further + hints. + + If this parameter is empty, the default value given in + CJK.enc is selected: `song' for all encodings except KS + (which defaults to `mj'). If you use this parameter it + is the same as you would have used \CJKfamily; all + encodings then use this family: + + \begin{CJK}{...}{song} + ... + + is identical to + + \begin{CJK}{...}{} + \CJKfamily{song} + ... + + You can change the families per encoding (and font + encoding) with the command \CJKencfamily; the first + parameter is the encoding, the second the family, the + optional argument is the font encoding. This overrides + the default value. + + Note that \CJKfamily or a non-empty `family' parameter + of the CJK environment overrides any \CJKencfamily + commands. Say `\CJKfamily{}' to enable \CJKencfamily + again. + + + The CJK* environment swallows unprotected spaces and newlines after a + CJK character (the usual habit for Chinese and Japanese text), whereas + CJK does not (for European and Korean text). You can switch between + these two `modes' with \CJKspace (CJK* -> CJK) and \CJKnospace (CJK -> + CJK*). + + If you use cjk-enc.el, you don't need to specify a CJK environment. This + is done automatically. See cjk-enc.txt for details. + + +This is a typical example: + + \begin{CJK*}{GB}{kai} + ... + Chinese simplified text in GB encoding + ... + \end{CJK*} + + +How it works +------------ + +Asian logographs can't be represented completely with one byte per +character. (At least) two bytes are needed, and the most common encoding +schemes (UTF-8, GB, Big 5, JIS, KS, etc.) have a certain range for the first +byte (usually 0xA1-0xFE or a part of it) which signals that this and the +next byte represent an Asian logograph. This means almost all plain ASCII +characters (characters between 0x00 and 0x7E) are left undisturbed, and the +remaining character codes (0x80-0xFF) are assigned to a CJK encoding, +creating a multiple-byte encoding with 1-byte and 2-byte characters (and +even 3-byte characters for UTF-8). + +The character 0x7F is reserved also for the CJK package. See the section +`Preprocessors' below. + +Encodings like EUC-TW access additional character sets using escape +characters (0x8E and 0x8F) which signals that the next character comes +from another character set (which is `shifted' to the GR range); up to +four bytes are needed for a single character. Example: + + 0x8E 0xA3 0xB7 0xCE + + 0x8E is a single shift escape character; 0xA3 selects CNS plane 3, and + 0xB7CE is the character code (in GR representation) in this plane. + +CJK.sty makes the character codes 0x7F and 0x81-0xFE active inside of the +CJK environment and assigns macros to the active characters which then +select the proper font and character. The real mechanism is a bit more +complex to assure robustness (it was borrowed and modified from LaTeX 2e's +inputenc.sty) and correct handling of punctuation characters. + +* emTeX users: you must activate 8bit input and output while creating the +* LaTeX2e format file! Do this by using the switches -o and -8 (additional +* to the iniTeX switch -i). +* +* Example: +* +* tex386 -i -o -8 latex.ltx + + +Some internals +-------------- + +Internally three levels (bindings, encodings, character macro sets) are +defined: + + active characters + | + +--------------> bindings (standard, SJIS, UTF8) + | + active character macros + | + +--------------> encodings (GB, Big 5, ...) + + | font encodings (none, dnp, wn, pmC, HL) + | + subfont selecting macros + | + +--------------> character macro sets (standard, Big 5, ...) + | + character selecting macros + +User-selectable are only the encoding and the font encoding (as explained +above); the other levels are selected by the CJK package. + +These levels correspond to the following internal macros: + + \CJK@xxxxBinding (`xxxx.bdg' files): + Possible values for `xxxx' are: standard, SJIS, UTF8, EUC-JP, and + EUC-TW. + + \CJK@xxxxEncoding (`xxxx.enc' files): + Possible values for `xxxx' are: standard, extended, Bg5, SJIS, KS, UTF8, + pmCsmall, pmCbig, JISdnp, SJISdnp, KSHL, EUC-JP, and EUC-TW. + + \CJK@xxxxChr (`xxxx.chr' files): + Possible values for `xxxx' are: standard, Bg5, KS, SJIS, UTF8, pmC, + HLaTeX, EUC-JP, and EUC-TW. + +In preprocessed mode (see below), no bindings are used. + + +And now a more detailed description of the various encodings. Please note +that you should never access these macros directly. + + \CJK@standardEncoding is used for EUC encodings with the first and second + byte in the range 0xA1-0xFE (GB, GBt, JIS, JIS2, CNS, CEF). + + \CJK@extendedEncoding is used for Big 5+ and GBK encodings. The first byte + is in the range 0x81-0xFE, the second byte in the range 0x40-0xFE (with a + gap at 0x7F). + + \CJK@Bg5Encoding is used for Big 5 encoding with the first byte in the + range 0xA1-0xFE and the second byte in the range 0x40-0xFE (with a gap + from 0x7F-0xA0). + + \CJK@SJISEncoding is used for SJIS encoding; one-byte characters are in + the range 0xA1-0xDF, two-byte characters have the first byte in the ranges + 0x81-0x9F and 0xE0-0xEF, the second byte runs from 0x40 to 0xFC except + 0x7F. Since SJIS only squeezes the JIS X 0208 character set into a new + scheme without changing the ordering, fonts produced by hbf2gf or ttf2pk + look the same for EUC and SJIS encoding except one-byte SJIS characters. + For more details see below the section `SJIS encoding'. + + \CJK@KSEncoding is used for the KS X 1001 character set in EUC encoding. + Two sets of subfonts are defined, one for Hangul syllables and elements, + and a second for Hanja. For more details see below the section `Korean + input'. + + \CJK@UTF8Encoding is used for Unicode in UTF-8 encoding. The first byte is + in the range 0xC0-0xDF for two-byte values, and in the range 0xE0-0xEF for + three-byte values. The other byte(s) are in the range 0x80-0xBF. Note that + CJK expects two hexadecimal digits as a running number in the font name + (as defined in UTF8.enc) instead of two decimal digits. Select the option + `unicode yes' in the hbf2gf config file if you use hbf2gf to transform + bitmap fonts in HBF format to PK fonts as used by CJK.sty . Three commands + (\CJKCJKchar, \CJKhangulchar, and \CJKlatinchar) control the handling of + intercharacter glue: \CJKCJKchar (the default) selects CJK style (using + \CJKglue), \CJKhangulchar selects hangul style (using \CJKtolerance), and + \CJKlatinchar selects none of them. This encoding does not work in + preprocessed mode. + + \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); Bg5pmC encoded fonts cannot contain + big characters. The names of the fonts in the FD files reflect the + modifications added by Marc Leisher <mleisher@nmsu.edu> to the original + poor man's Chinese (pmC) package written by Thomas Ridgeway + <ridgeway@blackbox.hacc.washington.edu>. + + \CJK@JISdnpEncoding is the JIS X 0208 character set in EUC encoding with + dnp fonts. The main difference (besides the offsets) is the composition of + real font names; a dnp font name consists of name stem + subfont name + + designsize: an example is dmjkata10. Note that the wadalab PS fonts omit + the designsize part in the font names, thus it is sufficient (and even + better) to use the `CJK' size functions in FD files instead of the `DNP' + ones. \CJK@JISwnEncoding is similar to JISdnp encoding but uses Watanabe + jfonts; \CJK@SJISdnpEncoding maps SJIS onto dnp encoded fonts. + + \CJK@KSHLEncoding finally uses the new fonts of the HLaTeX package for + Korean; three internal encodings are necessary to represent it. See the + next section for details. + + \CJK@EUC-TWEncoding and \CJK@EUC-JPEncoding are quite similar to + \CJK@standardEncoding but implement single shift access additionally. They + can't be used in preprocessed mode. + + +Korean input +------------ + +There is already a package which handles Hangul and Hanja (but no other +CJK character sets): HLaTeX. + +To use KS encoding, say + + \begin{CJK}{KS}{} + ... + \end{CJK} . + +These font switches are available inside the environment: + + hangul fonts from former hlatex (in the han font packages): + + * \mj MyoungJo (default) + \gt Gothic + \gs BootGulssi + \gr Graphic + \dr Dinaru + + hangul fonts from former jhtex (in the han1 font packages): + + * \hgt Hangul Gothic + * \hmj Hangul MyoungJo (MunHwaBu fonts) + * \hpg Hangul Pilgi + \hol Hangul Outline (MyoungJo) + + +If a font is marked with a star, real bold series are available. All other +bold fonts are defined using poor-man's boldface (see below the section +`Poor man's Boldface'). + +See the file INSTALL how to get these fonts. Both `han' and `han1' packages +contain bitmap fonts only (in PK format). + +Note that the font switches are abbreviations for \CJKencfamily and not for +\CJKfamily. + + +For characters with the first byte in the ranges 0xA1-0xAF (except 0xA4) and +0xC9-0xFD (graphic characters, hanja, archaic hangul, etc.) fonts with the +encoding C60 are used. C61 is assigned to hangul fonts (for hangul elements +with the first byte 0xA4 and hangul characters in the range 0xB0-0xC8). This +enables the use of many hangul fonts and perhaps only one or two different +hanja fonts. If you want to use C60 encoding for hangul characters also say +\CJKhanja. The opposite command is \CJKhangul (of course this works only if +you have hangul characters in the C60 font). + +Archaic hangul elements (KS X 1001 0xA4D5-0xA4FE) and the character +KS X 1001 0xA4D4 are only accessible if \CJKhanja is active. + +You should convert your KS X 1001 hanja fonts using hbf2gf (or ttf2pk) as +described above. + + +To use HLaTeX fonts, say + + \begin{CJK}[HL]{KS}{} + ... + \end{CJK} . + +All HLaTeX fonts are PS fonts; these font switches are available inside the +environment (as defined in HLaTeX 1.0; this differs from older versions): + + \bm Bom + * \dn Dinaru + * \gr Graphic + + \gs Gungseo + + * \gt Gothic + \jgt Jamo Gothic + \jmj Jamo Myoungjo + \jnv Jamo Novel + \jsr Jamo Sora + + * \mj Myoungjo + * \pg Pilgi + \pga Pilgia + \ph Pen Heulim + \pn Pen + + \sh Shinmun Myoungjo + + \tz Typewriter + \vd Vada + \yt Yetgul + +If a font is marked with an asterisk, real bold series are available. All +other fonts are defined using poor-man's boldface (see below). Only fonts +marked with a plus sign are available for hanja too; the other font families +are mapped to these six hanja families. For backwards compatibility, \ol and +\sm are defined also; both are now equivalent to \mj. + +UN Koaung-Hi <koaunghi@kornet.net>, the author of HLaTeX, defines three +groups of fonts: hangul, hanja, and symbols. The CJK package needs three +internal encodings (C63 for hanja, C64 for symbols, and C65 for hangul) to +represent the font encoding scheme of HLaTeX. + +HLaTeX options: + +The option `hardbold' has been integrated into the FD files---I consider the +fact whether you have bold series available or not as a fundamental local +font setup decision which should be coded into the FD files and not into the +document. As a consequence you have to change your FD files to emulate the +`softbold' option with CJK's poor-man's boldface. Example: + + \DeclareFontShape{C63}{gt}{bx}{n}{<-> CJK * wgtb}{} + +should be changed to + + \DeclareFontShape{C63}{gt}{bx}{n}{<-> CJKb * wgt}{\CJKbold} . + +and similar font definitions too. + +[Well, it is not really necessary to modify the FD files to emulate the + `softbold' option: just insert the appropriate \DeclareFontShape and/or + \DeclareFontFamily commands in the preamble of your document.] + +Finally a warning: Please bear in mind that CJK does not emulate the +behaviour of HLaTeX, it only supports its fonts. + + +Big 5 encoding +-------------- + +See below the section `Preprocessors' for the preferred input method using +bg5conv. + +The characters `\', `{', and `}' are used as second bytes in the Big 5 +encoding. This collides with TeX. If you write Big 5 text mixed with other +encodings (and you don't want/can't use Mule, Emacs or bg5conv), 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. + +This environment is ugly, and some commands like \newcommand don't work in +it. Starting with CJK version 3.0 it is also possible to use different +encodings in preprocessed mode, thus this environment is almost obsolete. + +Instead of using the Bg5text environment you can protect the offending +second bytes with a backslash, i.e., `\{', `\}', `\\' (using a non-Chinese +editor). This doesn't increase the readability of the Chinese text, but for +short texts it is perhaps more comfortable. Alas, it doesn't work in page +header commands because the macros `\{', etc., are not expanded. + +Be careful not to use any commands inside the Bg5text environment which +write something into an external file (commands like \chapter, etc.). + +If it is not possible to avoid Big 5 character codes with `\', `{', or `}' +outside of the Bg5text environment (e.g., having Big 5 text in a \chapter or +\section command), you can replace them with the \CJKchar macro manually: + + \section{This is a problematic Big 5 character: \CJKchar{169}{92}} + +The parameters are the first and second byte of the Big 5 character code. +You can also use hexadecimal or octal notation. See commands.txt for a full +description of \CJKchar. + + +SJIS encoding +------------- + +See below the section `Preprocessors' for the preferred input method using +sjisconv. + +Shift-JIS encoding is widely used on PCs for Japanese. A special feature is +the simultaneous use of one-byte and two-byte encoded characters which arose +because of backwards compatibility. The two-byte encoded character set is +completely identical to the JIS X 0208 character set, even the ordering is +the same. Thus there is no need for special two-byte SJIS FD files; the font +definition files for JIS X 0208 are used. + +The situation is different for one-byte SJIS characters, the so called +`half-width' Katakana (encoding C49) from JIS X 0201. Usually you should use +full-width Katakana fonts too to get a typographically correct output. The +exception is a typewriter font which should really have only the half width +of normal Kanji or Katakana to represent screen snapshots or similar things. +The use of C49 encoding can be controlled with the \CJKhwkatakana and +\CJKnohwkatakana macros (see commands.txt for more information). + +Fonts in C49 encoding scheme must have the character glyphs at the code +points 0xA1-0xDF. + +An environment `SJIStext' similar to `Bg5text' is defined; the same +restrictions as explained in the previous section hold. + + +Big 5+ and GBK encodings +------------------------ + +See below the section `Preprocessors' for the preferred input method using +extconv. + +These relatively new encodings are used in some older MS Windows versions in +Taiwan (Big 5+) and Mainland China (GBK). Both encodings implement the whole +CJK character repertory of Unicode in the Basic Multilingual Plane +(U+4E00-U+9FFF, approx. 21000 characters) and a few other characters but +still try to be backwards compatible. All code points of Big 5 are identical +to the code points in Big 5+, and the same holds for GB 2312-1980 and GBK. +Note that the default CJK font encodings for Big 5+ and Big 5 are *not* +compatible. The same is true for GBK and GB2312. + +Two new environments, `Bg5+text' and `GBKtext' similar to `Bg5text' are +defined also; the same restrictions as above hold. + + +CJK captions +------------ + +To use the supplied caption files you need the koma-script package. The main +reason why I choose these style files instead of the standard classes is the +fact that the author of koma-script is willing to support CJK. On the other +hand, the philosophy of the LaTeX 2e maintainers is not to add new features +to the standard classes. + +The koma-script style files are maintained by Markus Kohm +(Markus.Kohm@gmx.de); they are available at the CTAN hosts. + + +If you say \CJKcaption{<caption>} inside of a CJK environment, the file +<caption>.cpx is loaded (.cpx is a preprocessed version of .cap) + +Example: + + \documentclass{scrartcl}% this is a KOMA-script class + \usepackage{CJK} + + \begin{document} + \begin{CJK*}{GB}{kai} + \CJKcaption{GB}% loading GB.cap + + \chapter{blablabla}% is formatted in Chinese + + ... + + \end{CJK*} + \end{document} + + +Note that for Korean three caption files are available: hanja.cap for +captions using hanja (this corresponds to HLaTeX's `hanja' option) and +two caption files (hangul.cap and hangul2.cap) using hangul. + +For GBK encoding use the GB.cap file. Similarly, use Big5.cap for Big 5+ +encoding. + +In case you want to edit a CAP file, you must create its corresponding +CPX file too. After editing, preprocess the file with + + bg5conv < xxx.cap > xxx.cpx + +(for caption files in SJIS encoding use sjisconv instead), then change +the file name identification strings in the CPX file accordingly. + + +Underlining and other font effects +---------------------------------- + +Full support for Donald Arseneau's ulem.sty package (beginning with version +2000-05-26) is available by using CJKulem.sty (which loads ulem.sty +automatically). No changes to ulem's interface. + +Even more font effects specific to CJK scripts can be found in CJKfntef.sty; +usage examples can be found in the file CJKfntef.tex . + + +Poor-man's boldface +------------------- + +Most CJK fonts available in the public domain do not have bold series. To +emulate boldface by printing the character three times with slight +horizontal offsets some special features are used: + + CJK uses \CJKsymbol internally instead of \symbol to access CJK + characters (after the correct font has been selected). This macro + honours the \ifCJK@bold@ flag; if set it emulates boldface. The default + value of the horizontal offset is 0.015em; to change it you should + redefine \CJKboldshift, the macro which holds this shift. + + \ifCJK@bold@ can be set and unset globally with the commands \CJKbold + and \CJKnormal. These commands are intended to be used with + \DeclareFontShape as follows: + + \DeclareFontShape{C00}{CNS}{m}{n}{<-> CJK * csso12}{} + \DeclareFontShape{C00}{CNS}{bx}{n}{<-> CJKb * csso12}{\CJKbold} + + It should be never necessary to use \CJKnormal since \selectfont has + been modified to always reset \ifCJK@bold@ and to call the + loading-settings (i.e., the sixth parameter) of \DeclareFontShape. + + Additionally, new size functions (CJKb, sCJKb, CJKfixedb, sCJKfixedb, + and others; see fonts.txt for details) have been introduced which are + completely identical to its counterparts without the final `b'. The only + reason to use them is, as shown in the above example, to make the fifth + parameter of \DeclareFontShape for bold series different from the one + for medium series (LaTeX 2e uses this parameter as a macro name to + execute loading-settings, thus they must not be equal). + + +Embedding non-CJK words into CJK text +------------------------------------- + +To enable line breaking you should separate non-CJK words and CJK characters +with horizontal space. But the ordinary space dimensions inserted by TeX +based on the current non-CJK font often looks bad because the surrounding +CJK characters are printed almost side by side (the non-stretched value of +\CJKglue is 0pt). Especially in extreme cases which happen in underfull +\hbox commands the default space distorts the CJK text too much. + +If you say \CJKtilde, the active `~' character doesn't produce an +unbreakable space; instead, the following definition is used: + + \def~{\hspace{0.25em plus 0.125em minus 0.08em}} . + +This defines a space which has a normal width of a quarter (CJK) space. See +the file japanese/shibuaki.txt for some further details. + +Here an example: + + ThisIsChineseText~test~ThisIsChineseText + + ^^^^^^ + +Simply use tilde characters instead of spaces at the border between CJK and +non-CJK characters. + +In BibTeX entries, you have to use `{~}' instead of `~'. + +The original definition of `~' is available as \nbs (non-breakable space, a +shorthand for the LaTeX command \nobreakspace). To return to the standard +`~' macro definition say \standardtilde. + +Note that the opposite is not true: To embed CJK words into non-CJK text an +ordinary space is optimal. + +If you use Mule or Emacs 20 please consider the use of cjktilde.el in +utils/lisp. This small package defines a minor mode (cjk-tilde-mode) which +exchanges the space key with the tilde key. It is convenient to bind this +mode to a key, e.g., C-insert. + +For AUC TeX you can also use cjkspace.el which is similar (but not +identical) to cjktilde.el . + + +Preprocessors +------------- + +Using the `XXXtext' environments like `Bg5text' is a mess. Thus three +preprocessors are provided to overcome the restrictions of the XXXtext +environments: bg5conv and sjisconv Big 5 and SJIS encoding, and extconv for +GBK and Big 5+ encoding characters. Compile them with + + cc -O -s -o bg5conv bg5conv.c + cc -O -s -o sjisconv sjisconv.c + cc -O -s -o extconv extconv.c + +and move the binaries to a location in your path, e.g., /usr/local/bin in +a Unix system. [`cc' is the C compiler.] + +See the batch files bg5latex[.bat], etc., for examples how to use them. + +Each Big 5, Big 5+, or GBK character (and each two-byte encoded SJIS +character) `XY' is converted into the form `^^7fX^^7fZZZ^^7f'; ZZZ is the +decimal equivalent of Y, and ^^7f is a character with the hex value 0x7F. +The use of bg5conv/sjisconv/extconv is completely transparent; no changes to +your documents are necessary. + +It is possible to mix preprocessed and non-preprocessed data; simply use +\CJKenc to change the encoding; you can use \CJKinput and \CJKinclude to +load preprocessed data (see commands.txt for a detailed description). + +If you use traditional Chinese characters within Mule or Emacs 20, it is not +necessary to call bg5conv after the use of *cjk-coding* output encoding (but +it is necessary if you write out the file in Big 5 encoding). + +Note 1: The OS/2 script files bg5latex.cmd, etc., need REXX which you + probably have to install first. + +Note 2: With extconv, you can also preprocess encodings like GB or SJIS. + This has the advantage that such data is robust against any changes + of the uc/lccodes in the range 0xA1-0xFE. Only three encodings can't + be preprocessed: UTF8, EUC-TW, and EUC-JP. + + +Customization +------------- + +In case you want to add encodings, font encodings, and related things, or if +you must change or customize some CJK settings, you should use a +configuration file called `CJK.cfg' which is loaded (if it exists) by +CJK.sty just before the final \endinput command. + + +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' + of TeX (with emTeX you can adjust this with -ms=...; web2c users + can control it with the `save_size' parameter in texmf.cnf). + + The CJK package has optional arguments which control the scope of + CJK environments: + + lowercase If you want to use \lowercase with encodings + inside CJK environments. You need less save size + using the `encapsulated' option if `lowercase' + is not set. You must use bg5conv (sjisconv) or + cjk-enc.el to use Big 5 (SJIS) characters with + this option. + + Use this with caution! All \lccode values in the + range 0x80-0xFF are set to zero, thus disabling + TeX's hyphenation mechanism for words which + contain characters of this range in the *input + encoding* (e.g., Latin-1 encoded words with + accents). This is due to an unfortunate mangling + of the input and output encoding mechanism in + TeX itself. + + global \lccode (if `lowercase' set), \uccode, \catcode + and the activation of the characters 0x81-0xFE + are 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 0x81-0xFE. + + All CJK font selection commands are globally too! + + Packages which change some of the above values + only once (e.g., in the preamble) also don't + work after the first use of a CJK environment. + + cjk-enc.el automatically selects this option. + + local \lccode (if `lowercase' set) and \uccode + together with bindings are modified globally. + This is the default. You can stack CJK + environments. + + active If activated, bindings are local additionally. + You need this option if you want to mix + preprocessed text with non-preprocessed text in + nested CJK environments. This can happen if you + merge texts in various encodings. + + encapsulated If you want to access e.g., T1 fonts directly + (i.e., without the macros defined in t1enc.def) + or if you want to use a non-CJK LaTeX 2e input + encoding outside of the CJK environment (e.g., + `latin1' for Western European, `latin2' for + Eastern European), you must use this option. + This also ensures that \uppercase and \lowercase + (together with \MakeUppercase and + \MakeLowercase) work correctly. All values + mentioned above are local, so you can stack + environments. This option probably causes an + overflow of the save size. + + Note: All macro packages which access T1 fonts + with the macros defined in t1enc.def work in CJK + environments! E.g., the command `"s' of + german.sty works with \MakeUppercase too. + + + Say + + \usepackage[<option>]{CJK} + + to activate <option>. + + o There is another way to overcome the problem of stacked + environments. CJK implements four CJK attribute switches: \CJKenc, + \CJKfontenc, \CJKencfamily, and \CJKfamily; see commands.txt for a + detailed description. If you need two different encodings/families + at the same output line, you must use these macros. + + An example for \CJKfamily: + + \begin{CJK}{GB}{song} + ... Text in GB song ... \CJKenc{GBt} + ... Text in GBt song ... \CJKfamily{kai} + ... Text in GBt kai ... + \end{CJK} + + An example for \CJKencfamily: + + \CJKencfamily{Bg5}{fs}% fangsong + \CJKencfamily{GB}{kai} + + \begin{CJK*}{}{} + \CJKenc{Bg5} ... Text in Big 5 fangsong ... + \CJKenc{GB} ... Text in GB kai ... + \end{CJK*} + + Contrary to \begin{CJK}{...}{...} it is not necessary to start a new + line in your TeX document file after \CJKenc. + + o A similar command to \CJKchar is \Unicode{<byte1>}{<byte2>} to + access Unicode characters (real Unicode values, not UTF-8 encoded + Unicode) directly; the parameters are the first (high) and second + (low) byte of the Unicode. \Unicode works only in UTF-8 encoding; in + all other encodings you must use \CJKchar[UTF8]{<byte1>}{<byte2>} + instead. + + o CJK disables \MakeUppercase (preserving the command as + \CJKuppercase) if you select Big 5 or SJIS encoding without using + bg5conv or sjisconv. This usually affects the headers of the LaTeX + 2e standard classes only. + + o Because CJK.sty and MULEenc.sty insert glue between CJK (and Thai) + characters, it is possible to get unwanted line breaks in verbatim + environments if lines are too long. To avoid this, use the command + \CJKverbatim in combination with the `verbatim' package. It installs + a hook which disables \CJKglue and \Thaiglue 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 To suppress a line break before a CJK character, say \CJKkern. This + command prevents the insertion of \CJKglue before the CJK character. + + You may wonder about the strange name: a small kern (2 sp) between + two CJK characters signals that the first one is a punctuation + character. + + o If you get the error message: `\CJK... undefined' or other `... + undefined ...' messages and you can't find an error, try inserting + \newpage, \clearpage, or \cleardoublepage (the latter for two-column + printing) before saying \end{CJK} or \end{CJK*}. This can happen if + LaTeX 2e writes the headers (or footers) of a page containing CJK + characters after closing the CJK environment. + + In case of footnotes with CJK characters which are split across + pages, you have to close the CJK environment on the page on which + the particular footnote ends (probably preceded by a \newpage + command). + + o If you get overfull \hbox'es caused by CJK characters, try to + increase \CJKglue. It defines the glue between CJK characters; the + default definition is + + \newcommand{\CJKglue}{\hskip 0pt plus 0.08\baselineskip} . + + \CJKglue is inserted by CJK.sty between CJK characters (except + punctuation characters as defined in the punctuation tables; see + CJK.enc for the lists). You should separate non-CJK text from CJK + characters with spaces to enable hyphenation, or you write + \CJKtilde and then use `~' instead of spaces to embed non-CJK text + into CJK characters. + + o If you get overfull \hbox'es caused by Hangul syllables, try to + increase \CJKtolerance. The default definition is + + \newcommand{\CJKtolerance}{400} . + + Alternatively, try to increase \emergencystretch (which is a TeX + primitive), setting it to a reasonable value. + + o It is not possible to start a new encoding inside of a verbatim + environment which has not been loaded before (CJK.sty emits an + \input ... command which causes the encoding file to be printed + verbatim instead of being executed). In this case, write a proper + \CJKenc{...} command before opening the verbatim environment. + + Example: + + \CJKenc{JIS} % this loads standard.enc and standard.chr + + \begin{verbatim} + ... + first time JIS characters appear + ... + \end{verbatim} + + + cjk-enc.el does this automatically for you. + + o If you get an error message which looks like this: + + + ! Undefined control sequence. + try@size@range ...extract@rangefontinfo font@info + <-*>@nil <@nnil + + + then you are using an unknown family for a CJK encoding. + + Reason: If you declare an NFSS font encoding in the standard way the + corresponding FD file for the default font is loaded. For the CJK + package this would be almost 30 files which is inacceptable. To + avoid this overhead NFSS is faked with some rudimentary definitions + just enough to pass the NFSS tests. Of course this has a + disadvantage: An unknown CJK family causes the above error instead + of switching to the fallback family usually defined with + \DeclareFontSubstitution. Nevertheless, replacing an undefined + series or shape works correctly. + + The CJK package's default family value is `song' for all encodings + except KS; to avoid the error just described in cases you start an + environment with an empty family parameter XXXsong.fd files for all + encodings (except for KS) are provided. + + o It is neither possible to use a CJK character in a \cite command of + standard LaTeX, nor is it possible to use the `alpha' citation + style. This is a limitation of LaTeX and not of the CJK package. + + o Sometimes it is necessary to define or redefine a command or + environment globally in the preamble, using CJK characters. Example: + + \newtheorem{Them}{some Chinese characters}[section] + + This won't work directly because of the Chinese characters, + producing an error. The next idea is to use a CJK environment in the + preamble: + + \begin{CJK}{...}{...} + \newtheorem{Them}{some Chinese characters}}[section] + \end{CJK} + + Don't be surprised that this also fails! Most commands like + \newtheorem expand to \def which define a macro locally only; + consequently, the just defined command is undefined again after + leaving the CJK environment. + + The correct solution is to use a globally defined macro: + + \begin{CJK}{...}{...} + \gdef\ChineseTheorem{some Chinese characters} + \end{CJK} + + \newtheorem{Them}{\ChineseTheorem}[section] + + o The \makelabels command of letter.sty needs special treatment if you + have an address with CJK characters because it uses the + \AtEndDocument hook to write out its data. Since \AtEndDocument is + called by \end{document} after all environments have been closed + already, a CJK environment must be explicitly inserted into the AUX + file. Example: + + \documentclass{letter} + + \usepackage{CJK} + + \makeatletter + \AtBeginDocument{% + \if@filesw + \immediate\write\@mainaux{\string\begin{CJK*}{...}{...}}% + \fi} + \makelabels + \AtEndDocument{% + \if@filesw + \immediate\write\@mainaux{\string\end{CJK*}}% + \fi} + \makeatother + + + \begin{CJK*}{...}{...} + \address{An address\\ + with some CJK characters} + \signature{...} + \end{CJK*} + + + \begin{document} + + \begin{CJK*}{...}{...} + + \begin{letter}{Another address\\ + with some CJK characters} + \opening{...} + + Your letter text + + \closing{...} + \end{letter} + + \end{CJK*} + + \end{document} + + o A similar solution is needed if you use \bibliography and your + bibliographic database contains author names with CJK characters. + + \makeatletter + \AtBeginDocument{% + \if@filesw + \immediate\write\@mainaux{\string\begin{CJK*}{...}{...}}% + \immediate\write\@mainaux{\string\makeatletter}% + \fi} + \AtEndDocument{% + \if@filesw + \immediate\write\@mainaux{\string\end{CJK*}}% + \fi} + \makeatother + + o If you get strange error messages while using the hyperref package, + add the `CJKbookmarks' option: + + \usepackage[CJKbookmarks]{hyperref} + + +Author +------ + +Werner Lemberg <wl@gnu.org> + +Kleine Beurhausstr. 1 +D-44137 Dortmund +Germany + +Tel. +49 231 165290 + +Please report any errors or suggestions to cjk-bug@ffii.org. + + +---End of CJK.txt--- |