patterns input is not a TeX patterns file

git-svn-id: svn://tug.org/texlive/trunk@5593 c570f23f-e606-0410-a88d-b1316a301751

2 files changed, 55 insertions, 28 deletions

diff --git a/Build/source/texk/web2c/man/ChangeLog b/Build/source/texk/web2c/man/ChangeLog
index e0789cff0da..860b0d2e6da 100644
--- a/Build/source/texk/web2c/man/ChangeLog
+++ b/Build/source/texk/web2c/man/ChangeLog
@@ -1,3 +1,9 @@
+2007-11-25  Karl Berry  <karl@tug.org>
+
+	* patgen.man: mention that the "patterns" input file to patgen is
+	not an actual TeX patterns file.
+	Kurt Roeckx, 17 Nov 2007 20:54:43, debian bug 450875.
+
 2007-04-20  Karl Berry  <karl@tug.org>
 
 	* gftodvi.man: no way to override output filename for gftodvi
diff --git a/Build/source/texk/web2c/man/patgen.man b/Build/source/texk/web2c/man/patgen.man
index d32f56e37a3..f8e6332b01d 100644
--- a/Build/source/texk/web2c/man/patgen.man
+++ b/Build/source/texk/web2c/man/patgen.man
@@ -1,9 +1,10 @@
-.TH PATGEN 1 "23 August 2004" "Web2C @VERSION@"
+.TH PATGEN 1 "25 November 2007" "Web2C @VERSION@"
 .\"=====================================================================
 .if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP
 .if n .ds TX TeX
 .ie t .ds OX \fIT\v'+0.25m'E\v'-0.25m'X\fP for troff
-.el .ds OX TeX for nroff
+.el .ds OX TeX
+.\" that's for nroff.
 .\" the same but obliqued
 .\" BX definition must follow TX so BX can use TX
 .if t .ds BX \fRB\s-2IB\s0\fP\*(TX
@@ -19,19 +20,18 @@ patgen \- generate patterns for TeX hyphenation
 .I dictionary_file pattern_file patout_file translate_file
 .\"=====================================================================
 .SH DESCRIPTION
-This manual page is not meant to be exhaustive.  The complete
-documentation for this version of \*(TX can be found in the info file
-or manual
+This manual page is not meant to be exhaustive.  
+See also the Info file or manual
 .IR "Web2C: A TeX implementation" .
 .PP
 The
-.B patgen
+.I patgen
 program reads the
 .I dictionary_file
 containing a list of hyphenated words and the
 .I pattern_file
 containing previously-generated patterns (if any) for a particular
-language, and produces the
+language (not a complete TeX source file; see below), and produces the
 .I patout_file
 with (previously- plus newly-generated) hyphenation patterns for that
 language. The
@@ -43,28 +43,26 @@ of the lower and upper case version(s) of all \`letters' of that
 language. Further details of the pattern generation process such as
 hyphenation levels and pattern lengths are requested interactively from
 the user's terminal. Optionally
-.B patgen
+.I patgen
 creates a new dictionary file
 .BI pattmp. n
 showing the good and bad hyphens found by the generated patterns, where
 .I n
-is the highest hypenation level.
+is the highest hyphenation level.
 .PP
 The patterns generated by
-.B patgen
+.I patgen
 can be read by
 .B initex
-for use in hyphenating words. For a (very) long example of
+for use in hyphenating words. For a real-life example of
 .IR patgen 's
 output, see
 .IR $TEXMFMAIN/tex/generic/hyphen/hyphen.tex ,
-which contains the patterns \*(TX uses for English.
-At some sites, patterns for several other languages may be available,
+which contains the patterns \*(TX uses for English by default.
+At some sites, patterns for (many) other languages may be available,
 and the local
 .B tex
-programs may have them preloaded; consult your
-.I Local Guide
-or your system administrator for details.
+programs may have them preloaded.
 .PP
 All filenames must be complete; no adding of default
 extensions or path searching is done.
@@ -79,7 +77,7 @@ must entirely consist of digits (hyphenation levels), dots (\`.', edge
 of a word), and letters. In pattern files for non-English languages
 letters are often represented by macros or other expandable constructs.
 For the purpose of
-.B patgen
+.I patgen
 these are just character sequences, subject to the condition that no
 such sequence is a prefix of another one.
 .TP \w'@@'u+2n
@@ -95,10 +93,23 @@ replacements as defined in the translate file) for hyphens yet to be
 found, \`good' hyphens (correctly found by the patterns), and \`bad'
 hyphens (erroneously found by the patterns) respectively; when reading a
 dictionary file \`*' is treated like \`-' and \`.' is ignored.
-.TP \w'@@'u+2n
+.TP
+.B Pattern file
+A pattern file contains only patterns in the format above, e.g., from a
+previous run of patgen.  It may \fInot\fR contain any \*(TX comments or
+control sequences.  For instance, this is not a valid pattern file:
+.nf
+
+% this is a pattern file read by TeX.
+\\patterns{%
+ ...
+}
+.fi
+It can only contain the actual patterns, i.e., the `...'.
+.TP
 .B Translate file
 A translate file starts with a line containing the values of
-.I left_hypen_min
+.I left_hyphen_min
 in columns 1-2,
 .I right_hyphen_min
 in columns 3-4, and either a blank or the replacement for one of the
@@ -112,19 +123,19 @@ one terminated by the delimiter and the whole sequence terminated by
 another delimiter.
 
 If the translate file is empty, the values
-.IR left_hypen_min "=2, " right_hyphen_min "=3,"
+.IR left_hyphen_min "=2, " right_hyphen_min "=3,"
 and the 26 lower case letters
 .IR a ... z
 with their upper case representations
 .IR A ... Z
 are assumed.
-.TP \w'@@'u+2n
+.TP
 .B Terminal input
 After reading the
 .I translate_file
 and any previously-generated patterns from
 .IR pattern_file,
-.B patgen
+.I patgen
 requests input from the user's terminal.
 
 First the integer values of
@@ -143,19 +154,30 @@ the weights for good and bad hyphens and a weight threshold for useful
 patterns.
 
 Finally the decision (\`y' or \`Y' vs. anything else) whether or not to
-produce a hypenated word list.
+produce a hyphenated word list.
 .\"=====================================================================
 .SH FILES
 .TP \w'@@'u+2n
 .I $TEXMFMAIN/tex/generic/hyphen/hyphen.tex
-Patterns for English.
+The original hyphenation patterns for English, by Donald Knuth and Frank
+Liang.
+.TP
+.I $TEXMFMAIN/tex/generic/hyphen/ushyphmax.tex
+Maximal hyphenation patterns for English, extended by Gerard Kuiken.
+.TP
+.I http://www.ctan.org/tex-archive/language/
+Patterns and support for many other languages
 .\"=====================================================================
 .SH "SEE ALSO"
+Frank Liang and Peter Breitenlohner,
+patgen.web.
+.PP
 Frank Liang,
 .IR "Word hy-phen-a-tion by com-puter" ,
 STAN-CS-83-977,
-Stanford University Ph.D. thesis, 1983.
-.br
+Stanford University Ph.D. thesis, 1983,
+http://tug.org/docs/liang.
+.PP
 Donald E. Knuth,
 .IR "The \*(OXbook" ,
 Addison-Wesley, 1986, ISBN 0-201-13447-0, Appendix H.
@@ -166,5 +188,4 @@ Breitenlohner made a
 substantial revision in 1991 for \*(TX 3.
 The first version was published as the appendix to the
 .I \*(OXware
-technical report, available from the \*(TX Users Group. Howard Trickey
-originally ported it to Unix.
+technical report. Howard Trickey originally ported it to Unix.