update the man page and pdf docu of tlmgr

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

2 files changed, 114 insertions, 26 deletions

diff --git a/Master/texmf/doc/man/man1/tlmgr.1 b/Master/texmf/doc/man/man1/tlmgr.1
index 2e85b96eccd..56a69c675f4 100644
--- a/Master/texmf/doc/man/man1/tlmgr.1
+++ b/Master/texmf/doc/man/man1/tlmgr.1
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
+.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.07)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
@@ -132,7 +132,7 @@
 .\" ========================================================================
 .\"
 .IX Title "TLMGR 1"
-.TH TLMGR 1 "2008-05-07" "perl v5.10.0" "User Contributed Perl Documentation"
+.TH TLMGR 1 "2008-07-22" "perl v5.10.0" "User Contributed Perl Documentation"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
@@ -141,11 +141,11 @@
 tlmgr \- the TeX Live Manager
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
-tlmgr [\fIoptions\fR] \fIaction\fR [\fIoption\fR]... [\fIoperand\fR]...
+tlmgr [\fIoption\fR]... \fIaction\fR [\fIoption\fR]... [\fIoperand\fR]...
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 \&\fBtlmgr\fR manages an existing TeX Live installation, both packages and
-options.
+configurations options.
 .SH "OPTIONS"
 .IX Header "OPTIONS"
 The following options have to be given \fIbefore\fR you specify the action.
@@ -164,14 +164,17 @@ into the respective screen of the \s-1GUI\s0. So calling
 .Ve
 .Sp
 will bring you directly into the update screen.
-.IP "\fB\-\-netarchive\fR \fIdir\fR" 8
-.IX Item "--netarchive dir"
-Overrides the default settings for netarchive. Should be used with care.
-.IP "\fB\-\-diskarchive\fR \fIdir\fR" 8
-.IX Item "--diskarchive dir"
-Overrides the default settings for diskarchive. Should be used with care.
+.IP "\fB\-\-gui\-lang\fR" 8
+.IX Item "--gui-lang"
+Normally the \s-1GUI\s0 tries to deduce your language from the environment
+(on Windows via the registry, on Unix via \s-1LC_MESSAGES\s0). If that fails 
+you can select a different language by giving this option a two-letter
+language code.
 .PP
-The standard options \fB\-\-help/\-h/\-?\fR and \fB\-\-debug\fR are also accepted.
+The standard options are also accepted: \fB\-\-help/\-h/\-?\fR, \fB\-\-version\fR,
+\&\fB\-q\fR (no informational messages), \fB\-v\fR (debugging messages, can be
+repeated).  For more information about the latter, see the
+TeXLive::TLUtils documentation.
 .SH "ACTIONS"
 .IX Header "ACTIONS"
 .IP "\fBhelp\fR" 8
@@ -179,7 +182,7 @@ The standard options \fB\-\-help/\-h/\-?\fR and \fB\-\-debug\fR are also accepte
 Gives this help page.
 .IP "\fBgui\fR" 8
 .IX Item "gui"
-Run using a graphical interface.
+Start the graphical user interface.
 .IP "\fBinstall [\f(BIoption\fB]... \f(BIpkg\fB...\fR" 8
 .IX Item "install [option]... pkg..."
 Install all \fIpkg\fRs given on the command line. By default this installs
@@ -201,6 +204,9 @@ written to the terminal.
 Updates the packages given as arguments to the latest version available
 at the installation source. Options:
 .RS 8
+.IP "\fB\-\-list\fR" 8
+.IX Item "--list"
+List only which packages could be updated.
 .IP "\fB\-\-all\fR" 8
 .IX Item "--all"
 Update all package.
@@ -208,6 +214,59 @@ Update all package.
 .IX Item "--dry-run"
 Nothing is actually installed; instead, the actions to be performed are
 written to the terminal.
+.IP "\fB\-\-backupdir directory\fR" 8
+.IX Item "--backupdir directory"
+If this option is given it must specify an existing directory where a 
+snapshot of the current package as installed will be saved before 
+the packages is updated. This way one can go back in case an update
+turned out as not working. See the action \fBrestore\fR for details.
+.RE
+.RS 8
+.RE
+.IP "\fBbackup \-\-backupdir dir [\-\-all] [pkg [pkg]]\fR" 8
+.IX Item "backup --backupdir dir [--all] [pkg [pkg]]"
+Makes a backup of the given packages (or all packages with \fB\-\-all\fR) to
+the directory specified with \fB\-\-backupdir\fR (must exist and be a writable).
+.Sp
+Warning: Making a backup of \fIall\fR packages will need quite some space and
+time.
+.Sp
+Options:
+.RS 8
+.IP "\fB\-\-backupdir directory\fR" 8
+.IX Item "--backupdir directory"
+This is an obligatory argument and has to specify a directory where
+backups are to be found.
+.IP "\fB\-\-all\fR" 8
+.IX Item "--all"
+Make a backup of all packages in the texlive.tlpdb
+.RE
+.RS 8
+.RE
+.IP "\fBrestore \-\-backupdir dir [pkg [rev]]\fR" 8
+.IX Item "restore --backupdir dir [pkg [rev]]"
+If no \fBpkg\fR and \fBrev\fR is given list all packages the available 
+backup revisions.
+.Sp
+With \fBpkg\fR given but without \fBrev\fR lists all available backup revisions
+of \fBpkg\fR.
+.Sp
+With both \fBpkg\fR an \fBrev\fR given tries to restore the package from its
+backup.
+.Sp
+The option \fB\-\-backupdir dir\fR is obligatory and has to specify a directory
+with backups.
+.Sp
+Options:
+.RS 8
+.IP "\fB\-\-dry\-run\fR" 8
+.IX Item "--dry-run"
+Nothing is actually restored; instead, the actions to be performed are
+written to the terminal.
+.IP "\fB\-\-backupdir directory\fR" 8
+.IX Item "--backupdir directory"
+This is an obligatory argument and has to specify a directory where
+backups are to be found.
 .RE
 .RS 8
 .RE
@@ -260,11 +319,12 @@ Possible values for \fIkey\fR are:
 .PD 0
 .IP "\fBpaper letter\fR" 8
 .IX Item "paper letter"
-.IP "\fB[xdvi|dvips|pdftex|dvipdfm|dvipdfmx] paper [help|papersize]\fR" 8
-.IX Item "[xdvi|dvips|pdftex|dvipdfm|dvipdfmx] paper [help|papersize]"
+.IP "\fB[xdvi|dvips|pdftex|dvipdfm|dvipdfmx|context] paper [help|papersize|\-\-list]\fR" 8
+.IX Item "[xdvi|dvips|pdftex|dvipdfm|dvipdfmx|context] paper [help|papersize|--list]"
 .PD
 Configures the system wide paper settings, either for all programs in
-one go, or just for the specified program.
+one go, or just for the specified program. The last form with \fB\-\-list\fR
+outputs all known papersizes for the specified program.
 .IP "\fBarch list\fR" 8
 .IX Item "arch list"
 Prints the names of the systems available at the default install location.
@@ -320,38 +380,66 @@ Do not ask for confirmation, remove immediately.
 .IP "\fBgenerate language\fR" 8
 .IX Item "generate language"
 .PD 0
+.IP "\fBgenerate language.dat\fR" 8
+.IX Item "generate language.dat"
+.IP "\fBgenerate language.def\fR" 8
+.IX Item "generate language.def"
 .IP "\fBgenerate fmtutil\fR" 8
 .IX Item "generate fmtutil"
 .IP "\fBgenerate updmap\fR" 8
 .IX Item "generate updmap"
 .PD
-\&\fB\s-1WARNING:\s0\fR This action overwrites any user changes made in
-the respective files, by regenerating them from scratch.
+The \fIgenerate\fR action overwrites any manual changes made in the
+respective files: it recreates them from scratch.
+.Sp
+For fmtutil and the language files, this is normal, and both the TeX
+Live installer and \f(CW\*(C`tlmgr\*(C'\fR routinely call \fIgenerate\fR for them.
 .Sp
-This is especially questionable with updmap, because the result will be
-to disable all maps which have been manually installed (via \f(CW\*(C`updmap\-sys
-\&\-\-enable\*(C'\fR), e.g., for proprietary or local fonts.  Be sure that's what
-you want to do.
+For updmap, however, neither the installer nor \f(CW\*(C`tlmgr\*(C'\fR use \fIgenerate\fR,
+because the result would be to disable all maps which have been manually
+installed via \f(CW\*(C`updmap\-sys \-\-enable\*(C'\fR, e.g., for proprietary or local
+fonts.  Only the changes in the \f(CW\*(C`\-\-localcfg\*(C'\fR file mentioned below are
+incorporated by \fIgenerate\fR.
 .Sp
-This action regenerates any of the three config files \f(CW\*(C`language.dat\*(C'\fR,
-\&\f(CW\*(C`fmtutil.cnf\*(C'\fR, and \f(CW\*(C`updmap.cfg\*(C'\fR from the information present in the
-local \s-1TLPDB\s0. If the files \f(CW\*(C`language\-local.dat\*(C'\fR, \f(CW\*(C`fmtutil\-local.cnf\*(C'\fR,
-or \f(CW\*(C`updmap\-local.cfg\*(C'\fR are present under \f(CW\*(C`TEXMFLOCAL\*(C'\fR in the respective
+On the other hand, if you only use the fonts and font packages within
+TeX Live, there is nothing wrong with using \fIgenerate updmap\fR.  Indeed,
+we use it to generate the \f(CW\*(C`updmap.cfg\*(C'\fR file that is maintained in the
+live source repository.
+.Sp
+In more detail: \fIgenerate\fR remakes any of the four config files
+\&\f(CW\*(C`language.dat\*(C'\fR, \f(CW\*(C`language.def\*(C'\fR, \f(CW\*(C`fmtutil.cnf\*(C'\fR, and \f(CW\*(C`updmap.cfg\*(C'\fR from
+the information present in the local \s-1TLPDB\s0. If the files
+\&\f(CW\*(C`language\-local.dat\*(C'\fR, \f(CW\*(C`language\-local.def\*(C'\fR, \f(CW\*(C`fmtutil\-local.cnf\*(C'\fR, or
+\&\f(CW\*(C`updmap\-local.cfg\*(C'\fR are present under \f(CW\*(C`TEXMFLOCAL\*(C'\fR in the respective
 directories, their contents will be simply merged into the final files,
 with no error checking of any kind.
 .Sp
+The form \f(CW\*(C`generate language\*(C'\fR recreates both the \f(CW\*(C`language.dat\*(C'\fR and the
+\&\f(CW\*(C`language.def\*(C'\fR files, while the forms with extension only recreates
+the given file.
+.Sp
 Options:
 .RS 8
 .IP "\fB\-\-dest\fR \fIoutput file\fR" 8
 .IX Item "--dest output file"
 specifies the output file (defaults to the respective location in
-\&\f(CW\*(C`TEXMFSYSVAR\*(C'\fR).
+\&\f(CW\*(C`TEXMFSYSVAR\*(C'\fR).  If \fB\-\-dest\fR is given to \f(CW\*(C`generate language\*(C'\fR, its
+value will be used for the \f(CW\*(C`language.dat\*(C'\fR output, and \f(CW\*(C`.def\*(C'\fR will be
+appended to the value for the name of the \f(CW\*(C`language.def\*(C'\fR output file.
+(This is just to avoid overwriting; if you really want a specific name
+for each output file, we recommend invoking \f(CW\*(C`tlmgr\*(C'\fR twice.)
 .IP "\fB\-\-localcfg\fR \fIlocal conf file\fR" 8
 .IX Item "--localcfg local conf file"
 specifies the (optional) local additions (defaults to the respective
 location in \f(CW\*(C`TEXMFSYSVAR\*(C'\fR).
 .RE
 .RS 8
+.Sp
+The respective locations are as follows:
+  \f(CW\*(C`tex/generic/config/language.dat\*(C'\fR (and \f(CW\*(C`language\-local.dat\*(C'\fR)
+  \f(CW\*(C`tex/generic/config/language.def\*(C'\fR (and \f(CW\*(C`language\-local.def\*(C'\fR)
+  \f(CW\*(C`web2c/fmtutil.cnf\*(C'\fR (and \f(CW\*(C`fmtutil\-local.cnf\*(C'\fR)
+  \f(CW\*(C`web2c/updmap.cfg\*(C'\fR (and \f(CW\*(C`updmap\-local.cnf\*(C'\fR)
 .RE
 .SH "AUTHORS AND COPYRIGHT"
 .IX Header "AUTHORS AND COPYRIGHT"
diff --git a/Master/texmf/doc/man/man1/tlmgr.pdf b/Master/texmf/doc/man/man1/tlmgr.pdf
index 1e2b40c672b..6680bd1cd57 100644
--- a/Master/texmf/doc/man/man1/tlmgr.pdf
+++ b/Master/texmf/doc/man/man1/tlmgr.pdf