summaryrefslogtreecommitdiff
path: root/language/chinese/CJK/cjk-4.8.5/doc/pyhyphen.txt
blob: 63e68dce323d5dd0fb1e058908f5ea15fc11240a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
This is the file pyhyphen.txt of the CJK macro package ver. 4.8.5
(16-Oct-2021).

Hyphenation patterns for pinyin syllables with and without tone markers
-----------------------------------------------------------------------

Sometimes it makes sense to use unaccented pinyin syllables for common names
and phrases which are repeated frequently; sometimes you are in an
environment which doesn't allow accented pinyin syllables at all. For such
cases it is desirable to have correct hyphenation, avoiding manually added
hints using e.g., `\-' between the syllables.

Fortunately, due to the limited numbers of Chinese pinyin syllables (407 for
Mandarin), it is easy to create hyphenation patterns. The logical
consequence is to add a new `language' to the Babel package, and exactly
this can be found in the directory utils/pyhyphen.


Installation
------------

[Note: The hyphenation patterns have been submitted to the `tex-hyphen'
       project. In recent TeX distributions it is no longer necessary to set
       up pinyin support manually since everything should work out of the
       box.]

This is fairly straightforward. Move the Babel language definition file
pinyin.ldf file to a place found by TeX. If you e.g., maintain a local
TEXMF tree, a good place would be $TEXMFLOCAL/tex/generic/babel/pinyin.ldf.
Similarly, move the pinyin hyphenation pattern files hyph-zh-latn-pinyin.tex
and hyph-zh-latin-tonepinyin.tex into your (local) TEXMF tree: The analogous
place would be directory $TEXMFLOCAL/tex/generic/hyphen.

Now run texconfig (or a similar tool) to add hyph-zh-latn-pinyin.tex and
hyph-zh-latin-tonepinyin.tex to the used hyphenation patterns. In the usual
case you have to add a line saying

  pinyin    hyph-zh-latn-tonepinyin.tex

for Unicode-aware TeX engines (XeTeX, luatex, upTeX) or

  pinyin    hyph-zh-latn-pinyin.tex

for all other engines to the hyphenation configuration file language.dat.
Finally, build a new format file (usually the command `initex latex.ltx');
in most cases this happens automatically.

Using Babel ensures that it works both with LaTeX and Plain TeX.


Usage
-----

Unicode-aware engines
- - - - - - - - - - -

Do something like this:

  \documentclass[...]{...}

  \usepackage[pinyin,german,english]{babel}
  ...

  \begin{document}
  ...
  \foreignlanguage{pinyin}{pinyin with tone markers like Běijīng}
  ...
  \end{document}


Other engines
- - - - - - -

Do something like this:

  \documentclass[...]{...}

  \usepackage[T1]{fontenc}
  \usepackage[pinyin,german,english]{babel}
  ...

  \begin{document}
  ...
  \foreignlanguage{pinyin}{pinyin without tone markers like Beijing}
  ...
  \end{document}


Note 1: pinyin.ldf is intentionally very minimal. Don't expect that e.g.,
        \chapter yields a pinyin version of the Chinese word for `chapter'.
        It might be useful to define a shorthand macro like the following:

          \newcommand{\py}[1]{\foreignlanguage{pinyin}{#1}}

        Now you can simply say

          \py{Beijing}

Note 2: The apostrophe character `'' is used as to precede syllables
        starting with `a', `e', or `u'. This is needed to resolve
        ambiguities like this:

          Xi'an -> Xi-an (two syllables)
          Xian  -> Xian (one syllable)

        If a line break occurs, the apostrophe should vanish, e.g.,

          Tian'anmen -> Tian-
                        anmen

        Use the Babel shorthand "' to enter '; this internally resolves to
        \discretionary.

        The shorthand `"u' (as used in German) is available to input
        `umlaut u'.

Note 3: Most Babel language support files define a `<language>.sty' file
        also. This is not true for pinyin! pinyin.sty is used for accented
        pinyin syllables which don't need a special hyphenation support.
        (pinyin.sty works with Plain TeX also.)


Technical details
-----------------

The dictionary used to construct the hyphenation patterns has been created
with a small C program `pinyin.c' which simply combines all existing Chinese
syllable pairs that don't need an apostrophe inbetween. Then, `patgen' has
been run on the dictionary; `pinyin.tr' defines the used character set.

Due to the regularity of the word combinations, only two-letter patterns of
the first and second level are needed to find all possible breaks without a
single error or omission.

---End of pyhyphen.txt---