diff options
Diffstat (limited to 'Master/texmf-dist/doc/man/man1/tlmgr.1')
| -rw-r--r-- | Master/texmf-dist/doc/man/man1/tlmgr.1 | 1655 |
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 |