source/texk/web2c/man/patgen.man

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