summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/man/man1/tlmgr.1
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-04-07 18:26:53 +0000
committerKarl Berry <karl@freefriends.org>2013-04-07 18:26:53 +0000
commitb04c2e1a42573e9735547702356c7b9a769a6855 (patch)
treec0753443f39500a062d7698fe6b94359c813f871 /Master/texmf-dist/doc/man/man1/tlmgr.1
parentfb0bf13304a356f197bfc1add17f98c07e96f17b (diff)
texmf -> texmf-dist: doc
git-svn-id: svn://tug.org/texlive/trunk@29714 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/man/man1/tlmgr.1')
-rw-r--r--Master/texmf-dist/doc/man/man1/tlmgr.11655
1 files changed, 1655 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/man/man1/tlmgr.1 b/Master/texmf-dist/doc/man/man1/tlmgr.1
new file mode 100644
index 00000000000..a30588224e3
--- /dev/null
+++ b/Master/texmf-dist/doc/man/man1/tlmgr.1
@@ -0,0 +1,1655 @@
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.de Ve \" End verbatim text
+.ft R
+.fi
+..
+.\" Set up some character translations and predefined strings. \*(-- will
+.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.ie \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. nr % 0
+. rr F
+.\}
+.el \{\
+. de IX
+..
+.\}
+.\"
+.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "TLMGR 1"
+.TH TLMGR 1 "2013-04-02" "perl v5.16.3" "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
+.nh
+.SH "NAME"
+tlmgr \- the TeX Live Manager
+.SH "SYNOPSIS"
+.IX Header "SYNOPSIS"
+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
+configuration options. For information on initially downloading and
+installing TeX Live, see <http://tug.org/texlive/acquire.html>.
+.PP
+The most up-to-date version of this documentation (updated nightly from
+the development sources) is available at
+<http://tug.org/texlive/tlmgr.html>, along with procedures for updating
+\&\f(CW\*(C`tlmgr\*(C'\fR itself and information about test versions.
+.PP
+TeX Live is organized into a few top-level \fIschemes\fR, each of which is
+specified as a different set of \fIcollections\fR and \fIpackages\fR, where a
+collection is a set of packages, and a package is what contains actual
+files. Schemes typically contain a mix of collections and packages, but
+each package is included in exactly one collection, no more and no less.
+A TeX Live installation can be customized and managed at any level.
+.PP
+See <http://tug.org/texlive/doc> for all the TeX Live documentation
+available.
+.SH "EXAMPLES"
+.IX Header "EXAMPLES"
+After successfully installing TeX Live, here are a few common operations
+with \f(CW\*(C`tlmgr\*(C'\fR:
+.ie n .IP """tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet""" 4
+.el .IP "\f(CWtlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet\fR" 4
+.IX Item "tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet"
+Tell \f(CW\*(C`tlmgr\*(C'\fR to use a nearby \s-1CTAN\s0 mirror for future updates; useful if
+you installed TeX Live from the \s-1DVD\s0 image and want continuing updates.
+.ie n .IP """tlmgr update \-\-list""" 4
+.el .IP "\f(CWtlmgr update \-\-list\fR" 4
+.IX Item "tlmgr update --list"
+Report what would be updated without actually updating anything.
+.ie n .IP """tlmgr update \-\-all""" 4
+.el .IP "\f(CWtlmgr update \-\-all\fR" 4
+.IX Item "tlmgr update --all"
+Make your local TeX installation correspond to what is in the package
+repository (typically useful when updating from \s-1CTAN\s0).
+.ie n .IP """tlmgr info"" \fIpkg\fR" 4
+.el .IP "\f(CWtlmgr info\fR \fIpkg\fR" 4
+.IX Item "tlmgr info pkg"
+Display detailed information about \fIpkg\fR, such as the installation
+status and description.
+.PP
+For all the capabilities and details of \f(CW\*(C`tlmgr\*(C'\fR, please read the
+following voluminous information.
+.SH "OPTIONS"
+.IX Header "OPTIONS"
+The following options to \f(CW\*(C`tlmgr\*(C'\fR are global options, not specific to
+any action. All options, whether global or action-specific, can be
+given anywhere on the command line, and in any order. The first
+non-option argument will be the main action. In all cases,
+\&\f(CW\*(C`\-\-\*(C'\fR\fIoption\fR and \f(CW\*(C`\-\*(C'\fR\fIoption\fR are equivalent, and an \f(CW\*(C`=\*(C'\fR is optional
+between an option name and its value.
+.IP "\fB\-\-repository\fR \fIurl|path\fR" 4
+.IX Item "--repository url|path"
+Specifies the package repository from which packages should be installed
+or updated, overriding the default package repository found in the
+installation's TeX Live Package Database (a.k.a. the \s-1TLPDB\s0, defined
+entirely in the file \f(CW\*(C`tlpkg/texlive.tlpdb\*(C'\fR). The documentation for
+\&\f(CW\*(C`install\-tl\*(C'\fR has more details about this
+(http://tug.org/texlive/doc/install\-tl.html <http://tug.org/texlive/doc/install-tl.html>).
+.Sp
+\&\f(CW\*(C`\-\-repository\*(C'\fR changes the repository location only for the current
+run; to make a permanent change, use \f(CW\*(C`option repository\*(C'\fR (see the
+option action).
+.Sp
+For backward compatibility and convenience, \f(CW\*(C`\-\-location\*(C'\fR and \f(CW\*(C`\-\-repo\*(C'\fR
+are accepted as aliases for this option.
+.IP "\fB\-\-gui\fR [\fIaction\fR]" 4
+.IX Item "--gui [action]"
+\&\f(CW\*(C`tlmgr\*(C'\fR has a graphical interface as well as the command-line
+interface. You can give this option, \f(CW\*(C`\-\-gui\*(C'\fR, together with an action
+to be brought directly into the respective screen of the \s-1GUI\s0. For
+example, running
+.Sp
+.Vb 1
+\& tlmgr \-\-gui update
+.Ve
+.Sp
+starts you directly at the update screen. Without any action, the
+\&\s-1GUI\s0 will be started at the main screen.
+.IP "\fB\-\-gui\-lang\fR \fIllcode\fR" 4
+.IX Item "--gui-lang llcode"
+By default, the \s-1GUI\s0 tries to deduce your language from the environment
+(on Windows via the registry, on Unix via \f(CW\*(C`LC_MESSAGES\*(C'\fR). If that fails
+you can select a different language by giving this option with a
+language code (based on \s-1ISO\s0 639\-1). Currently supported (but not
+necessarily completely translated) are: English (en, default), Czech
+(cs), German (de), French (fr), Italian (it), Japanese (ja), Dutch (nl),
+Polish (pl), Brazilian Portuguese (pt_BR), Russian (ru), Slovak (sk),
+Slovenian (sl), Serbian (sr), Vietnamese (vi), simplified Chinese
+(zh_CN), and traditional Chinese (zh_TW).
+.IP "\fB\-\-machine\-readable\fR" 4
+.IX Item "--machine-readable"
+Instead of the normal output intended for human consumption, write (to
+standard output) a fixed format more suitable for machine parsing. See
+the \*(L"MACHINE-READABLE \s-1OUTPUT\s0\*(R" section below.
+.IP "\fB\-\-package\-logfile\fR \fIfile\fR" 4
+.IX Item "--package-logfile file"
+\&\f(CW\*(C`tlmgr\*(C'\fR logs all package actions (install, remove, update, failed
+updates, failed restores) to a separate log file, by default
+\&\f(CW\*(C`TEXMFSYSVAR/web2c/tlmgr.log\*(C'\fR. This option allows you to specific a
+different file for the log.
+.IP "\fB\-\-pause\fR" 4
+.IX Item "--pause"
+This option makes \f(CW\*(C`tlmgr\*(C'\fR wait for user input before exiting. Useful on
+Windows to avoid disappearing command windows.
+.IP "\fB\-\-persistent\-downloads\fR" 4
+.IX Item "--persistent-downloads"
+.PD 0
+.IP "\fB\-\-no\-persistent\-downloads\fR" 4
+.IX Item "--no-persistent-downloads"
+.PD
+For network-based installations, this option (on by default) makes
+\&\f(CW\*(C`tlmgr\*(C'\fR try to set up a persistent connection (using the Net::LWP
+Perl module). The idea is to open and reuse only one connection per
+session between your computer and the server, instead of initiating a
+new download for each package.
+.Sp
+If this is not possible, \f(CW\*(C`tlmgr\*(C'\fR will fall back to using \f(CW\*(C`wget\*(C'\fR. To
+disable these persistent connections, use \f(CW\*(C`\-\-no\-persistent\-downloads\*(C'\fR.
+.IP "\fB\-\-no\-execute\-actions\fR" 4
+.IX Item "--no-execute-actions"
+Suppress the execution of the execute actions as defined in the tlpsrc
+files. Documented only for completeness, as this is only useful in
+debugging.
+.IP "\fB\-\-debug\-translation\fR" 4
+.IX Item "--debug-translation"
+In \s-1GUI\s0 mode, this switch makes \f(CW\*(C`tlmgr\*(C'\fR report any missing, or more
+likely untranslated, messages to standard error. This can help
+translators to see what remains to be done.
+.PP
+The standard options for TeX Live programs are also accepted:
+\&\f(CW\*(C`\-\-help/\-h/\-?\*(C'\fR, \f(CW\*(C`\-\-version\*(C'\fR, \f(CW\*(C`\-q\*(C'\fR (no informational messages), \f(CW\*(C`\-v\*(C'\fR
+(debugging messages, can be repeated). For the details about these, see
+the TeXLive::TLUtils documentation.
+.PP
+The \f(CW\*(C`\-\-version\*(C'\fR option shows version information about the TeX Live
+release and about the \f(CW\*(C`tlmgr\*(C'\fR script itself. If \f(CW\*(C`\-v\*(C'\fR is given as
+well, revision number for the used TeX Live Perl modules are shown, too.
+.SH "ACTIONS"
+.IX Header "ACTIONS"
+.SS "help"
+.IX Subsection "help"
+Gives this help information (same as \f(CW\*(C`\-\-help\*(C'\fR).
+.SS "version"
+.IX Subsection "version"
+Gives version information (same as \f(CW\*(C`\-\-version\*(C'\fR).
+.PP
+If \f(CW\*(C`\-v\*(C'\fR has been given the revisions of the used modules are reported, too.
+.SS "backup [\-\-clean[=\fIN\fP]] [\-\-backupdir \fIdir\fP] [\-\-all | \fIpkg\fP]..."
+.IX Subsection "backup [--clean[=N]] [--backupdir dir] [--all | pkg]..."
+If the \f(CW\*(C`\-\-clean\*(C'\fR option is not specified, this action makes a backup of
+the given packages, or all packages given \f(CW\*(C`\-\-all\*(C'\fR. These backups are
+saved to the value of the \f(CW\*(C`\-\-backupdir\*(C'\fR option, if that is an existing and
+writable directory. If \f(CW\*(C`\-\-backupdir\*(C'\fR is not given, the \f(CW\*(C`backupdir\*(C'\fR
+option setting in the \s-1TLPDB\s0 is used, if present. If both are missing,
+no backups are made.
+.PP
+If the \f(CW\*(C`\-\-clean\*(C'\fR option is specified, backups are pruned (removed)
+instead of saved. The optional integer value \fIN\fR may be specified to
+set the number of backups that will be retained when cleaning. If \f(CW\*(C`N\*(C'\fR
+is not given, the value of the \f(CW\*(C`autobackup\*(C'\fR option is used. If both are
+missing, an error is issued. For more details of backup pruning, see
+the \f(CW\*(C`option\*(C'\fR action.
+.PP
+Options:
+.IP "\fB\-\-backupdir\fR \fIdirectory\fR" 4
+.IX Item "--backupdir directory"
+Overrides the \f(CW\*(C`backupdir\*(C'\fR option setting in the \s-1TLPDB\s0.
+The \fIdirectory\fR argument is required and must specify an existing,
+writable directory where backups are to be placed.
+.IP "\fB\-\-all\fR" 4
+.IX Item "--all"
+If \f(CW\*(C`\-\-clean\*(C'\fR is not specified, make a backup of all packages in the TeX
+Live installation; this will take quite a lot of space and time. If
+\&\f(CW\*(C`\-\-clean\*(C'\fR is specified, all packages are pruned.
+.IP "\fB\-\-clean\fR[=\fIN\fR]" 4
+.IX Item "--clean[=N]"
+Instead of making backups, prune the backup directory of old backups, as
+explained above. The optional integer argument \fIN\fR overrides the
+\&\f(CW\*(C`autobackup\*(C'\fR option set in the \s-1TLPDB\s0. You must use \f(CW\*(C`\-\-all\*(C'\fR or a list
+of packages together with this option, as desired.
+.IP "\fB\-\-dry\-run\fR" 4
+.IX Item "--dry-run"
+Nothing is actually backed up or removed; instead, the actions to be
+performed are written to the terminal.
+.SS "candidates"
+.IX Subsection "candidates"
+.IP "\fBcandidates \f(BIpkg\fB\fR" 4
+.IX Item "candidates pkg"
+Shows the available candidate repositories for package \fIpkg\fR.
+See \*(L"\s-1MULTIPLE\s0 \s-1REPOSITORIES\s0\*(R" below.
+.SS "check [\fIoption\fP]... [files|depends|executes|runfiles|all]"
+.IX Subsection "check [option]... [files|depends|executes|runfiles|all]"
+Executes one (or all) check(s) on the consistency of the installation.
+.IP "\fBfiles\fR" 4
+.IX Item "files"
+Checks that all files listed in the local \s-1TLPDB\s0 (\f(CW\*(C`texlive.tlpdb\*(C'\fR) are
+actually present, and lists those missing.
+.IP "\fBdepends\fR" 4
+.IX Item "depends"
+Lists those packages which occur as dependencies in an installed collections,
+but are themselves not installed, and those packages that are not
+contained in any collection.
+.Sp
+If you call \f(CW\*(C`tlmgr check collections\*(C'\fR this test will be carried out
+instead since former versions for \f(CW\*(C`tlmgr\*(C'\fR called it that way.
+.IP "\fBexecutes\fR" 4
+.IX Item "executes"
+Check that the files referred to by \f(CW\*(C`execute\*(C'\fR directives in the TeX
+Live Database are present.
+.IP "\fBrunfiles\fR" 4
+.IX Item "runfiles"
+List those filenames that are occurring more than one time in the runfiles.
+.PP
+Options:
+.IP "\fB\-\-use\-svn\fR" 4
+.IX Item "--use-svn"
+Use the output of \f(CW\*(C`svn status\*(C'\fR instead of listing the files; for
+checking the \s-1TL\s0 development repository.
+.SS "conf [texmf|tlmgr [\fIkey\fP [\fIvalue\fP]]]"
+.IX Subsection "conf [texmf|tlmgr [key [value]]]"
+With only \f(CW\*(C`conf\*(C'\fR, show general configuration information for TeX Live,
+including active configuration files, path settings, and more. This is
+like the \f(CW\*(C`texconfig conf\*(C'\fR call, but works on all supported platforms.
+.PP
+With either \f(CW\*(C`conf texmf\*(C'\fR or \f(CW\*(C`conf tlmgr\*(C'\fR given in addition, shows all
+key/value pairs (i.e., all settings) as saved in \f(CW\*(C`ROOT/texmf.cnf\*(C'\fR or
+the tlmgr configuration file (see below), respectively.
+.PP
+If \fIkey\fR is given in addition, shows the value of only that given
+\&\fIkey\fR in the respective file.
+.PP
+If \fIvalue\fR is given in addition, \fIkey\fR is set to \fIvalue\fR in the
+respective file. \fINo error checking is done!\fR
+.PP
+Practical application: if the execution of (some or all) system commands
+via \f(CW\*(C`\ewrite18\*(C'\fR was left enabled during installation, you can disable
+it afterwards:
+.PP
+.Vb 1
+\& tlmgr conf texmf shell_escape 0
+.Ve
+.PP
+Warning: The general facility is here, but tinkering with settings in
+this way is very strongly discouraged. Again, no error checking is
+done, so any sort of breakage is possible.
+.SS "dump-tlpdb [\-\-local|\-\-remote]"
+.IX Subsection "dump-tlpdb [--local|--remote]"
+Dump complete local or remote \s-1TLPDB\s0 to standard output, as-is. The
+output is analogous to the \f(CW\*(C`\-\-machine\-readable\*(C'\fR output; see
+\&\*(L"MACHINE-READABLE \s-1OUTPUT\s0\*(R" section.
+.PP
+Options:
+.IP "\fB\-\-local\fR" 4
+.IX Item "--local"
+Dump the local tlpdb.
+.IP "\fB\-\-remote\fR" 4
+.IX Item "--remote"
+Dump the remote tlpdb.
+.PP
+Exactly one of \f(CW\*(C`\-\-local\*(C'\fR and \f(CW\*(C`\-\-remote\*(C'\fR must be given.
+.PP
+In either case, the first line of the output specifies the repository
+location, in this format:
+.PP
+.Vb 1
+\& "location\-url" "\et" location
+.Ve
+.PP
+where \f(CW\*(C`location\-url\*(C'\fR is the literal field name, followed by a tab, and
+\&\fIlocation\fR is the file or url to the repository.
+.PP
+Line endings may be either \s-1LF\s0 or \s-1CRLF\s0 depending on the current platform.
+.SS "generate [\fIoption\fP]... \fIwhat\fP"
+.IX Subsection "generate [option]... what"
+.IP "\fBgenerate language\fR" 4
+.IX Item "generate language"
+.PD 0
+.IP "\fBgenerate language.dat\fR" 4
+.IX Item "generate language.dat"
+.IP "\fBgenerate language.def\fR" 4
+.IX Item "generate language.def"
+.IP "\fBgenerate language.dat.lua\fR" 4
+.IX Item "generate language.dat.lua"
+.IP "\fBgenerate fmtutil\fR" 4
+.IX Item "generate fmtutil"
+.PD
+.PP
+The \f(CW\*(C`generate\*(C'\fR action overwrites any manual changes made in the
+respective files: it recreates them from scratch based on the
+information of the installed packages, plus local adaptions.
+The TeX Live installer and \f(CW\*(C`tlmgr\*(C'\fR routinely call \f(CW\*(C`generate\*(C'\fR for
+all of these files.
+.PP
+For managing your own fonts, please read the \f(CW\*(C`updmap \-\-help\*(C'\fR
+information and/or <http://tug.org/fonts/fontinstall.html>.
+.PP
+In more detail: \f(CW\*(C`generate\*(C'\fR remakes any of the configuration files
+\&\f(CW\*(C`language.dat\*(C'\fR, \f(CW\*(C`language.def\*(C'\fR, \f(CW\*(C`language.dat.lua\*(C'\fR, and
+\&\f(CW\*(C`fmtutil.cnf\*(C'\fR, from the information present in the local \s-1TLPDB\s0, plus
+locally-maintained files.
+.PP
+The locally-maintained files are \f(CW\*(C`language\-local.dat\*(C'\fR,
+\&\f(CW\*(C`language\-local.def\*(C'\fR, \f(CW\*(C`language\-local.dat.lua\*(C'\fR, or
+\&\f(CW\*(C`fmtutil\-local.cnf\*(C'\fR, searched for in \f(CW\*(C`TEXMFLOCAL\*(C'\fR in the respective
+directories. If local additions are present, the final file is made by
+starting with the main file, omitting any entries that the local file
+specifies to be disabled, and finally appending the local file.
+.PP
+(Historical note: The formerly supported \f(CW\*(C`updmap\-local.cfg\*(C'\fR is no longer
+read, since \f(CW\*(C`updmap\*(C'\fR now supports multiple \f(CW\*(C`updmap.cfg\*(C'\fR files. Thus,
+local additions can and should be put into an \f(CW\*(C`updmap.cfg\*(C'\fR file in
+\&\f(CW\*(C`TEXMFLOCAL\*(C'\fR. The \f(CW\*(C`generate updmap\*(C'\fR action no longer exists.)
+.PP
+Local files specify entries to be disabled with a comment line, namely
+one of these:
+.PP
+.Vb 3
+\& #!NAME
+\& %!NAME
+\& \-\-!NAME
+.Ve
+.PP
+where \f(CW\*(C`fmtutil.cnf\*(C'\fR uses \f(CW\*(C`#\*(C'\fR, \f(CW\*(C`language.dat\*(C'\fR and \f(CW\*(C`language.def\*(C'\fR use
+\&\f(CW\*(C`%\*(C'\fR, and \f(CW\*(C`language.dat.lua\*(C'\fR use \f(CW\*(C`\-\-\*(C'\fR. In all cases, the \fIname\fR is
+the respective format name or hyphenation pattern identifier.
+Examples:
+.PP
+.Vb 3
+\& #!pdflatex
+\& %!german
+\& \-\-!usenglishmax
+.Ve
+.PP
+(Of course, you're not likely to actually want to disable those
+particular items. They're just examples.)
+.PP
+After such a disabling line, the local file can include another entry
+for the same item, if a different definition is desired. In general,
+except for the special disabling lines, the local files follow the same
+syntax as the master files.
+.PP
+The form \f(CW\*(C`generate language\*(C'\fR recreates all three files \f(CW\*(C`language.dat\*(C'\fR,
+\&\f(CW\*(C`language.def\*(C'\fR, and \f(CW\*(C`language.dat.lua\*(C'\fR, while the forms with an
+extension recreates only that given language file.
+.PP
+Options:
+.IP "\fB\-\-dest\fR \fIoutput_file\fR" 4
+.IX Item "--dest output_file"
+specifies the output file (defaults to the respective location in
+\&\f(CW\*(C`TEXMFSYSVAR\*(C'\fR). If \f(CW\*(C`\-\-dest\*(C'\fR is given to \f(CW\*(C`generate language\*(C'\fR, it
+serves as a basename onto which \f(CW\*(C`.dat\*(C'\fR will be appended for the name of
+the \f(CW\*(C`language.dat\*(C'\fR output file, \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, and \f(CW\*(C`.dat.lua\*(C'\fR to the
+name of the \f(CW\*(C`language.dat.lua\*(C'\fR file. (This is just to avoid
+overwriting; if you 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" 4
+.IX Item "--localcfg local_conf_file"
+specifies the (optional) local additions (defaults to the respective
+location in \f(CW\*(C`TEXMFLOCAL\*(C'\fR).
+.IP "\fB\-\-rebuild\-sys\fR" 4
+.IX Item "--rebuild-sys"
+tells tlmgr to run necessary programs after config files have been
+regenerated. These are:
+\&\f(CW\*(C`fmtutil\-sys \-\-all\*(C'\fR after \f(CW\*(C`generate fmtutil\*(C'\fR,
+\&\f(CW\*(C`fmtutil\-sys \-\-byhyphen .../language.dat\*(C'\fR after \f(CW\*(C`generate language.dat\*(C'\fR,
+and
+\&\f(CW\*(C`fmtutil\-sys \-\-byhyphen .../language.def\*(C'\fR after \f(CW\*(C`generate language.def\*(C'\fR.
+.Sp
+These subsequent calls cause the newly-generated files to actually take
+effect. This is not done by default since those calls are lengthy
+processes and one might want to made several related changes in
+succession before invoking these programs.
+.PP
+The respective locations are as follows:
+.PP
+.Vb 4
+\& tex/generic/config/language.dat (and language\-local.dat);
+\& tex/generic/config/language.def (and language\-local.def);
+\& tex/generic/config/language.dat.lua (and language\-local.dat.lua);
+\& web2c/fmtutil.cnf (and fmtutil\-local.cnf);
+.Ve
+.SS "gui"
+.IX Subsection "gui"
+Start the graphical user interface. See \fB\s-1GUI\s0\fR below.
+.SS "info [\fIoption\fP...] [collections|schemes|\fIpkg\fP...]"
+.IX Subsection "info [option...] [collections|schemes|pkg...]"
+With no argument, lists all packages available at the package
+repository, prefixing those already installed with \f(CW\*(C`i\*(C'\fR.
+.PP
+With the single word \f(CW\*(C`collections\*(C'\fR or \f(CW\*(C`schemes\*(C'\fR as the argument, lists
+the request type instead of all packages.
+.PP
+With any other arguments, display information about \fIpkg\fR: the name,
+category, short and long description, installation status, and TeX Live
+revision number. If \fIpkg\fR is not locally installed, searches in the
+remote installation source.
+.PP
+It also displays information taken from the TeX Catalogue, namely the
+package version, date, and license. Consider these, especially the
+package version, as approximations only, due to timing skew of the
+updates of the different pieces. By contrast, the \f(CW\*(C`revision\*(C'\fR value
+comes directly from \s-1TL\s0 and is reliable.
+.PP
+The former actions \f(CW\*(C`show\*(C'\fR and \f(CW\*(C`list\*(C'\fR are merged into this action,
+but are still supported for backward compatibility.
+.PP
+Options:
+.IP "\fB\-\-list\fR" 4
+.IX Item "--list"
+If the option \f(CW\*(C`\-\-list\*(C'\fR is given with a package, the list of contained
+files is also shown, including those for platform-specific dependencies.
+When given with schemes and collections, \f(CW\*(C`\-\-list\*(C'\fR outputs their
+dependencies in a similar way.
+.IP "\fB\-\-only\-installed\fR" 4
+.IX Item "--only-installed"
+If this options is given, the installation source will
+not be used; only locally installed packages, collections, or schemes
+are listed.
+(Does not work for listing of packages for now)
+.IP "\fB\-\-taxonomy\fR" 4
+.IX Item "--taxonomy"
+.PD 0
+.IP "\fB\-\-keyword\fR" 4
+.IX Item "--keyword"
+.IP "\fB\-\-functionality\fR" 4
+.IX Item "--functionality"
+.IP "\fB\-\-characterization\fR" 4
+.IX Item "--characterization"
+.PD
+In addition to the normal data displayed, also display information for
+given packages from the corresponding taxonomy (or all of them). See
+\&\*(L"\s-1TAXONOMIES\s0\*(R" below for details.
+.SS "install [\fIoption\fP]... \fIpkg\fP..."
+.IX Subsection "install [option]... pkg..."
+Install each \fIpkg\fR given on the command line. By default this installs
+all packages on which the given \fIpkg\fRs are dependent, also. Options:
+.IP "\fB\-\-file\fR" 4
+.IX Item "--file"
+Instead of fetching a package from the installation repository, use
+the packages files given on the command line. These files need
+to be proper TeX Live package files (with contained tlpobj file).
+.IP "\fB\-\-reinstall\fR" 4
+.IX Item "--reinstall"
+Reinstall a package (including dependencies for collections) even if it
+seems to be already installed (i.e, is present in the \s-1TLPDB\s0). This is
+useful to recover from accidental removal of files in the hierarchy.
+.Sp
+When re-installing, only dependencies on normal packages are followed
+(not those of category Scheme or Collection).
+.IP "\fB\-\-no\-depends\fR" 4
+.IX Item "--no-depends"
+Do not install dependencies. (By default, installing a package ensures
+that all dependencies of this package are fulfilled.)
+.IP "\fB\-\-no\-depends\-at\-all\fR" 4
+.IX Item "--no-depends-at-all"
+When you install a package which ships binary files the respective
+binary package will also be installed. That is, for a package \f(CW\*(C`foo\*(C'\fR,
+the package \f(CW\*(C`foo.i386\-linux\*(C'\fR will also be installed on an \f(CW\*(C`i386\-linux\*(C'\fR
+system. This switch suppresses this behavior, and also implies
+\&\f(CW\*(C`\-\-no\-depends\*(C'\fR. Don't use it unless you are sure of what you are
+doing.
+.IP "\fB\-\-dry\-run\fR" 4
+.IX Item "--dry-run"
+Nothing is actually installed; instead, the actions to be performed are
+written to the terminal.
+.IP "\fB\-\-force\fR" 4
+.IX Item "--force"
+If updates to \f(CW\*(C`tlmgr\*(C'\fR itself (or other parts of the basic
+infrastructure) are present, \f(CW\*(C`tlmgr\*(C'\fR will bail out and not perform the
+installation unless this option is given. Not recommended.
+.SS "option"
+.IX Subsection "option"
+.IP "\fBoption [show]\fR" 4
+.IX Item "option [show]"
+.PD 0
+.IP "\fBoption showall\fR" 4
+.IX Item "option showall"
+.IP "\fBoption \f(BIkey\fB [\f(BIvalue\fB]\fR" 4
+.IX Item "option key [value]"
+.PD
+.PP
+The first form shows the global TeX Live settings currently saved in the
+\&\s-1TLPDB\s0 with a short description and the \f(CW\*(C`key\*(C'\fR used for changing it in
+parentheses.
+.PP
+The second form is similar, but also shows options which can be defined
+but are not currently set to any value.
+.PP
+In the third form, if \fIvalue\fR is not given, the setting for \fIkey\fR is
+displayed. If \fIvalue\fR is present, \fIkey\fR is set to \fIvalue\fR.
+.PP
+Possible values for \fIkey\fR are (run \f(CW\*(C`tlmgr option showall\*(C'\fR for
+the definitive list):
+.PP
+.Vb 10
+\& repository (default package repository),
+\& formats (create formats at installation time),
+\& postcode (run postinst code blobs)
+\& docfiles (install documentation files),
+\& srcfiles (install source files),
+\& backupdir (default directory for backups),
+\& autobackup (number of backups to keep).
+\& sys_bin (directory to which executables are linked by the path action)
+\& sys_man (directory to which man pages are linked by the path action)
+\& sys_info (directory to which Info files are linked by the path action)
+\& desktop_integration (Windows\-only: create Start menu shortcuts)
+\& fileassocs (Windows\-only: change file associations)
+\& multiuser (Windows\-only: install for all users)
+.Ve
+.PP
+One common use of \f(CW\*(C`option\*(C'\fR is to permanently change the installation to
+get further updates from the Internet, after originally installing from
+\&\s-1DVD\s0. To do this, you can run
+.PP
+.Vb 1
+\& tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet
+.Ve
+.PP
+The \f(CW\*(C`install\-tl\*(C'\fR documentation has more information about the possible
+values for \f(CW\*(C`repository\*(C'\fR. (For backward compatibility, \f(CW\*(C`location\*(C'\fR can
+be used as alternative name for \f(CW\*(C`repository\*(C'\fR.)
+.PP
+If \f(CW\*(C`formats\*(C'\fR is set (this is the default), then formats are regenerated
+when either the engine or the format files have changed. Disable this
+only when you know what you are doing.
+.PP
+The \f(CW\*(C`postcode\*(C'\fR option controls execution of per-package
+postinstallation action code. It is set by default, and again disabling
+is not likely to be of interest except perhaps to developers.
+.PP
+The \f(CW\*(C`docfiles\*(C'\fR and \f(CW\*(C`srcfiles\*(C'\fR options control the installation of
+their respective files of a package. By default both are enabled (1).
+This can be disabled (set to 0) if disk space is (very) limited.
+.PP
+The options \f(CW\*(C`autobackup\*(C'\fR and \f(CW\*(C`backupdir\*(C'\fR determine the defaults for
+the actions \f(CW\*(C`update\*(C'\fR, \f(CW\*(C`backup\*(C'\fR and \f(CW\*(C`restore\*(C'\fR. These three actions
+need a directory in which to read or write the backups. If
+\&\f(CW\*(C`\-\-backupdir\*(C'\fR is not specified on the command line, the \f(CW\*(C`backupdir\*(C'\fR
+option value is used (if set).
+.PP
+The \f(CW\*(C`autobackup\*(C'\fR option (de)activates automatic generation of backups.
+Its value is an integer. If the \f(CW\*(C`autobackup\*(C'\fR value is \f(CW\*(C`\-1\*(C'\fR, no
+backups are removed. If \f(CW\*(C`autobackup\*(C'\fR is 0 or more, it specifies the
+number of backups to keep. Thus, backups are disabled if the value is
+0. In the \f(CW\*(C`\-\-clean\*(C'\fR mode of the \f(CW\*(C`backup\*(C'\fR action this option also
+specifies the number to be kept.
+.PP
+To setup \f(CW\*(C`autobackup\*(C'\fR to \f(CW\*(C`\-1\*(C'\fR on the command line, use either:
+.PP
+.Vb 1
+\& tlmgr option autobackup infty
+.Ve
+.PP
+or:
+.PP
+.Vb 1
+\& tlmgr option \-\- autobackup \-1
+.Ve
+.PP
+The \f(CW\*(C`\-\-\*(C'\fR avoids having the \f(CW\*(C`\-1\*(C'\fR treated as an option. (\f(CW\*(C`\-\-\*(C'\fR stops
+parsing for options at the point where it appears; this is a general
+feature across most Unix programs.)
+.PP
+The \f(CW\*(C`sys_bin\*(C'\fR, \f(CW\*(C`sys_man\*(C'\fR, and \f(CW\*(C`sys_info\*(C'\fR options are used on
+Unix-like systems to control the generation of links for executables,
+info files and man pages. See the \f(CW\*(C`path\*(C'\fR action for details.
+.PP
+The last three options control behaviour on Windows installations. If
+\&\f(CW\*(C`desktop_integration\*(C'\fR is set, then some packages will install items in
+a sub-folder of the Start menu for \f(CW\*(C`tlmgr gui\*(C'\fR, documentation, etc. If
+\&\f(CW\*(C`fileassocs\*(C'\fR is set, Windows file associations are made (see also the
+\&\f(CW\*(C`postaction\*(C'\fR action). Finally, if \f(CW\*(C`multiuser\*(C'\fR is set, then adaptions
+to the registry and the menus are done for all users on the system
+instead of only the current user. All three options are on by default.
+.SS "paper"
+.IX Subsection "paper"
+.IP "\fBpaper [a4|letter]\fR" 4
+.IX Item "paper [a4|letter]"
+.PD 0
+.IP "\fB[xdvi|pdftex|dvips|dvipdfmx|dvipdfm|context]\ paper\ [\f(BIpapersize\fB|\-\-list]\fR" 4
+.IX Item "[xdvi|pdftex|dvips|dvipdfmx|dvipdfm|context]paper[papersize|--list]"
+.PD
+.PP
+With no arguments (\f(CW\*(C`tlmgr paper\*(C'\fR), shows the default paper size setting
+for all known programs.
+.PP
+With one argument (e.g., \f(CW\*(C`tlmgr paper a4\*(C'\fR), sets the default for all
+known programs to that paper size.
+.PP
+With a program given as the first argument and no paper size specified
+(e.g., \f(CW\*(C`tlmgr dvips paper\*(C'\fR), shows the default paper size for that
+program.
+.PP
+With a program given as the first argument and a paper size as the last
+argument (e.g., \f(CW\*(C`tlmgr dvips paper a4\*(C'\fR), set the default for that
+program to that paper size.
+.PP
+With a program given as the first argument and \f(CW\*(C`\-\-list\*(C'\fR given as the
+last argument (e.g., \f(CW\*(C`tlmgr dvips paper \-\-list\*(C'\fR), shows all valid paper
+sizes for that program. The first size shown is the default.
+.PP
+Incidentally, this syntax of having a specific program name before the
+\&\f(CW\*(C`paper\*(C'\fR keyword may seem strange. It is inherited from the
+longstanding \f(CW\*(C`texconfig\*(C'\fR script, which supports other configuration
+settings for some programs, notably \f(CW\*(C`dvips\*(C'\fR. \f(CW\*(C`tlmgr\*(C'\fR does not support
+those extra settings at present.
+.SS "path [\-\-w32mode=user|admin] [add|remove]"
+.IX Subsection "path [--w32mode=user|admin] [add|remove]"
+On Unix, merely adds or removes symlinks for binaries, man pages, and
+info pages in the system directories specified by the respective options
+(see the option description above). Does not change any
+initialization files, either system or personal.
+.PP
+On Windows, the registry part where the binary directory is added or
+removed is determined in the following way:
+.PP
+If the user has admin rights, and the option \f(CW\*(C`\-\-w32mode\*(C'\fR is not given,
+the setting \fIw32_multi_user\fR determines the location (i.e., if it is
+on then the system path, otherwise the user path is changed).
+.PP
+If the user has admin rights, and the option \f(CW\*(C`\-\-w32mode\*(C'\fR is given, this
+option determines the path to be adjusted.
+.PP
+If the user does not have admin rights, and the option \f(CW\*(C`\-\-w32mode\*(C'\fR
+is not given, and the setting \fIw32_multi_user\fR is off, the user path
+is changed, while if the setting \fIw32_multi_user\fR is on, a warning is
+issued that the caller does not have enough privileges.
+.PP
+If the user does not have admin rights, and the option \f(CW\*(C`\-\-w32mode\*(C'\fR
+is given, it must be \fBuser\fR and the user path will be adjusted. If a
+user without admin rights uses the option \f(CW\*(C`\-\-w32mode admin\*(C'\fR a warning
+is issued that the caller does not have enough privileges.
+.SS "pinning"
+.IX Subsection "pinning"
+The \f(CW\*(C`pinning\*(C'\fR action manages the pinning file, see Pinning below.
+.ie n .IP """pinning show""" 4
+.el .IP "\f(CWpinning show\fR" 4
+.IX Item "pinning show"
+Shows the current pinning data.
+.ie n .IP """pinning add \f(CIrepo\f(CW \f(CIpkgglob\f(CW...""" 4
+.el .IP "\f(CWpinning add \f(CIrepo\f(CW \f(CIpkgglob\f(CW...\fR" 4
+.IX Item "pinning add repo pkgglob..."
+Pins the packages matching the \fIpkgglob\fR(s) to the repository
+\&\fIrepo\fR.
+.ie n .IP """pinning remove \f(CIrepo\f(CW \f(CIpkgglob\f(CW...""" 4
+.el .IP "\f(CWpinning remove \f(CIrepo\f(CW \f(CIpkgglob\f(CW...\fR" 4
+.IX Item "pinning remove repo pkgglob..."
+Any packages recorded in the pinning file matching the <pkgglob>s for
+the given repository \fIrepo\fR are removed.
+.ie n .IP """pinning remove \f(CIrepo\f(CW \-\-all""" 4
+.el .IP "\f(CWpinning remove \f(CIrepo\f(CW \-\-all\fR" 4
+.IX Item "pinning remove repo --all"
+Remove all pinning data for repository \fIrepo\fR.
+.SS "platform list|add|remove \fIplatform\fP..."
+.IX Subsection "platform list|add|remove platform..."
+.SS "platform set \fIplatform\fP"
+.IX Subsection "platform set platform"
+.SS "platform set auto"
+.IX Subsection "platform set auto"
+\&\f(CW\*(C`platform list\*(C'\fR lists the TeX Live names of all the platforms
+(a.k.a. architectures), (\f(CW\*(C`i386\-linux\*(C'\fR, ...) available at the package
+repository.
+.PP
+\&\f(CW\*(C`platform add\*(C'\fR \fIplatform\fR... adds the executables for each given platform
+\&\fIplatform\fR to the installation from the repository.
+.PP
+\&\f(CW\*(C`platform remove\*(C'\fR \fIplatform\fR... removes the executables for each given
+platform \fIplatform\fR from the installation, but keeps the currently
+running platform in any case.
+.PP
+\&\f(CW\*(C`platform set\*(C'\fR \fIplatform\fR switches TeX Live to always use the given
+platform instead of auto detection.
+.PP
+\&\f(CW\*(C`platform set auto\*(C'\fR switches TeX Live to auto detection mode for platform.
+.PP
+Platform detection is needed to select the proper \f(CW\*(C`xz\*(C'\fR, \f(CW\*(C`xzdec\*(C'\fR and
+\&\f(CW\*(C`wget\*(C'\fR binaries that are shipped with TeX Live.
+.PP
+\&\f(CW\*(C`arch\*(C'\fR is a synonym for \f(CW\*(C`platform\*(C'\fR.
+.PP
+Options:
+.IP "\fB\-\-dry\-run\fR" 4
+.IX Item "--dry-run"
+Nothing is actually installed; instead, the actions to be performed are
+written to the terminal.
+.SS "postaction [\-\-w32mode=user|admin] [\-\-fileassocmode=1|2] [\-\-all] [install|remove] [shortcut|fileassoc|script] [\fIpkg\fP]..."
+.IX Subsection "postaction [--w32mode=user|admin] [--fileassocmode=1|2] [--all] [install|remove] [shortcut|fileassoc|script] [pkg]..."
+Carry out the postaction \f(CW\*(C`shortcut\*(C'\fR, \f(CW\*(C`fileassoc\*(C'\fR, or \f(CW\*(C`script\*(C'\fR given
+as the second required argument in install or remove mode (which is the
+first required argument), for either the packages given on the command
+line, or for all if \f(CW\*(C`\-\-all\*(C'\fR is given.
+.PP
+If the option \f(CW\*(C`\-\-w32mode\*(C'\fR is given the value \f(CW\*(C`user\*(C'\fR, all actions will
+only be carried out in the user-accessible parts of the
+registry/filesystem, while the value \f(CW\*(C`admin\*(C'\fR selects the system-wide
+parts of the registry for the file associations. If you do not have
+enough permissions, using \f(CW\*(C`\-\-w32mode=admin\*(C'\fR will not succeed.
+.PP
+\&\f(CW\*(C`\-\-fileassocmode\*(C'\fR specifies the action for file associations. If it is
+set to 1 (the default), only new associations are added; if it is set to
+2, all associations are set to the TeX Live programs. (See also
+\&\f(CW\*(C`option fileassocs\*(C'\fR.)
+.SS "print-platform"
+.IX Subsection "print-platform"
+Print the TeX Live identifier for the detected platform
+(hardware/operating system) combination to standard output, and exit.
+\&\f(CW\*(C`\-\-print\-arch\*(C'\fR is a synonym.
+.SS "restore [\-\-backupdir \fIdir\fP] [\-\-all | \fIpkg\fP [\fIrev\fP]]"
+.IX Subsection "restore [--backupdir dir] [--all | pkg [rev]]"
+Restore a package from a previously-made backup.
+.PP
+If \f(CW\*(C`\-\-all\*(C'\fR is given, try to restore the latest revision of all
+package backups found in the backup directory.
+.PP
+Otherwise, if neither \fIpkg\fR nor \fIrev\fR are given, list the available backup
+revisions for all packages.
+.PP
+With \fIpkg\fR given but no \fIrev\fR, list all available backup revisions of
+\&\fIpkg\fR.
+.PP
+When listing available packages tlmgr shows the revision and in
+parenthesis the creation time if available (in format yyyy-mm-dd hh:mm).
+.PP
+With both \fIpkg\fR and \fIrev\fR, tries to restore the package from the
+specified backup.
+.PP
+Options:
+.IP "\fB\-\-all\fR" 4
+.IX Item "--all"
+Try to restore the latest revision of all package backups found in the
+backup directory. Additional non-option arguments (like \fIpkg\fR) are not
+allowed.
+.IP "\fB\-\-backupdir\fR \fIdirectory\fR" 4
+.IX Item "--backupdir directory"
+Specify the directory where the backups are to be found. If not given it
+will be taken from the configuration setting in the \s-1TLPDB\s0.
+.IP "\fB\-\-dry\-run\fR" 4
+.IX Item "--dry-run"
+Nothing is actually restored; instead, the actions to be performed are
+written to the terminal.
+.IP "\fB\-\-force\fR" 4
+.IX Item "--force"
+Don't ask questions.
+.SS "remove [\fIoption\fP]... \fIpkg\fP..."
+.IX Subsection "remove [option]... pkg..."
+Remove each \fIpkg\fR specified. Removing a collection removes all package
+dependencies (unless \f(CW\*(C`\-\-no\-depends\*(C'\fR is specified), but not any
+collection dependencies of that collection. However, when removing a
+package, dependencies are never removed. Options:
+.IP "\fB\-\-no\-depends\fR" 4
+.IX Item "--no-depends"
+Do not remove dependent packages.
+.IP "\fB\-\-no\-depends\-at\-all\fR" 4
+.IX Item "--no-depends-at-all"
+See above under \fBinstall\fR (and beware).
+.IP "\fB\-\-force\fR" 4
+.IX Item "--force"
+By default, removal of a package or collection that is a dependency of
+another collection or scheme is not allowed. With this option, the
+package will be removed unconditionally. Use with care.
+.Sp
+A package that has been removed using the \f(CW\*(C`\-\-force\*(C'\fR option because it
+is still listed in an installed collection or scheme will not be
+updated, and will be mentioned as \fBforcibly removed\fR in the output of
+\&\fBtlmgr update \-\-list\fR.
+.IP "\fB\-\-dry\-run\fR" 4
+.IX Item "--dry-run"
+Nothing is actually removed; instead, the actions to be performed are
+written to the terminal.
+.SS "repository"
+.IX Subsection "repository"
+.IP "\fBrepository list\fR" 4
+.IX Item "repository list"
+.PD 0
+.IP "\fBrepository list \f(BIpath|tag\fB\fR" 4
+.IX Item "repository list path|tag"
+.IP "\fBrepository add \f(BIpath\fB [\f(BItag\fB]\fR" 4
+.IX Item "repository add path [tag]"
+.IP "\fBrepository remove \f(BIpath|tag\fB\fR" 4
+.IX Item "repository remove path|tag"
+.IP "\fBrepository set \f(BIpath\fB[#\f(BItag\fB] [\f(BIpath\fB[#\f(BItag\fB] ...]\fR" 4
+.IX Item "repository set path[#tag] [path[#tag] ...]"
+.PD
+This action manages the list of repositories. See \*(L"\s-1MULTIPLE\s0
+\&\s-1REPOSITORIES\s0\*(R" below for detailed explanations.
+.Sp
+The first form (\f(CW\*(C`list\*(C'\fR) lists all configured repositories and the
+respective tags if set. If a path, url, or tag is given after the
+\&\f(CW\*(C`list\*(C'\fR keyword, it is interpreted as source from where to
+initialize a TeX Live Database and lists the contained packages.
+This can also be an up-to-now not used repository, both locally
+and remote. If one pass in addition \f(CW\*(C`\-\-with\-platforms\*(C'\fR, for each
+package the available platforms (if any) are listed, too.
+.Sp
+The third form (\f(CW\*(C`add\*(C'\fR) adds a repository
+(optionally attaching a tag) to the list of repositories. The forth
+form (\f(CW\*(C`remove\*(C'\fR) removes a repository, either by full path/url, or by
+tag. The last form (\f(CW\*(C`set\*(C'\fR) sets the list of repositories to the items
+given on the command line, not keeping previous settings
+.Sp
+In all cases, one of the repositories must be tagged as \f(CW\*(C`main\*(C'\fR;
+otherwise, all operations will fail!
+.SS "search [\fIoption\fP...] \fIwhat\fP"
+.IX Subsection "search [option...] what"
+\fIsearch [\fIoption\fI...] \-\-file \fIwhat\fI\fR
+.IX Subsection "search [option...] --file what"
+.PP
+\fIsearch [\fIoption\fI...] \-\-taxonomy \fIwhat\fI\fR
+.IX Subsection "search [option...] --taxonomy what"
+.PP
+\fIsearch [\fIoption\fI...] \-\-keyword \fIwhat\fI\fR
+.IX Subsection "search [option...] --keyword what"
+.PP
+\fIsearch [\fIoption\fI...] \-\-functionality \fIwhat\fI\fR
+.IX Subsection "search [option...] --functionality what"
+.PP
+\fIsearch [\fIoption\fI...] \-\-characterization \fIwhat\fI\fR
+.IX Subsection "search [option...] --characterization what"
+.PP
+\fIsearch [\fIoption\fI...] \-\-all \fIwhat\fI\fR
+.IX Subsection "search [option...] --all what"
+.PP
+By default, search the names, short descriptions, and long descriptions
+of all locally installed packages for the argument \fIwhat\fR, interpreted
+as a regular expression.
+.PP
+Options:
+.IP "\fB\-\-global\fR" 4
+.IX Item "--global"
+Search the TeX Live Database of the installation medium, instead of the
+local installation.
+.IP "\fB\-\-word\fR" 4
+.IX Item "--word"
+Restrict the search to match only full words. For example, searching for
+\&\f(CW\*(C`table\*(C'\fR with this option will not output packages containing the
+word \f(CW\*(C`tables\*(C'\fR (unless they also contain the word \f(CW\*(C`table\*(C'\fR on its own).
+.IP "\fB\-\-list\fR" 4
+.IX Item "--list"
+If a search for any (or all) taxonomies is done, by specifying one of
+the taxonomy options below, then instead of searching for packages, list
+the entire corresponding taxonomy (or all of them). See
+\&\*(L"\s-1TAXONOMIES\s0\*(R" below.
+.PP
+Other search options are selected by specifying one of the following:
+.IP "\fB\-\-file\fR" 4
+.IX Item "--file"
+List all filenames containing \fIwhat\fR.
+.IP "\fB\-\-taxonomy\fR" 4
+.IX Item "--taxonomy"
+.PD 0
+.IP "\fB\-\-keyword\fR" 4
+.IX Item "--keyword"
+.IP "\fB\-\-functionality\fR" 4
+.IX Item "--functionality"
+.IP "\fB\-\-characterization\fR" 4
+.IX Item "--characterization"
+.PD
+Search in the corresponding taxonomy (or all) instead of the package
+descriptions. See \*(L"\s-1TAXONOMIES\s0\*(R" below.
+.IP "\fB\-\-all\fR" 4
+.IX Item "--all"
+Search for package names, descriptions, and taxonomies, but not files.
+.SS "uninstall"
+.IX Subsection "uninstall"
+Uninstalls the entire TeX Live installation. Options:
+.IP "\fB\-\-force\fR" 4
+.IX Item "--force"
+Do not ask for confirmation, remove immediately.
+.SS "update [\fIoption\fP]... [\fIpkg\fP]..."
+.IX Subsection "update [option]... [pkg]..."
+Updates the packages given as arguments to the latest version available
+at the installation source. Either \f(CW\*(C`\-\-all\*(C'\fR or at least one \fIpkg\fR name
+must be specified. Options:
+.IP "\fB\-\-all\fR" 4
+.IX Item "--all"
+Update all installed packages except for \f(CW\*(C`tlmgr\*(C'\fR itself. Thus, if
+updates to \f(CW\*(C`tlmgr\*(C'\fR itself are present, this will simply give an error,
+unless also the option \f(CW\*(C`\-\-force\*(C'\fR or \f(CW\*(C`\-\-self\*(C'\fR is given. (See below.)
+.Sp
+In addition to updating the installed packages, during the update of a
+collection the local installation is (by default) synchronized to the
+status of the collection on the server, for both additions and removals.
+.Sp
+This means that if a package has been removed on the server (and thus
+has also been removed from the respective collection), \f(CW\*(C`tlmgr\*(C'\fR will
+remove the package in the local installation. This is called
+``auto\-remove'' and is announced as such when using the option
+\&\f(CW\*(C`\-\-list\*(C'\fR. This auto-removal can be suppressed using the option
+\&\f(CW\*(C`\-\-no\-auto\-remove\*(C'\fR.
+.Sp
+Analogously, if a package has been added to a collection on the server
+that is also installed locally, it will be added to the local
+installation. This is called ``auto\-install'' and is announced as such
+when using the option \f(CW\*(C`\-\-list\*(C'\fR. This auto-installation can be
+suppressed using the option \f(CW\*(C`\-\-no\-auto\-install\*(C'\fR.
+.Sp
+An exception to the collection dependency checks (including the
+auto-installation of packages just mentioned) are those that have been
+``forcibly removed'' by you, that is, you called \f(CW\*(C`tlmgr remove \-\-force\*(C'\fR
+on them. (See the \f(CW\*(C`remove\*(C'\fR action documentation.) To reinstall any
+such forcibly removed packages use \f(CW\*(C`\-\-reinstall\-forcibly\-removed\*(C'\fR.
+.Sp
+If you want to exclude some packages from the current update run (e.g.,
+due to a slow link), see the \f(CW\*(C`\-\-exclude\*(C'\fR option below.
+.IP "\fB\-\-self\fR" 4
+.IX Item "--self"
+Update \f(CW\*(C`tlmgr\*(C'\fR itself (that is, the infrastructure packages) if updates
+to it are present. On Windows this includes updates to the private Perl
+interpreter shipped inside TeX Live.
+.Sp
+If this option is given together with either \f(CW\*(C`\-\-all\*(C'\fR or a list of
+packages, then \f(CW\*(C`tlmgr\*(C'\fR will be updated first and, if this update
+succeeds, the new version will be restarted to complete the rest of the
+updates.
+.Sp
+In short:
+.Sp
+.Vb 4
+\& tlmgr update \-\-self # update infrastructure only
+\& tlmgr update \-\-self \-\-all # update infrastructure and all packages
+\& tlmgr update \-\-force \-\-all # update all packages but *not* infrastructure
+\& # ... this last at your own risk, not recommended!
+.Ve
+.IP "\fB\-\-dry\-run\fR" 4
+.IX Item "--dry-run"
+Nothing is actually installed; instead, the actions to be performed are
+written to the terminal. This is a more detailed report than \f(CW\*(C`\-\-list\*(C'\fR.
+.IP "\fB\-\-list\fR [\fIpkg\fR]" 4
+.IX Item "--list [pkg]"
+Concisely list the packages which would be updated, newly installed, or
+removed, without actually changing anything.
+If \f(CW\*(C`\-\-all\*(C'\fR is also given, all available updates are listed.
+If \f(CW\*(C`\-\-self\*(C'\fR is given, but not \f(CW\*(C`\-\-all\*(C'\fR, only updates to the
+critical packages (tlmgr, texlive infrastructure, perl on Windows, etc.)
+are listed.
+If neither \f(CW\*(C`\-\-all\*(C'\fR nor \f(CW\*(C`\-\-self\*(C'\fR is given, and in addition no \fIpkg\fR is
+given, then \f(CW\*(C`\-\-all\*(C'\fR is assumed (thus, \f(CW\*(C`tlmgr update \-\-list\*(C'\fR is the
+same as \f(CW\*(C`tlmgr update \-\-list \-\-all\*(C'\fR).
+If neither \f(CW\*(C`\-\-all\*(C'\fR nor \f(CW\*(C`\-\-self\*(C'\fR is given, but specific package names are
+given, those packages are checked for updates.
+.IP "\fB\-\-exclude\fR \fIpkg\fR" 4
+.IX Item "--exclude pkg"
+Exclude \fIpkg\fR from the update process. If this option is given more
+than once, its arguments accumulate.
+.Sp
+An argument \fIpkg\fR excludes both the package \fIpkg\fR itself and all
+its related platform-specific packages \fIpkg.ARCH\fR. For example,
+.Sp
+.Vb 1
+\& tlmgr update \-\-all \-\-exclude a2ping
+.Ve
+.Sp
+will not update \f(CW\*(C`a2ping\*(C'\fR, \f(CW\*(C`a2ping.i386\-linux\*(C'\fR, or
+any other \f(CW\*(C`a2ping.\*(C'\fR\fI\s-1ARCH\s0\fR package.
+.Sp
+If this option specifies a package that would otherwise be a candidate
+for auto-installation, auto-removal, or reinstallation of a forcibly
+removed package, \f(CW\*(C`tlmgr\*(C'\fR quits with an error message. Excludes are not
+supported in these circumstances.
+.IP "\fB\-\-no\-auto\-remove\fR [\fIpkg\fR]..." 4
+.IX Item "--no-auto-remove [pkg]..."
+Under normal circumstances \f(CW\*(C`tlmgr\*(C'\fR tries to remove packages which have
+disappeared on the server, as described above under \f(CW\*(C`\-\-all\*(C'\fR. This
+option prevents any such removals, either for all packages (with
+\&\f(CW\*(C`\-\-all\*(C'\fR), or the given \fIpkg\fR names.
+.IP "\fB\-\-no\-auto\-install\fR [\fIpkg\fR]..." 4
+.IX Item "--no-auto-install [pkg]..."
+Under normal circumstances \f(CW\*(C`tlmgr\*(C'\fR will install packages which are new
+on the server, as described above under \f(CW\*(C`\-\-all\*(C'\fR. This option prevents
+any such automatic installation, either for all packages (with
+\&\f(CW\*(C`\-\-all\*(C'\fR), or the given \fIpkg\fR names.
+.Sp
+Furthermore, after the \f(CW\*(C`tlmgr\*(C'\fR run using this has finished, the
+packages that would have been auto-installed \fIwill be considered as
+forcibly removed\fR. So, if \f(CW\*(C`foobar\*(C'\fR is the only new package on the
+server, then
+.Sp
+.Vb 1
+\& tlmgr update \-\-all \-\-no\-auto\-install
+.Ve
+.Sp
+is equivalent to
+.Sp
+.Vb 2
+\& tlmgr update \-\-all
+\& tlmgr remove \-\-force foobar
+.Ve
+.IP "\fB\-\-reinstall\-forcibly\-removed\fR" 4
+.IX Item "--reinstall-forcibly-removed"
+Under normal circumstances \f(CW\*(C`tlmgr\*(C'\fR will not install packages that have
+been forcibly removed by the user; that is, removed with \f(CW\*(C`remove
+\&\-\-force\*(C'\fR, or whose installation was prohibited by \f(CW\*(C`\-\-no\-auto\-install\*(C'\fR
+during an earlier update.
+.Sp
+This option makes \f(CW\*(C`tlmgr\*(C'\fR ignore the forcible removals and re-install
+all such packages. This can be used to completely synchronize an
+installation with the server's idea of what is available:
+.Sp
+.Vb 1
+\& tlmgr update \-\-reinstall\-forcibly\-removed \-\-all
+.Ve
+.IP "\fB\-\-backup\fR and \fB\-\-backupdir\fR \fIdirectory\fR" 4
+.IX Item "--backup and --backupdir directory"
+These two options control the creation of backups of packages \fIbefore\fR
+updating; that is, backup of packages as currently installed. If
+neither of these options are given, no backup package will be saved. If
+\&\f(CW\*(C`\-\-backupdir\*(C'\fR is given and specifies a writable directory then a backup
+will be made in that location. If only \f(CW\*(C`\-\-backup\*(C'\fR is given, then a
+backup will be made to the directory previously set via the \f(CW\*(C`option\*(C'\fR
+action (see below). If both are given then a backup will be made to the
+specified \fIdirectory\fR.
+.Sp
+You can set options via the \f(CW\*(C`option\*(C'\fR action to automatically create
+backups for all packages, and/or keep only a certain number of
+backups. Please see the \f(CW\*(C`option\*(C'\fR action for details.
+.Sp
+\&\f(CW\*(C`tlmgr\*(C'\fR always makes a temporary backup when updating packages, in case
+of download or other failure during an update. In contrast, the purpose
+of this \f(CW\*(C`\-\-backup\*(C'\fR option is to allow you to save a persistent backup
+in case the actual \fIcontent\fR of the update causes problems, e.g.,
+introduces an incompatibility.
+.Sp
+The \f(CW\*(C`restore\*(C'\fR action explains how to restore from a backup.
+.IP "\fB\-\-no\-depends\fR" 4
+.IX Item "--no-depends"
+If you call for updating a package normally all depending packages
+will also be checked for updates and updated if necessary. This switch
+suppresses this behavior.
+.IP "\fB\-\-no\-depends\-at\-all\fR" 4
+.IX Item "--no-depends-at-all"
+See above under \fBinstall\fR (and beware).
+.IP "\fB\-\-force\fR" 4
+.IX Item "--force"
+Force update of normal packages, without updating \f(CW\*(C`tlmgr\*(C'\fR itself
+(unless the \f(CW\*(C`\-\-self\*(C'\fR option is also given). Not recommended.
+.Sp
+Also, \f(CW\*(C`update \-\-list\*(C'\fR is still performed regardless of this option.
+.PP
+If the package on the server is older than the package already installed
+(e.g., if the selected mirror is out of date), \f(CW\*(C`tlmgr\*(C'\fR does not
+downgrade. Also, packages for uninstalled platforms are not installed.
+.SH "TLMGR CONFIGURATION FILE"
+.IX Header "TLMGR CONFIGURATION FILE"
+A small subset of the command line options can be set in a config file
+for \f(CW\*(C`tlmgr\*(C'\fR which resides in \f(CW\*(C`TEXMFCONFIG/tlmgr/config\*(C'\fR. By default, the
+config file is in \f(CW\*(C`~/.texliveYYYY/texmf\-config/tlmgr/config\*(C'\fR (replacing
+\&\f(CW\*(C`YYYY\*(C'\fR with the year of your TeX Live installation). This is \fInot\fR
+\&\f(CW\*(C`TEXMFSYSVAR\*(C'\fR, so that the file is specific to a single user.
+.PP
+In this file, empty lines and lines starting with # are ignored. All
+other lines must look like
+.PP
+.Vb 1
+\& key = value
+.Ve
+.PP
+where the allowed keys are
+\&\f(CW\*(C`gui\-expertmode\*(C'\fR (values 0 or 1),
+\&\f(CW\*(C`persistent\-downloads\*(C'\fR (values 0 or 1), \f(CW\*(C`auto\-remove\*(C'\fR (values 0 or 1),
+and \f(CW\*(C`gui\-lang\*(C'\fR (values like the command line arguments).
+\&\f(CW\*(C`persistent\-downloads\*(C'\fR, \f(CW\*(C`gui\-lang\*(C'\fR, and \f(CW\*(C`auto\-remove\*(C'\fR correspond to the
+respective command line options of the same name.
+\&\f(CW\*(C`gui\-expertmode\*(C'\fR switches between the full
+\&\s-1GUI\s0 and a simplified \s-1GUI\s0 with only the important and mostly used
+settings.
+.SH "TAXONOMIES"
+.IX Header "TAXONOMIES"
+tlmgr allows searching and listing of various categorizations, which we
+call \fItaxonomies\fR, as provided by an enhanced TeX Catalogue (available
+for testing at <http://az.ctan.org>). This is useful when, for
+example, you don't know a specific package name but have an idea of the
+functionality you need; or when you want to see all packages relating to
+a given area.
+.PP
+There are three different taxonomies, specified by the following
+options:
+.IP "\fB\-\-keyword\fR" 4
+.IX Item "--keyword"
+The keywords, as specified at <http://az.ctan.org/keyword>.
+.IP "\fB\-\-functionality\fR" 4
+.IX Item "--functionality"
+The ``by\-topic'' categorization created by J\e"urgen Fenn, as specified
+at http://az.ctan.org/characterization/by\-function <http://az.ctan.org/characterization/by-function>.
+.IP "\fB\-\-characterization\fR" 4
+.IX Item "--characterization"
+Both the primary and secondary functionalities, as specified at
+<http://az.ctan.org/characterization/choose_dimen>.
+.IP "\fB\-\-taxonomy\fR" 4
+.IX Item "--taxonomy"
+Operate on all the taxonomies.
+.PP
+The taxonomies are updated nightly and stored within TeX Live, so
+Internet access is not required to search them.
+.PP
+Examples:
+.PP
+.Vb 5
+\& tlmgr search \-\-taxonomy exercise # check all taxonomies for "exercise"
+\& tlmgr search \-\-taxonomy \-\-word table # check for "table" on its own
+\& tlmgr search \-\-list \-\-keyword # dump entire keyword taxonomy
+\& tlmgr show \-\-taxonomy pdftex # show pdftex package information,
+\& # including all taxonomy entries
+.Ve
+.SH "MULTIPLE REPOSITORIES"
+.IX Header "MULTIPLE REPOSITORIES"
+The main TeX Live repository contains a vast array of packages.
+Nevertheless, additional local repositories can be useful to provide
+locally-installed resources, such as proprietary fonts and house styles.
+Also, alternative package repositories distribute packages that cannot
+or should not be included in TeX Live, for whatever reason.
+.PP
+The simplest and most reliable method is to temporarily set the
+installation source to any repository (with the \f(CW\*(C`\-repository\*(C'\fR or
+\&\f(CW\*(C`option repository\*(C'\fR command line options), and perform your operations.
+.PP
+When you are using multiple repositories over a sustained time, however,
+explicitly switching between them becomes inconvenient. Thus, it's
+possible to tell \f(CW\*(C`tlmgr\*(C'\fR about additional repositories you want to use.
+The basic command is \f(CW\*(C`tlmgr repository add\*(C'\fR. The rest of this section
+explains further.
+.PP
+When using multiple repositories, one of them has to be set as the main
+repository, which distributes most of the installed packages. When you
+switch from a single repository installation to a multiple repository
+installation, the previous sole repository will be set as the main
+repository.
+.PP
+By default, even if multiple repositories are configured, packages are
+\&\fIstill\fR \fIonly\fR installed from the main repository. Thus, simply
+adding a second repository does not actually enable installation of
+anything from there. You also have to specify which packages should be
+taken from the new repository, by specifying so-called ``pinning''
+rules, described next.
+.SS "Pinning"
+.IX Subsection "Pinning"
+When a package \f(CW\*(C`foo\*(C'\fR is pinned to a repository, a package \f(CW\*(C`foo\*(C'\fR in any
+other repository, even if it has a higher revision number, will not be
+considered an installable candidate.
+.PP
+As mentioned above, by default everything is pinned to the main
+repository. Let's now go through an example of setting up a second
+repository and enabling updates of a package from it.
+.PP
+First, check that we have support for multiple repositories, and have
+only one enabled (as is the case by default):
+.PP
+.Vb 3
+\& $ tlmgr repository list
+\& List of repositories (with tags if set):
+\& /var/www/norbert/tlnet
+.Ve
+.PP
+Ok. Let's add the \f(CW\*(C`tlcontrib\*(C'\fR repository (this is a real
+repository, hosted at <http://tlcontrib.metatex.org>, maintained by
+Taco Hoekwater et al.), with the tag \f(CW\*(C`tlcontrib\*(C'\fR:
+.PP
+.Vb 1
+\& $ tlmgr repository add http://tlcontrib.metatex.org/2012 tlcontrib
+.Ve
+.PP
+Check the repository list again:
+.PP
+.Vb 4
+\& $ tlmgr repository list
+\& List of repositories (with tags if set):
+\& http://tlcontrib.metatex.org/2012 (tlcontrib)
+\& /var/www/norbert/tlnet (main)
+.Ve
+.PP
+Now we specify a pinning entry to get the package \f(CW\*(C`context\*(C'\fR from
+\&\f(CW\*(C`tlcontrib\*(C'\fR:
+.PP
+.Vb 1
+\& $ tlmgr pinning add tlcontrib context
+.Ve
+.PP
+Check that we can find \f(CW\*(C`context\*(C'\fR:
+.PP
+.Vb 6
+\& $ tlmgr show context
+\& tlmgr: package repositories:
+\& ...
+\& package: context
+\& repository: tlcontrib/26867
+\& ...
+.Ve
+.PP
+\&\- install \f(CW\*(C`context\*(C'\fR:
+.PP
+.Vb 4
+\& $ tlmgr install context
+\& tlmgr: package repositories:
+\& ...
+\& [1/1, ??:??/??:??] install: context @tlcontrib [
+.Ve
+.PP
+In the output here you can see that the \f(CW\*(C`context\*(C'\fR package has been
+installed from the \f(CW\*(C`tlcontrib\*(C'\fR repository (\f(CW@tlcontrib\fR).
+.PP
+Finally, \f(CW\*(C`tlmgr pinning\*(C'\fR also supports removing certain or all packages
+from a given repository:
+.PP
+.Vb 2
+\& $ tlmgr pinning remove tlcontrib context # remove just context
+\& $ tlmgr pinning remove tlcontrib \-\-all # take nothing from tlcontrib
+.Ve
+.PP
+A summary of the \f(CW\*(C`tlmgr pinning\*(C'\fR actions is given above.
+.SH "GUI FOR TLMGR"
+.IX Header "GUI FOR TLMGR"
+The graphical user interface for \f(CW\*(C`tlmgr\*(C'\fR needs Perl/Tk to be installed.
+For Windows the necessary modules are shipped within TeX Live, for all
+other (i.e., Unix-based) systems Perl/Tk (as well as Perl of course) has
+to be installed. <http://tug.org/texlive/distro.html#perltk> has a
+list of invocations for some distros.
+.PP
+When started with \f(CW\*(C`tlmgr gui\*(C'\fR the graphical user interface will be
+shown. The main window contains a menu bar, the main display, and a
+status area where messages normally shown on the console are displayed.
+.PP
+Within the main display there are three main parts: the \f(CW\*(C`Display
+configuration\*(C'\fR area, the list of packages, and the action buttons.
+.PP
+Also, at the top right the currently loaded repository is shown; this
+also acts as a button and when clicked will try to load the default
+repository. To load a different repository, see the \f(CW\*(C`tlmgr\*(C'\fR menu item.
+.PP
+Finally, the status area at the bottom of the window gives additional
+information about what is going on.
+.SS "Main display"
+.IX Subsection "Main display"
+\fIDisplay configuration area\fR
+.IX Subsection "Display configuration area"
+.PP
+The first part of the main display allows you to specify (filter) which
+packages are shown. By default, all are shown. Changes here are
+reflected right away.
+.IP "Status" 4
+.IX Item "Status"
+Select whether to show all packages (the default), only those installed,
+only those \fInot\fR installed, or only those with update available.
+.IP "Category" 4
+.IX Item "Category"
+Select which categories are shown: packages, collections, and/or
+schemes. These are briefly explained in the \*(L"\s-1DESCRIPTION\s0\*(R" section
+above.
+.IP "Match" 4
+.IX Item "Match"
+Select packages matching for a specific pattern. By default, this uses
+the same algorithm as \f(CW\*(C`tlmgr search\*(C'\fR, i.e., searches everything:
+descriptions, taxonomies, and/or filenames. You can also select any
+subset for searching.
+.IP "Selection" 4
+.IX Item "Selection"
+Select packages to those selected, those not selected, or all. Here,
+``selected'' means that the checkbox in the beginning of the line of a
+package is ticked.
+.IP "Display configuration buttons" 4
+.IX Item "Display configuration buttons"
+To the right there are three buttons: select all packages, select none
+(a.k.a. deselect all), and reset all these filters to the defaults,
+i.e., show all available.
+.PP
+\fIPackage list area\fR
+.IX Subsection "Package list area"
+.PP
+The second are of the main display lists all installed packages. If a
+repository is loaded, those that are available but not installed are
+also listed.
+.PP
+Double clicking on a package line pops up an informational window with
+further details: the long description, included files, etc.
+.PP
+Each line of the package list consists of the following items:
+.IP "a checkbox" 4
+.IX Item "a checkbox"
+Used to select particular packages; some of the action buttons (see
+below) work only on the selected packages.
+.IP "package name" 4
+.IX Item "package name"
+The name (identifier) of the package as given in the database.
+.IP "local revision (and version)" 4
+.IX Item "local revision (and version)"
+If the package is installed the TeX Live revision number for the
+installed package will be shown. If there is a catalogue version given
+in the database for this package, it will be shown in parentheses.
+However, the catalogue version, unlike the \s-1TL\s0 revision, is not
+guaranteed to reflect what is actually installed.
+.IP "remote revision (and version)" 4
+.IX Item "remote revision (and version)"
+If a repository has been loaded the revision of the package in the
+repository (if present) is shown. As with the local column, if a
+catalogue version is provided it will be displayed. And also as with
+the local column, the catalogue version may be stale.
+.IP "short description" 4
+.IX Item "short description"
+The short description of the package.
+.PP
+\fIMain display action buttons\fR
+.IX Subsection "Main display action buttons"
+.PP
+Below the list of packages are several buttons:
+.IP "Update all installed" 4
+.IX Item "Update all installed"
+This calls \f(CW\*(C`tlmgr update \-\-all\*(C'\fR, i.e., tries to update all available
+packages. Below this button is a toggle to allow reinstallation of
+previously removed packages as part of this action.
+.Sp
+The other four buttons only work on the selected packages, i.e., those
+where the checkbox at the beginning of the package line is ticked.
+.IP "Update" 4
+.IX Item "Update"
+Update only the selected packages.
+.IP "Install" 4
+.IX Item "Install"
+Install the selected packages; acts like \f(CW\*(C`tlmgr install\*(C'\fR, i.e., also
+installs dependencies. Thus, installing a collection installs all its
+constituent packages.
+.IP "Remove" 4
+.IX Item "Remove"
+Removes the selected packages; acts like \f(CW\*(C`tlmgr remove\*(C'\fR, i.e., it will
+also remove dependencies of collections (but not dependencies of normal
+packages).
+.IP "Backup" 4
+.IX Item "Backup"
+Makes a backup of the selected packages; acts like \f(CW\*(C`tlmgr backup\*(C'\fR. This
+action needs the option \f(CW\*(C`backupdir\*(C'\fR set (see \f(CW\*(C`Options \-\*(C'\fR General>).
+.SS "Menu bar"
+.IX Subsection "Menu bar"
+The following entries can be found in the menu bar:
+.IP "\fBtlmgr\fR menu" 4
+.IX Item "tlmgr menu"
+The items here load various repositories: the default as specified in
+the TeX Live database, the default network repository, the repository
+specified on the command line (if any), and an arbitrarily
+manually-entered one. Also has the so-necessary \f(CW\*(C`quit\*(C'\fR operation.
+.IP "\fBOptions menu\fR" 4
+.IX Item "Options menu"
+Provides access to several groups of options: \f(CW\*(C`Paper\*(C'\fR (configuration of
+default paper sizes), \f(CW\*(C`Platforms\*(C'\fR (only on Unix, configuration of the
+supported/installed platforms), \f(CW\*(C`GUI Language\*(C'\fR (select language used in
+the \s-1GUI\s0 interface), and \f(CW\*(C`General\*(C'\fR (everything else).
+.Sp
+Several toggles are also here. The first is \f(CW\*(C`Expert options\*(C'\fR, which is
+set by default. If you turn this off, the next time you start the \s-1GUI\s0 a
+simplified screen will be shown that display only the most important
+functionality. This setting is saved in the configuration file of
+\&\f(CW\*(C`tlmgr\*(C'\fR; see \*(L"\s-1CONFIGURATION\s0 \s-1FILE\s0\*(R" for details.
+.Sp
+The other toggles are all off by default: for debugging output, to
+disable the automatic installation of new packages, and to disable the
+automatic removal of packages deleted from the server. Playing with the
+choices of what is or isn't installed may lead to an inconsistent TeX Live
+installation; e.g., when a package is renamed.
+.IP "\fBActions menu\fR" 4
+.IX Item "Actions menu"
+Provides access to several actions: update the filename database (aka
+\&\f(CW\*(C`ls\-R\*(C'\fR, \f(CW\*(C`mktexlsr\*(C'\fR, \f(CW\*(C`texhash\*(C'\fR), rebuild all formats (\f(CW\*(C`fmtutil\-sys
+\&\-\-all\*(C'\fR), update the font map database (\f(CW\*(C`updmap\-sys\*(C'\fR), restore from a backup
+of a package, and use of symbolic links in system directories (not on
+Windows).
+.Sp
+The final action is to remove the entire TeX Live installation (also not
+on Windows).
+.IP "\fBHelp menu\fR" 4
+.IX Item "Help menu"
+Provides access to the TeX Live manual (also on the web at
+<http://tug.org/texlive/doc.html>) and the usual ``About'' box.
+.SH "MACHINE-READABLE OUTPUT"
+.IX Header "MACHINE-READABLE OUTPUT"
+With the \f(CW\*(C`\-\-machine\-readable\*(C'\fR option, \f(CW\*(C`tlmgr\*(C'\fR writes to stdout in the
+fixed line-oriented format described here, and the usual informational
+messages for human consumption are written to stderr (normally they are
+written to stdout). The idea is that a program can get all the
+information it needs by reading stdout.
+.PP
+Currently this option only applies to the
+update, the
+install, and the
+option actions.
+.SS "update and install actions"
+.IX Subsection "update and install actions"
+The output format is as follows:
+.PP
+.Vb 7
+\& fieldname "\et" value
+\& ...
+\& "end\-of\-header"
+\& pkgname status localrev serverrev size runtime esttot
+\& ...
+\& "end\-of\-updates"
+\& other output from post actions, not in machine readable form
+.Ve
+.PP
+The header section currently has two fields: \f(CW\*(C`location\-url\*(C'\fR (the
+repository source from which updates are being drawn), and
+\&\f(CW\*(C`total\-bytes\*(C'\fR (the total number of bytes to be downloaded).
+.PP
+The \fIlocalrev\fR and \fIserverrev\fR fields for each package are the
+revision numbers in the local installation and server repository,
+respectively. The \fIsize\fR field is the number of bytes to be
+downloaded, i.e., the size of the compressed tar file for a network
+installation, not the unpacked size. The runtime and esttot fields
+are only present for updated and auto-install packages, and contain
+the currently passed time since start of installation/updates
+and the estimated total time.
+.PP
+Line endings may be either \s-1LF\s0 or \s-1CRLF\s0 depending on the current platform.
+.ie n .IP """location\-url"" \fIlocation\fR" 4
+.el .IP "\f(CWlocation\-url\fR \fIlocation\fR" 4
+.IX Item "location-url location"
+The \fIlocation\fR may be a url (including \f(CW\*(C`file:///foo/bar/...\*(C'\fR), or a
+directory name (\f(CW\*(C`/foo/bar\*(C'\fR). It is the package repository from which
+the new package information was drawn.
+.ie n .IP """total\-bytes"" \fIcount\fR" 4
+.el .IP "\f(CWtotal\-bytes\fR \fIcount\fR" 4
+.IX Item "total-bytes count"
+The \fIcount\fR is simply a decimal number, the sum of the sizes of all the
+packages that need updating or installing (which are listed subsequently).
+.PP
+Then comes a line with only the literal string \f(CW\*(C`end\-of\-header\*(C'\fR.
+.PP
+Each following line until a line with literal string \f(CW\*(C`end\-of\-updates\*(C'\fR
+reports on one package. The fields on
+each line are separated by a tab. Here are the fields.
+.IP "\fIpkgname\fR" 4
+.IX Item "pkgname"
+The TeX Live package identifier, with a possible platform suffix for
+executables. For instance, \f(CW\*(C`pdftex\*(C'\fR and \f(CW\*(C`pdftex.i386\-linux\*(C'\fR are given
+as two separate packages, one on each line.
+.IP "\fIstatus\fR" 4
+.IX Item "status"
+The status of the package update. One character, as follows:
+.RS 4
+.ie n .IP """d""" 8
+.el .IP "\f(CWd\fR" 8
+.IX Item "d"
+The package was removed on the server.
+.ie n .IP """f""" 8
+.el .IP "\f(CWf\fR" 8
+.IX Item "f"
+The package was removed in the local installation, even though a
+collection depended on it. (E.g., the user ran \f(CW\*(C`tlmgr remove
+\&\-\-force\*(C'\fR.)
+.ie n .IP """u""" 8
+.el .IP "\f(CWu\fR" 8
+.IX Item "u"
+Normal update is needed.
+.ie n .IP """r""" 8
+.el .IP "\f(CWr\fR" 8
+.IX Item "r"
+Reversed non-update: the locally-installed version is newer than the
+version on the server.
+.ie n .IP """a""" 8
+.el .IP "\f(CWa\fR" 8
+.IX Item "a"
+Automatically-determined need for installation, the package is new on
+the server and is (most probably) part of an installed collection.
+.ie n .IP """i""" 8
+.el .IP "\f(CWi\fR" 8
+.IX Item "i"
+Package will be installed and isn't present in the local installation
+(action install).
+.ie n .IP """I""" 8
+.el .IP "\f(CWI\fR" 8
+.IX Item "I"
+Package is already present but will be reinstalled (action install).
+.RE
+.RS 4
+.RE
+.IP "\fIlocalrev\fR" 4
+.IX Item "localrev"
+The revision number of the installed package, or \f(CW\*(C`\-\*(C'\fR if it is not
+present locally.
+.IP "\fIserverrev\fR" 4
+.IX Item "serverrev"
+The revision number of the package on the server, or \f(CW\*(C`\-\*(C'\fR if it is not
+present on the server.
+.IP "\fIsize\fR" 4
+.IX Item "size"
+The size in bytes of the package on the server. The sum of all the
+package sizes is given in the \f(CW\*(C`total\-bytes\*(C'\fR header field mentioned above.
+.IP "\fIruntime\fR" 4
+.IX Item "runtime"
+The run time since start of installations or updates.
+.IP "\fIesttot\fR" 4
+.IX Item "esttot"
+The estimated total time.
+.SS "option action"
+.IX Subsection "option action"
+The output format is as follows:
+.PP
+.Vb 1
+\& key "\et" value
+.Ve
+.PP
+If a value is not saved in the database the string \f(CW\*(C`(not set)\*(C'\fR is shown.
+.PP
+If you are developing a program that uses this output, and find that
+changes would be helpful, do not hesitate to write the mailing list.
+.SH "AUTHORS AND COPYRIGHT"
+.IX Header "AUTHORS AND COPYRIGHT"
+This script and its documentation were written for the TeX Live
+distribution (<http://tug.org/texlive>) and both are licensed under the
+\&\s-1GNU\s0 General Public License Version 2 or later.
+.SH "POD ERRORS"
+.IX Header "POD ERRORS"
+Hey! \fBThe above document had some coding errors, which are explained below:\fR
+.IP "Around line 6509:" 4
+.IX Item "Around line 6509:"
+Unterminated C<...> sequence
+.IP "Around line 6514:" 4
+.IX Item "Around line 6514:"
+Unterminated C<...> sequence