Debian Codegraph @

texmf-dist/doc/man/man1/patgen.1

raw
1 .TH PATGEN 1 "10 January 2026" "Web2C 2026"
2 .\"=====================================================================
3 .if t .ds TX \fRT\\h'-0.10m'\\v'0.17v'E\\v'-0.17v'\\h'-0.06m'X\fP
4 .if n .ds TX TeX
5 .ie t .ds OX \fIT\h'-0.17m'\v'+0.21m'E\v'-0.21m'\h'-0.04m'X\fP
6 .el .ds OX TeX
7 .\"=====================================================================
8 .SH NAME
9 patgen \- generate patterns for TeX hyphenation
10 .SH SYNOPSIS
11 .B patgen
12 .I dictionary_file pattern_file patout_file translate_file
13 .\"=====================================================================
14 .SH DESCRIPTION
15 The
16 .I patgen
17 program reads a
18 .I dictionary_file
19 containing a list of hyphenated words and a
20 .I pattern_file
21 containing previously-generated patterns (if any) for a particular
22 language (not a complete \*(TX source file; see below), and produces the
23 .I patout_file
24 with (previously- plus newly-generated) hyphenation patterns for that
25 language. The
26 .I translate_file
27 defines language specific values for the parameters
28 .IR left_hyphen_min " and " right_hyphen_min
29 used by \*(TX's hyphenation algorithm and the external representation
30 of the lower and upper case version(s) of all `letters' of that
31 language. Further details of the pattern generation process such as
32 hyphenation levels and pattern lengths are requested interactively from
33 the user's terminal. Optionally,
34 .I patgen
35 creates a new dictionary file
36 .BI pattmp. n
37 showing the good and bad hyphens found by the generated patterns, where
38 .I n
39 is the highest hyphenation level.
40 .PP
41 The patterns generated by
42 .I patgen
43 can be read by
44 .BR initex (1)
45 for use in hyphenating words. For the original example of
46 .IR patgen 's
47 output, see (in \*(TX Live)
48 .IR $TEXMFMAIN/tex/generic/hyphen/hyphen.tex ,
49 which contains the patterns \*(TX uses for English by default. In \*(TX
50 Live, patterns for (many) other languages are available (unless chosen
51 not to be installed).
52 .PP
53 All filenames must be complete; no adding of default
54 extensions or path searching is done.
55 .\"=====================================================================
56 .SH FILE FORMATS
57 .TP \w'@@'u+2n
58 .B Letters
59 When
60 .B initex
61 digests hyphenation patterns, \*(TX first expands macros and the result
62 must entirely consist of digits (hyphenation levels), dots (`.', meaning
63 the edge of a word), and letters. In pattern files for non-English
64 languages letters are often represented by macros or other expandable
65 constructs. For the purpose of
66 .I patgen
67 these are just character sequences, subject to the condition that no
68 such sequence is a prefix of another one.
69 .TP \w'@@'u+2n
70 .B Dictionary file
71 A dictionary file contains a weighted list of hyphenated words, one word
72 per line, each starting in column 1. A digit in column 1 indicates a
73 global word weight (initially =1) applicable to all following words up
74 to the next global word weight. A digit at some intercharacter position
75 indicates a weight for that position only.
76
77 The hyphens in a word are indicated by `-', `*', or `.' (or their
78 replacements as defined in the translate file) for hyphens yet to be
79 found, `good' hyphens (correctly found by the patterns), and `bad'
80 hyphens (erroneously found by the patterns) respectively; when reading a
81 dictionary file `*' is treated like `-' and `.' is ignored.
82 .TP
83 .B Pattern file
84 A pattern file contains only patterns in the format above, e.g., from a
85 previous run of patgen. It may \fInot\fR contain any \*(TX comments or
86 control sequences. For instance, this is not a valid pattern file:
87 .nf
88
89 % this is an invalid pattern file for TeX.
90 \\patterns{%
91 .\|.\|.
92 }
93 .fi
94 Pattern files can only contain the actual patterns, i.e., the `.\|.\|.'.
95 .TP
96 .B Translate file
97 A translate file starts with a line containing the values of
98 .I left_hyphen_min
99 in columns 1-2,
100 .I right_hyphen_min
101 in columns 3-4, and either a blank or the replacement for one of the
102 ``hyphen'' characters `-', `*', and `.' in columns 5, 6, and 7. Input
103 lines are extended with blanks as for many \*(TX related programs.
104
105 Each following line defines one `letter': an arbitrary delimiter
106 character in column 1, followed by one or more external representations
107 of that character (first the `lower' case one used for output), each
108 one terminated by the delimiter and the whole sequence terminated by
109 another delimiter.
110
111 If the translate file is empty, the default values are
112 .IR left_hyphen_min "=2, " right_hyphen_min "=3,"
113 and the 26 lower case letters
114 .BR a .\|.\|. z
115 with their upper case representations
116 .BR A .\|.\|. Z .
117 .TP
118 .B Terminal input
119 After reading the
120 .I translate_file
121 and any previously-generated patterns from
122 .IR pattern_file ,
123 .I patgen
124 requests input from the user's terminal.
125
126 First the integer values of
127 .IR hyph_start " and " hyph_finish ,
128 the lowest and highest hyphenation level for which patterns are to be
129 generated. The value of
130 .I hyph_start
131 should be larger than any hyphenation level already present in
132 .IR pattern_file .
133
134 Then, for each hyphenation level, the integer values of
135 .IR pat_start " and " pat_finish ,
136 the smallest and largest pattern length to be analyzed, as well as
137 .IR "good weight" ", " "bad weight" ", and " threshold ,
138 the weights for good and bad hyphens and a weight threshold for useful
139 patterns.
140
141 Finally the decision (`y' or `Y' vs. anything else) whether or not to
142 produce a hyphenated word list.
143 .\"=====================================================================
144 .SH FILES
145 .TP \w'@@'u+2n
146 $TEXMFMAIN/tex/generic/hyphen/hyphen.tex
147 The original hyphenation patterns for English, by Donald Knuth and Frank
148 Liang.
149 .TP
150 $TEXMFMAIN/tex/generic/hyphen/zerohyph.tex
151 A pattern file with no patterns, for languages that don't use
152 hyphenation.
153 .\"=====================================================================
154 .SH "SEE ALSO"
155 Frank Liang and Peter Breitenlohner,
156 patgen.web.
157 .PP
158 Frank Liang,
159 .IR "Word hy-phen-a-tion by com-puter" ,
160 STAN-CS-83-977,
161 Stanford University Ph.D. thesis, 1983,
162 http://tug.org/docs/liang.
163 .PP
164 Donald E. Knuth,
165 .IR "The \*(OXbook" ,
166 Addison-Wesley, Appendix H.
167 .TP
168 https://ctan.org/pkg/hyphenex
169 Hyphenation exceptions for American English, maintained by the
170 \fITUGboat\fP editors, and used in \fITUGboat\fP articles by default.
171 .TP
172 https://ctan.org/pkg/hyph-utf8
173 Collected hyphenation patterns for many languages in many formats.
174 .TP
175 https://ctan.org/pkg/ushyph
176 Large set of additional hyphenation patterns for English, extended by
177 Gerard Kuiken.
178 .TP
179 https://ctan.org/tex-archive/language/
180 General CTAN directory for patterns and support for many other languages.
181 .TP
182 https://tug.org/TUGboat/Contents/listkeyword.html#CatTAGMultilingualDocumentProcessing
183 \fITUGboat\fP articles on hyphenation and other aspects of
184 language-specific document processing.
185 .\"=====================================================================
186 .SH AUTHORS
187 Frank Liang wrote the first version of this program. Peter
188 Breitenlohner made a
189 substantial revision in 1991 for \*(TX 3.
190 The first version was published as the appendix to the
191 .I \*(OXware
192 technical report. Howard Trickey originally ported it to Unix.
193 .PP
194 Public discussion list and bug reports: https://lists.tug.org/tex-k