diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/CJK/doc/cjk-enc.txt')
| -rw-r--r-- | Master/texmf-dist/doc/latex/CJK/doc/cjk-enc.txt | 403 |
1 files changed, 403 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/CJK/doc/cjk-enc.txt b/Master/texmf-dist/doc/latex/CJK/doc/cjk-enc.txt new file mode 100644 index 00000000000..c4b24a676f9 --- /dev/null +++ b/Master/texmf-dist/doc/latex/CJK/doc/cjk-enc.txt @@ -0,0 +1,403 @@ +This is the file cjk-enc.txt of the CJK macro package ver. 4.6.0 +(11-Aug-2005). + +cjk-enc.el +---------- + +Mule, the multilingual Emacs, is one of the most powerful editors available +for Unix systems like Linux. It is capable to edit and display texts which +are, among other scripts, written in various CJK languages; as an example +you can have traditional and simplified Chinese at the same time. Mule is +distributed under the GNU Public License; it is now integrated into the +source code emacs 20. + +The CJK package enables LaTeX to do the same (with some restrictions, see +below), but the interface is different. Mule uses additional bits internally +to store the encoding of a character, whereas the CJK package needs \CJKenc +macros to select encodings. + +Now enters cjk-enc.el . This small output filter for Mule (written in Lisp) +converts text as entered in Mule into a form TeX can understand. Double-byte +encodings which can be processed by CJK are usually converted into EUC form +preceded by \CJKenc{...} macros, single-byte encodings (Latin-1, etc.) into +equivalent LaTeX 2e macros (e.g., Latin-1 character 0xC4 (umlaut A) into +\"A). Some of these macros are undefined by default in standard LaTeX 2e +because CM or EC fonts have no characters for it. Vietnamese, Cyrillic +scripts, Modern Greek, and Thai are also supported (see below). + +cjk-enc.el comes in two versions. + + . An old version for Mule 2.3 with limited capabilities since it is no + longer supported (but updated if necessary). + + . A new version with enhanced commands which works with emacs versions + >= 20.3 and xemacs versions >= 21.1 (the latter without Thai support). + +Support for emacs versions < 20.3 has been dropped. Please upgrade. In the +following, `Mule' is used for all emacs flavours. + + +Installation +------------ + +To load cjk-enc.el into Mule, put the following line into your .emacs file: + + (load-library "cjk-enc") + +this assumes that cjk-enc.el is in a directory searched by Mule. A good +place for it is the site-lisp subdirectory (e.g., +/usr/local/share/emacs/site-lisp). + +After loading, a new (output) encoding scheme is defined: `*cjk-coding*'. +[This is called `cjk-coding' under emacs 20---Please note further that the + prefix for Mule commands has changed to `C-x RET' for emacs 20 instead of + `C-x C-k'.] + +Note: `*cjk-coding*' (`cjk-coding') can't be used to save documents! It + is intended only to create the *.cjk file which is then directly + processed by LaTeX. + + +Usage (LaTeX 2e part) +--------------------- + +A sample of a multilingual document (muletest.{tex,cjk,dvi,pdf}) can be +found in the examples subdirectory (only the TEX file is in the src package +of CJK, the other files are in the doc package). + +European languages based on the Latin script: + + Simply write your documents! Characters like `u umlaut' or `c hacek' are + converted into LaTeX 2e macros. You don't need to write "u or something + else (nevertheless it's possible). It is recommended to use LaTeX 2e's + T1 font encoding scheme to have a) most of the European diacritics + available and b) correct hyphenation for accented characters. + + The lower half of JIS X 0201 is treated similarly. + + Note that the default CM fonts of LaTeX are OT1 encoded. You should + rather use the EC fonts which are based on T1 (or virtual T1 fonts + mapped onto OT1). + + For correct hyphenation you still have to change languages, thus a + system like Babel should be used additionally. + +CJK languages: + + Don't start a CJK (or CJK*) environment! cjk-enc.el does this + automatically for you at the `\begin{document}' command. It also inserts + \CJKspace and \CJKnospace commands (\CJKspace for Korean, \CJKnospace + for all other CJK scripts; but see the section `Problems' below also). + + In CJK.enc the default font family for all encodings is `song' (except + for Korean Hangul where it is `mj'). Two commands are available to + change the CJK font encoding and family in combination with cjk-enc.el + (see CJK.txt and commands.txt for a detailed description): + + \CJKencfamily[<fontencoding>]{<encoding>}{<family>} + Change family for a certain encoding (and fontencoding). + + \CJKfontenc{<encoding>}{<fontencoding>} + Change fontencoding for a certain encoding. + + The second command is primarily for users who use Japanese DNP fonts + (see the Japanese documentation subdirectory for further details) or + Korean HLaTeX fonts. + + For the upper half of JIS X 0201 encoding, the katakana range of the + SJIS encoding of the CJK package is used. + +Vietnamese: + + Vietnamese uses accented characters not contained in EC or CM fonts. To + assure proper kerning you must explicitly activate T5 font encoding + (this can't be done automatically) to access a Vietnamese font. + + The VnTeX bundle contains Vietnamese fonts and support files; it also + defines T5 encoding. It is available from http://vntex.sf.net. + (Note that the now obsolete vncmr package is no longer supported.) + +Russian and other languages using the cyrillic script: + + Cyrillic LaTeX encodings (T2A, T2B, T2C, and X2) are now supported + within the LaTeX 2e distribution (starting with version 1998/12/01). + Cyrillic fonts and auxiliary files supporting these encodings are + available at CTAN from fonts/cyrillic and macros/latex/contrib/t2); most + TeX distributions already come with Cyrillic fonts installed. + + The current implemention needs a lot of temporary disk space for + Cyrillic scripts (e.g., a 100 kByte document written only with Cyrillic + letters has an intermediate output file of about 800 kByte). On the + other hand, it is still possible to recognize the Cyrillic characters + name macros in the log file in case of error messages---if I used the + shortest possible representation, only numbers would be visible, and the + size of the intermediate output file would still have 500 kByte... + + You must explicitly activate one of the T2* (or X2) encodings for + Cyrillic. Russian needs T2A. + +Greek: + + You must use the LGR encoding and fonts as defined in the Babel package: + ISO-8859-7 characters are mapped back to ASCII characters which are then + displayed as Greek characters, using the ligature mechanism extensively. + +Thai: + + It is implemented only in the emacs 20.3 version of cjk-enc.el. Instead + of using an external program, Ken'ichi Handa has written thai-word.el + which implements the word-breaking algorithm in Lisp, based on the the + C-TTeX package version 1.15 written by Vuthichai Ampornaramveth + <vuthi@ctrl.titech.ac.jp>. `thai.sty' is still very rudimentary---any + improvements are welcome. + + The used encoding is C90 (this is the only case where you have to + specify a `C' encoding directly, either by using the `thaicjk' language + for Babel or by saying `\DeclareFontEncoding{C90}{}{}' in the preamble); + the default fonts specified in c90gar.fd and c90nrsr.fd are taken from + the thailatex package, which can be found at + + http://linux.thai.net/plone/TLWG/thailatex + + You should use version 0.3.5.1 or newer. Note that this package is not + compatible with CJK; neither its metric files nor its LaTeX support + files should be used. Please read the file thaifont.txt for details how + to install the fonts. + + Whitespace between Thai characters are always respected; newlines + together with trailing and leading whitespace are not by default. Use + \Thaispace to make trailing and leading whitespace respected also (the + opposite command is \Thainospace). Note that the space width of the Thai + font (which is usually larger than for a Roman font) is used for + whitespace between Thai words: + + Thai Thai + Thai + + is approximately translated to + + {\thaifont Thai Thai\nospaces + Thai} + + (if \Thainospace is active), whereas + + Thai\ Thai\ + Thai + + is approximately translated to + + {\thaifont Thai}{\romanfont\ }{\thaifont Thai}{\romanfont\ } + {\thaifont Thai} + + To improve appearance, \Thaiglue (which is defined in MULEenc.sty) is + used as intercharacter glue; this value can be modified similarly to + \CJKglue. + + +Usage (Mule part) +----------------- + +Simply load your document into Mule and call cjk-write-file (which is +defined in cjk-enc.el) to create a preprocessed file. For most files this +file's name is formed by replacing the extension with `.cjk'. However, +BibTeX files are given the extension `-cjk.bib' because the BibTeX program +requires `.bib' as the extension. This also avoids conflicts with the CJK +file produced by a LaTeX file by the same name. Because of this you should +use the command \CJKbibliography{foo} in your LaTeX source file (which +finally expands to foo-cjk.bib). A similar macro is \CJKinclude{bar} which +expands to `bar.cjk' instead of bar.tex. Finally, you can say +\CJKinput{foo.bar} to input file `foo.bar'; if the file name has no +extension, `cjk' is appended: \CJKinput{foo} loads `foo.cjk'. + +cjk-write-file is the only user function provided by cjk-enc.el for +Mule 2.3. + +If you want to process a file which includes some other files, use the +function cjk-write-all-files in combination with \CJKinclude, \CJKinput, and +\CJKbibliography. If used interactively, you have to supply a file name +which is then scanned for occurrences of \CJKinclude, \CJKinput, and +\CJKbibliography; all files found plus the master file are converted. + +Example: + + `a.tex' contains: + + \CJKenc{Bg5} + Chinese text + + `b.tex' contains: + + \CJKenc{JIS} + Japanese text + + `c.tex' contains: + + \CJKenc{UTF8} + Some Unicode text + + `master.tex' can now include the files as follows: + + Some Korean text + + \CJKinput{a} + \input{b} + \input{c} + + Calling cjk-write-all-files automatically converts `master.tex' and + `a.tex'. + +The functions batch-cjk-write-file and batch-force-write-file are intended +to be used in Makefiles; please read the function documentation for more +details. + +It is recommended that you assign cjk-write-file or cjk-write-all-files to a +key (e.g., with global-set-key) in your `.emacs' configuration file. + + +Usage with AUC TeX +------------------ + +Append the data between >>> and <<< to your .emacs file to have special CJK +support within AUC TeX: + + +>>> + + (defun TeX-run-CJK-LaTeX (name command file) + "Create a process for NAME using COMMAND to format FILE with CJK/LaTeX." + +; use next code line for Mule instead of the (balanced) expression +; containing `cjk-write-all-files' +; -- no multifile document support! +; (cjk-write-file) + + (cjk-write-all-files (concat (TeX-master-directory) + (file-name-nondirectory file) + ".tex")) + (TeX-run-LaTeX name command file)) + + ;; replace the error source file `*.cjk' with `*.tex' (and `*-cjk.bib' + ;; with `*.bib'), then C-c ` can be used as usual. + + (add-hook 'TeX-translate-location-hook + '(lambda () + (if (string-match "\\(.*\\)\.cjk$" file) + (setq file + (concat + (substring file + (match-beginning 1) + (match-end 1)) + ".tex")) + (if (string-match "\\(.*\\)-cjk\.bib$" file) + (setq file + (concat + (substring file + (match-beginning 1) + (match-end 1)) + ".bib")))))) + + (require 'tex) + (add-to-list 'TeX-command-list + '("CJKLaTeX" "%l '\\nonstopmode\\input{%s.cjk}'" TeX-run-CJK-LaTeX nil t)) + +<<< + + +To process a CJK document with AUC TeX use C-c C-c on your LaTeX source file +and select CJKLaTeX as the formatting command. It also works with multiple +files; only modified files are converted (again). + +Note that only the master file is processed with cjk-enc and scanned for +\CJKinclude and \CJKinput! + +If you mainly write text in Japanese or Chinese, consider the use of +cjkspace.el or cjktilde.el for inserting a tilde character (which has been +redefined to a shibuaki space) if you hit the space key. Please read the +documentation in the two files for differences. cjkspace.el works with +AUC TeX only, cjktilde.el works in every mode. + + +Technical notes +--------------- + +cjk-enc.el loads MULEenc.sty or CJK.sty in the first output line which +contains all needed definitions for LaTeX 2e. + +To assure working in verbatim environments, \CJKenc and the LaTeX 2e macros +are not output directly. The active character 0x7F is used to output +\CJKenc, \CJKspace, Latin characters, etc. + +CNS 1-CNS 7 and JIS2 encoded characters are output as \CJKchar macros. The +reason for this choice is the infrequency of CNS and JIS2 characters in +normal text. Since \CJKchar does not select a new binding this macro is +executed faster for single CNS and JIS2 characters. + + +Problems and Tips +----------------- + +. cjk-enc.el starts a CJK environment only if it finds at least one CJK + character in the master file; this character can appear in a comment also. + Example: + + % some Chinese text in this comment + \CJKinput{a} + \CJKbibliography{b} + +. If you need some CJK processing in the preamble you must start a CJK + environment there manually because cjk-enc.el uses the \AtBeginDocument + hook for its commands. This interferes with the \CJKspace/\CJKnospace + insertion mechanism of cjk-enc.el because the Lisp code always assumes a + single, global CJK environment. A similar problem exists if you start a + new language in a comment. To overcome this, simply insert a \CJKspace or + \CJKnospace command (whatever appropriate) right after the + `\begin{document}' macro to synchronize again with cjk-enc.el . + + Example: + + \documentclass{article} + + \begin{CJK*}{}{} + some Japanese macro stuff + \end{CJK*} + + \begin{document} + \CJKnospace + more Japanese text + ... + +. Another consequence of the \CJKspace/\CJKnospace insertion mechanism of + cjk-enc.el is that in cases like + + Latin_text Chinese_text\ Latin_text + + you can't omit the final `\ ' after the Chinese phrase---only for Korean + words it is not necessary to use a (protected) space. + +. Usually, Emacs can automatically recognize the encoding of a given file + (e.g., using a language environment or setting `file-coding-system-alist'; + please read the chapter `Recognizing Coding Systems' in the emacs info + files for further details). But sometimes this fails (e.g., to find out + whether a text is in latin-1 or in, say, latin-3 is impossible), and you + have to use a file variable to define the encoding. + + Here an example how to specify `Big 5' encoding for a TeX input file (the + following lines are to be inserted at the very end): + + % Local Variables: + % coding: big5 + % End: + + If AUCTeX already has created local variables like `TeX-master', simply + add the line `coding: big5' and you are done. + +. Another useful local variable for AUCTeX is `TeX-command-default': + + % Local Variables: + % TeX-command-default: "CJKLaTeX" + % End: + + selects `CJKLaTeX' as the default command if you type `C-c C-c'. + + +---End of cjk-enc.txt--- |