help2man for fmtutil, update man page

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

3 files changed, 199 insertions, 104 deletions

diff --git a/Build/source/texk/texlive/tl_scripts/Makefile.am b/Build/source/texk/texlive/tl_scripts/Makefile.am
index 68ff69158b2..6d2a927f5bf 100644
--- a/Build/source/texk/texlive/tl_scripts/Makefile.am
+++ b/Build/source/texk/texlive/tl_scripts/Makefile.am
@@ -99,16 +99,19 @@ dist_texconfig_DATA = tcfmgr.map
 web2cdir = $(datarootdir)/texmf-dist/web2c
 dist_web2c_DATA = fmtutil.cnf
 
-## Generate the updmap man page using help2man plus a bit of
-## handwritten material.  But don't actually update updmap.1,
+## Generate the updmap/fmtutil man page using help2man plus a bit of
+## handwritten material.  But don't actually update updmap/fmtutil.1,
 ## we don't want to require help2man for an install.  Leave that to be
 ## done by hand.
-.PHONY: xupdmap.1
-updmap_dir = $(top_srcdir)/linked_scripts/texlive
-xupdmap.1: updmap.help2man $(updmap_dir)/updmap.pl
+.PHONY: xupdmap.1 xfmtutil.1
+linked_scripts_dir = $(top_srcdir)/linked_scripts/texlive
+xupdmap.1: updmap.help2man $(linked_scripts_dir)/updmap.pl
 	help2man --include=$< --source="TeX Live" --no-info \
-	  $(updmap_dir)/updmap.pl >/tmp/$@
-EXTRA_DIST += updmap.help2man
+	  $(linked_scripts_dir)/updmap.pl >/tmp/$@
+xfmtutil.1: fmtutil.help2man $(linked_scripts_dir)/fmtutil.pl
+	help2man --include=$< --source="TeX Live" --no-info \
+	  $(linked_scripts_dir)/fmtutil.pl >/tmp/$@
+EXTRA_DIST += updmap.help2man fmtutil.help2man
 
 
 ## 
diff --git a/Build/source/texk/texlive/tl_scripts/fmtutil.1 b/Build/source/texk/texlive/tl_scripts/fmtutil.1
index c97449986b7..1b4357cdfa9 100644
--- a/Build/source/texk/texlive/tl_scripts/fmtutil.1
+++ b/Build/source/texk/texlive/tl_scripts/fmtutil.1
@@ -1,126 +1,196 @@
-.TH FMTUTIL 1 "July 2014" "TeX Live" "TeX Live"
-.SH "NAME"
-fmtutil \- utility for maintaining TeX format files
-.PP
-fmtutil-sys \- utility for maintaining TeX format files system\-wide
-.SH "SYNOPSIS"
-.B fmtutil\fP
-.RI [ OPTION .\|.\|.]
-.I COMMAND
-.PP
+.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.46.5.
+.TH FMTUTIL "1" "April 2015" "TeX Live" "User Commands"
+.SH NAME
+fmtutil \- manage TeX formats, Metafont bases and Metapost mems, per-user
+.br
+fmtutil-sys \- manage TeX formats, Metafont bases and Metapost mems, system-wide
+.br
+mktexfmt \- create a TeX format, Metafont base, or Metapost mem
+.SH SYNOPSIS
+.B fmtutil
+[\fI\,OPTION\/\fR] ... [\fI\,COMMAND\/\fR]
+.br
 .B fmtutil-sys
-.RI [ OPTION .\|.\|.]
-.I COMMAND
-.SH "DESCRIPTION"
-\fBfmtutil\fP is used to create or recreate format and hyphenation
-files or show information about format files\&.  The directory in which
-\fBfmtutil\fP is found is also preferentially used to find subprograms.
+[\fI\,OPTION\/\fR] ... [\fI\,COMMAND\/\fR]
+.br
+.B mktexfmt
+\fI\,FORMAT.fmt|BASE.base|MEM.mem|FMTNAME.EXT\/\fR
+.SH DESCRIPTION
+fmtutil version svn36788 (2015\-04\-13 00:53:26 +0900)
+.PP
+Rebuild and manage TeX formats, Metafont bases and MetaPost mems.
 .PP
-\fICOMMAND\fP is one of:
+If the command name ends in mktexfmt, only one format can be created.
+The only options supported are \fB\-\-help\fR and \fB\-\-version\fR, and the command
+line must consist of either a format name, with its extension, or a
+plain name that is passed as the argument to \fB\-\-byfmt\fR (see below).  The
+full name of the generated file (if any) is written to stdout, and
+nothing else.
 .PP
+If not operating in mktexfmt mode, the command line can be more general,
+and multiple formats can be generated, as follows.
+.SH OPTIONS
 .TP
-.B --all
-recreate all format files
+\fB\-\-cnffile\fR FILE
+read FILE instead of fmtutil.cnf
+(can be given multiple times, in which case
+all the files are used)
+.HP
+\fB\-\-fmtdir\fR DIRECTORY
 .TP
-.BI --byengine \ enginename
-(re)create formats that depend on the
-engine \fIenginename\fP
+\fB\-\-no\-engine\-subdir\fR
+don't use engine\-specific subdir of the fmtdir
 .TP
-.BI --byfmt \ formatname
-(re)create the format for
-format \fIformatname\fP
+\fB\-\-no\-error\-if\-no\-format\fR
+exit successfully if no format is selected
 .TP
-.BI --byhyphen \ hyphenfile
-(re)create formats that depend on the
-hyphenation file \fIhyphenfile\fP
+\fB\-\-no\-error\-if\-no\-engine\fR=\fI\,ENGINE1\/\fR,ENGINE2,...
+exit successfully even if the required engine
+.IP
+is missing, if it is included in the list.
 .TP
-.B --catcfg
-output the content of the config file
-.TP
-.BI --disablefmt \ formatname
-disable
-.I formatname
-in config file
+\fB\-\-quiet\fR
+be silent
 .TP
-.B --edit
-no-op in TeX Live
+\fB\-\-test\fR
+(not implemented, just for compatibility)
 .TP
-.BI --enablefmt \ formatname
-ensable
-.I formatname
-in config file
+\fB\-\-dolinks\fR
+(not implemented, just for compatibility)
 .TP
-.B --help
-print a summary of commands and options
+\fB\-\-force\fR
+(not implemented, just for compatibility)
+.SS "Commands:"
 .TP
-.B --listcfg
-list (enabled and disabled) configurations, filtered to available formats
+\fB\-\-all\fR
+recreate all format files
 .TP
-.B --missing
+\fB\-\-missing\fR
 create all missing format files
 .TP
-.B --refresh
+\fB\-\-refresh\fR
 recreate only existing format files
 .TP
-.BI --showhyphen \ formatname
-print the name of the
-hyphenation file for the format
-\fIformatname\fP
-.TP
-.B --version
-show version info
-.SH "OPTIONS"
-.TP
-.BI --cnffile \ file
-specify the configuration
-\fIfile\fP \fBfmtutil\fP should use
+\fB\-\-byengine\fR ENGINENAME
+(re)create formats using ENGINENAME
 .TP
-.B --dolinks
-(not implemented, just for compatibility)
+\fB\-\-byfmt\fR FORMATNAME
+(re)create format for FORMATNAME
 .TP
-.BI --fmtdir \ directory
-set the destination
-directory for format files generated by
-\fBfmtutil\fP to \fIdirectory\fP
+\fB\-\-byhyphen\fR HYPHENFILE
+(re)create formats that depend on HYPHENFILE
 .TP
-.B --force
-(not implemented, just for compatibility)
+\fB\-\-enablefmt\fR FORMATNAME
+enable formatname in config file
 .TP
-.B --no-engine-subdir
-don't use engine-specific subdir of the fmtdir
+\fB\-\-disablefmt\fR FORMATNAME
+disable formatname in config file
 .TP
-.BI --no-error-if-no-engine \ engine1,engine2,...
-exit successfully even if the required engine is missing, if that engine
-is included in the list here.
+\fB\-\-listcfg\fR
+list (enabled and disabled) configurations,
+filtered to available formats
 .TP
-.B --no-error-if-no-format
-exit successfully if no format is selected
+\fB\-\-catcfg\fR
+output the content of the config file
 .TP
-.B --quiet
-be silent
+\fB\-\-showhyphen\fR FORMATNAME
+print name of hyphenfile for format FORMATNAME
 .TP
-.B --test
-(not implemented, just for compatibility)
-.SH "FILES"
+\fB\-\-version\fR
+show version information and exit
 .TP
-.I fmtutil\&.cnf
-default configuration file; run \fIkpsewhich fmtutil.cnf\fP to see the
-active file.
+\fB\-\-help\fR
+show this message and exit
+.SH ENVIRONMENT
+.PP
+Explanation of trees and files normally used:
+.IP
+If \fB\-\-cnffile\fR is specified on the command line (possibly multiple
+times), its value(s) are used.  Otherwise, fmtutil reads all the
+fmtutil.cnf files found by running `kpsewhich \fB\-all\fR fmtutil.cnf', in the
+order returned by kpsewhich.
+.IP
+In any case, if multiple fmtutil.cnf files are found, all the format
+definitions found in all the fmtutil.cnf files are merged.
+.IP
+Thus, if fmtutil.cnf files are present in all trees, and the default
+layout is used as shipped with TeX Live, the following files are
+read, in the given order.
+.nf
+.IP
+For fmtutil\-sys:
+TEXMFSYSCONFIG \fI\,$TEXLIVE/YYYY/texmf\-config/web2c/fmtutil.cnf\/\fP
+TEXMFSYSVAR    \fI\,$TEXLIVE/YYYY/texmf\-var/web2c/fmtutil.cnf\/\fP
+TEXMFLOCAL     \fI\,$TEXLIVE/texmf\-local/web2c/fmtutil.cnf\/\fP
+TEXMFDIST      \fI\,$TEXLIVE/YYYY/texmf\-dist/web2c/fmtutil.cnf\/\fP
+.IP
+For fmtutil:
+TEXMFCONFIG    $HOME/.texliveYYYY/texmf\-config/web2c/fmtutil.cnf
+TEXMFVAR       $HOME/.texliveYYYY/texmf\-var/web2c/fmtutil.cnf
+TEXMFHOME      \fI\,$HOME/texmf/web2c/fmtutil.cnf\/\fP
+TEXMFSYSCONFIG \fI\,$TEXLIVE/YYYY/texmf\-config/web2c/fmtutil.cnf\/\fP
+TEXMFSYSVAR    \fI\,$TEXLIVE/YYYY/texmf\-var/web2c/fmtutil.cnf\/\fP
+TEXMFLOCAL     \fI\,$TEXLIVE/texmf\-local/web2c/fmtutil.cnf\/\fP
+TEXMFDIST      \fI\,$TEXLIVE/YYYY/texmf\-dist/web2c/fmtutil.cnf\/\fP
+.IP
+(where YYYY is the TeX Live release version).
+.fi
+.IP
+According to the actions, fmtutil might write to one of the given files
+or create a new fmtutil.cnf, described further below.
+.PP
+Where changes are saved:
+.IP
+If config files are given on the command line, then the first one
+given will be used to save any changes from \fB\-\-enable\fR or \fB\-\-disable\fR.
+If the config files are taken from kpsewhich output, then the
+algorithm is more complex:
+.IP
+1) If \fI\,$TEXMFCONFIG/web2c/fmtutil.cnf\/\fP or \fI\,$TEXMFHOME/web2c/fmtutil.cnf\/\fP
+appears in the list of used files, then the one listed first by
+kpsewhich \fB\-\-all\fR (equivalently, the one returned by kpsewhich
+fmtutil.cnf), is used.
+.IP
+2) If neither of the above two are present and changes are made, a
+new config file is created in \fI\,$TEXMFCONFIG/web2c/fmtutil.cnf\/\fP.
+.IP
+In general, the idea is that if a given config file is not writable, a
+higher\-level one can be used.  That way, the distribution's settings
+can be overridden for system\-wide using TEXMFLOCAL, and then system
+settings can be overridden again for a particular using using TEXMFHOME.
 .PP
-The command \fIkpsewhich --engine=/ --all foo.fmt\fP  should show the
-locations of any and all \fIfoo.fmt\fP files.
+Resolving multiple definitions of a format:
+.IP
+If a format is defined in more than one config file, then the definition
+coming from the first\-listed fmtutil.cnf is used.
 .PP
-For more information about fmt generation in TeX Live, try
-"tlmgr --help" or see http://tug.org/texlive/doc/tlmgr.html.
-The "generate" action in tlmgr does the work.
-.SH "SEE ALSO"
-.BR kpsewhich (1)
-.SH "BUGS"
-Please send bug reports to <tex-k@tug.org> (public mailing list).
-.SH "AUTHOR"
-\fBfmtutil\fP was originally written by Thomas Esser
-and is in the public domain.  It is now maintained as part of TeX Live.
+Disabling formats:
+.IP
+fmtutil.cnf files with higher priority (listed earlier) can disable
+formats mentioned in lower priority (listed later) fmtutil.cnf files by
+writing, e.g.,
+.IP
+#! <fmtname> <enginename> <hyphen> <args>
+.IP
+in the higher\-priority fmtutil.cnf file.
+.IP
+As an example, suppose you have want to disable the luajitlatex format.
+You can create the file \fI\,$TEXMFCONFIG/web2c/fmtutil.cnf\/\fP with the content
+.IP
+#! luajitlatex luajittex language.dat,language.dat.lua lualatex.ini
+.IP
+and call fmtutil.
 .PP
-This manual page was written by C\&.M\&. Connelly <c@eskimo\&.com>, for
-the Debian GNU/Linux system and later slightly adapted for the teTeX 3
-release\&.
+fmtutil vs. fmtutil\-sys (fmtutil \fB\-\-sys\fR):
+.IP
+When fmtutil\-sys is run or the command line option \fB\-\-sys\fR is used,
+TEXMFSYSCONFIG and TEXMFSYSVAR are used instead of TEXMFCONFIG and
+TEXMFVAR, respectively.  This is the primary difference between
+fmtutil\-sys and fmtutil.
+.IP
+Other locations may be used if you give them on the command line, or
+these trees don't exist, or you are not using the original TeX Live.
+.SH "REPORTING BUGS"
+Report bugs to: tex\-k@tug.org
+.br
+TeX Live home page: <http://tug.org/texlive/>
diff --git a/Build/source/texk/texlive/tl_scripts/fmtutil.help2man b/Build/source/texk/texlive/tl_scripts/fmtutil.help2man
new file mode 100644
index 00000000000..2f3cad6d798
--- /dev/null
+++ b/Build/source/texk/texlive/tl_scripts/fmtutil.help2man
@@ -0,0 +1,22 @@
+# $Id: fmtutil.help2man 31440 2013-08-15 22:39:10Z karl $
+# This help2man auxiliary file is in the public domain.
+# Originally created by Karl Berry.
+# See the Makefile for the help2man invocation.
+# do not fill the long TEXMF* tables.
+
+[NAME]
+fmtutil \- manage TeX formats, Metafont bases and Metapost mems, per-user
+.br
+fmtutil-sys \- manage TeX formats, Metafont bases and Metapost mems, system-wide
+.br
+mktexfmt \- create a TeX format, Metafont base, or Metapost mem
+
+/show this message and exit/
+.SH ENVIRONMENT
+
+/in the given order/
+.nf
+
+/where YYYY is/
+.fi
+