source/texk/web2c/man/patgen.man

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