| 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 |