diff options
author | Denis Bitouzé <dbitouze@wanadoo.fr> | 2021-02-25 18:23:07 +0000 |
---|---|---|
committer | Denis Bitouzé <dbitouze@wanadoo.fr> | 2021-02-25 18:23:07 +0000 |
commit | c6101f91d071883b48b1b4b51e5eba0f36d9a78d (patch) | |
tree | 1bf7f5a881d7a4f5c5bf59d0b2821943dd822372 /Build/source/doc/tlbuild-incl | |
parent | 07ee7222e389b0777456b427a55c22d0e6ffd267 (diff) |
French translation for tlmgr updated
git-svn-id: svn://tug.org/texlive/trunk@57912 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/doc/tlbuild-incl')
-rw-r--r-- | Build/source/doc/tlbuild-incl/install-tl.texi | 577 | ||||
-rw-r--r-- | Build/source/doc/tlbuild-incl/tlmgr.texi | 2742 |
2 files changed, 0 insertions, 3319 deletions
diff --git a/Build/source/doc/tlbuild-incl/install-tl.texi b/Build/source/doc/tlbuild-incl/install-tl.texi deleted file mode 100644 index 6e0e4d00997..00000000000 --- a/Build/source/doc/tlbuild-incl/install-tl.texi +++ /dev/null @@ -1,577 +0,0 @@ -@node install-tl -@appendix install-tl - -@menu -* install-tl NAME:: -* install-tl SYNOPSIS:: -* install-tl DESCRIPTION:: -* install-tl REFERENCES:: -* install-tl OPTIONS:: -* install-tl PROFILES:: -* install-tl ENVIRONMENT VARIABLES:: -* install-tl AUTHORS AND COPYRIGHT:: -@end menu - -@node install-tl NAME -@appendixsec NAME - -install-tl - TeX Live cross-platform installer - -@node install-tl SYNOPSIS -@appendixsec SYNOPSIS - -install-tl [@emph{option}]... - -install-tl-windows.bat [@emph{option}]... - -install-tl-advanced.bat [@emph{option}]... - -@node install-tl DESCRIPTION -@appendixsec DESCRIPTION - -This installer creates a runnable TeX Live installation from various -media, including over the network, from local hard disk, a DVD, etc. The -installer works on all platforms supported by TeX Live. For information -on initially downloading TeX Live, see -@url{https://tug.org/texlive/acquire.html}. - -The basic idea of TeX Live installation is for you to choose one of the -top-level @emph{schemes}, each of which is defined as a different set of -@emph{collections} and @emph{packages}, where a collection is a set of packages, -and a package is what contains actual files. - -Within the installer, you can choose a scheme, and further customize the -set of collections to install, but not the set of the packages. To work -at the package level, use @code{tlmgr} (reference just below) after the -initial installation is complete. - -The default is @code{scheme-full}, which installs everything, and this is -highly recommended. - -@node install-tl REFERENCES -@appendixsec REFERENCES - -Post-installation configuration, package updates, and more, are -handled through @strong{tlmgr}(1), the TeX Live Manager -(@url{https://tug.org/texlive/tlmgr.html}). - -The most up-to-date version of this installer documentation is on the -Internet at @url{https://tug.org/texlive/doc/install-tl.html}. - -For the full documentation of TeX Live, see -@url{https://tug.org/texlive/doc}. - -@node install-tl OPTIONS -@appendixsec OPTIONS - -As usual, all options can be specified in any order, and with either a -leading @code{-} or @code{--}. An argument value can be separated from its -option by either a space or @code{=}. - -@table @asis -@item @strong{-gui} [[=]@emph{module}] -@anchor{install-tl @strong{-gui} [[=]@emph{module}]} - -If no @emph{module} is given, starts the Tcl/Tk (see below) GUI installer. - -If @emph{module} is given loads the given installer module. Currently the -following modules are supported: - -@table @asis -@item @code{text} -@anchor{install-tl @code{text}} - -The text mode user interface (default on Unix systems). Same as the -@code{-no-gui} option. - -@item @code{tcl} -@anchor{install-tl @code{tcl}} - -The Tcl/Tk user interface (default on Macs and Windows). It starts -with a small number of configuration options, roughly equivalent -to what the wizard option below offers, but a button @code{Advanced} -takes you to a screen with roughly the same options as the @code{perltk} -interface. - -@item @code{wizard} -@anchor{install-tl @code{wizard}} - -The wizard mode user interface, asking only minimal questions before -installing all of TeX Live. - -@item @code{expert} -@anchor{install-tl @code{expert}} - -A generic name for, currently, @code{perltk}; it may select a different GUI -in the future. - -@item @code{perltk} -@anchor{install-tl @code{perltk}} - -The expert GUI installer, providing access to more options. - -@end table - -The @code{perltk} and @code{wizard} modules require the Perl/Tk module -(@url{https://tug.org/texlive/distro.html#perltk}). if Perl/Tk is not -available, installation continues in text mode, except on Windows, -where all gui options except @code{text} are diverted to the default -@code{tcl} GUI. - -The @code{tcl} GUI requires Tcl/Tk. This is standard on Macs and is often -already installed on GNU/Linux. For Windows, TeX Live provides a Tcl/Tk -runtime. - -@item @strong{-no-gui} -@anchor{install-tl @strong{-no-gui}} - -Use the text mode installer (default except on Windows and Macs). - -@item @strong{-lang} @emph{llcode} -@anchor{install-tl @strong{-lang} @emph{llcode}} - -By default, the GUI tries to deduce your language from the -environment. The Tcl GUI uses the language detection built into -Tcl/Tk; the Perl/Tk GUIs use the @code{LC_MESSAGES} environment -variable. If that fails you can select a different language by -giving this option with a language code (based on ISO 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), -Ukrainian (uk), Vietnamese (vi), simplified Chinese (zh_CN), and -traditional Chinese (zh_TW). - -@item @strong{-repository} @emph{url|path} -@anchor{install-tl @strong{-repository} @emph{url|path}} - -Specify the package repository to be used as the source of the -installation. In short, this can be a directory name or a url using -http(s), ftp, or scp. The documentation for @code{tlmgr} has the details -(@url{https://tug.org/texlive/doc/tlmgr.html#OPTIONS}). - -For installation, the default is to pick a mirror automatically, using -@url{http://mirror.ctan.org/systems/texlive/tlnet}; the chosen mirror is -used for the entire download. You can use the special argument @code{ctan} -as an abbreviation for this. (See @url{https://ctan.org} for more about CTAN -and its mirrors.) - -After installation is complete, you can use that installation as the -repository for another installation. If you chose to install less than -the full scheme containing all packages, the list of available schemes -will be adjusted accordingly. - -@item @strong{-select-repository} -@anchor{install-tl @strong{-select-repository}} - -This option allows you to choose a particular mirror from the current -list of active CTAN mirrors. This option is supported in the @code{text}, -@code{wizard} and @code{perltk} installer modes, and will also offer to install -from local media if available, or from a repository specified on the -command line. It's useful when the (default) automatic redirection does -not choose a good host for you. - -@item @strong{-all-options} -@anchor{install-tl @strong{-all-options}} - -Normally options not relevant to the current platform are not shown -(e.g., when running on Unix, Windows-specific options are omitted). -Giving this command line option allows configuring such "foreign" -settings. - -@item @strong{-custom-bin} @emph{path} -@anchor{install-tl @strong{-custom-bin} @emph{path}} - -If you have built your own set of TeX Live binaries (perhaps because -your platform was not supported by TeX Live out of the box), this option -allows you to specify the @emph{path} to a directory where the binaries for -the current system are present. The installation will continue as -usual, but at the end all files from @emph{path} are copied over to -@code{bin/custom/} under your installation directory and this @code{bin/custom/} -directory is what will be added to the path for the post-install -actions. To install multiple custom binary sets, manually rename -@code{custom} before doing each. - -For more information on custom binaries, see -@url{https://tug.org/texlive/custom-bin.html}. For general information on -building TeX Live, see @url{https://tug.org/texlive/build.html}. - -@item @strong{-debug-translation} -@anchor{install-tl @strong{-debug-translation}} - -In the Perl/Tk GUI modes, this option reports any missing, or more -likely untranslated, messages to standard error. Helpful for -translators to see what remains to be done. - -@item @strong{-force-platform} @emph{platform} -@anchor{install-tl @strong{-force-platform} @emph{platform}} - -Instead of auto-detecting the current platform, use @emph{platform}. -Binaries for this platform must be present and they must actually be -runnable, or installation will fail. @code{-force-arch} is a synonym. - -@item @strong{-help}, @strong{--help}, @strong{-?} -@anchor{install-tl @strong{-help}@comma{} @strong{--help}@comma{} @strong{-?}} - -Display this help and exit. (This help is also on the web at -@url{https://tug.org/texlive/doc/install-tl.html}). Sometimes the @code{perldoc} -and/or @code{PAGER} programs on the system have problems, possibly resulting -in control characters being literally output. This can't always be -detected, but you can set the @code{NOPERLDOC} environment variable and -@code{perldoc} will not be used. - -@item @strong{-in-place} -@anchor{install-tl @strong{-in-place}} - -This is a quick-and-dirty installation option in case you already have -an rsync or svn checkout of TeX Live. It will use the checkout as-is -and will just do the necessary post-install. Be warned that the file -@code{tlpkg/texlive.tlpdb} may be rewritten, that removal has to be done -manually, and that the only realistic way to maintain this installation -is to redo it from time to time. This option is not available via the -installer interfaces. USE AT YOUR OWN RISK. - -@item @strong{-init-from-profile} @emph{profile_file} -@anchor{install-tl @strong{-init-from-profile} @emph{profile_file}} - -Similar to @strong{-profile} (see @ref{install-tl PROFILES,, PROFILES} below), but only initializes -the installation configuration from @emph{profile_file} and then starts a -normal interactive session. Environment variables are not ignored. - -@item @strong{-logfile} @emph{file} -@anchor{install-tl @strong{-logfile} @emph{file}} - -Write both all messages (informational, debugging, warnings) to @emph{file}, -in addition to standard output or standard error. - -If this option is not given, the installer will create a log file -in the root of the writable installation tree, -for example, @code{/usr/local/texlive/YYYY/install-tl.log} for the @emph{YYYY} -release. - -@item @strong{-no-cls} -@anchor{install-tl @strong{-no-cls}} - -For the text mode installer only: do not clear the screen when entering -a new menu (for debugging purposes). - -@item @strong{-no-persistent-downloads} -@anchor{install-tl @strong{-no-persistent-downloads}} - -@item @strong{-persistent-downloads} -@anchor{install-tl @strong{-persistent-downloads}} - -For network installs, activating this option makes the installer try to -set up a persistent connection using the @code{Net::LWP} Perl module. This -opens only one connection between your computer and the server per -session and reuses it, instead of initiating a new download for each -package, which typically yields a significant speed-up. - -This option is turned on by default, and the installation program will -fall back to using @code{wget} if this is not possible. To disable usage of -LWP and persistent connections, use @code{-no-persistent-downloads}. - -@item @strong{-no-verify-downloads} -@anchor{install-tl @strong{-no-verify-downloads}} - -By default, if a GnuPG @code{gpg} binary is found in PATH, downloads are -verified against a cryptographic signature. This option disables such -verification. The full description is in the Crytographic Verification -section of the @code{tlmgr} documentation, e.g., -@url{https://tug.org/texlive/doc/tlmgr.html#CRYPTOGRAPHIC-VERIFICATION} - -@item @strong{-non-admin} -@anchor{install-tl @strong{-non-admin}} - -For Windows only: configure for the current user, not for all users. - -@item @strong{-portable} -@anchor{install-tl @strong{-portable}} - -Install for portable use, e.g., on a USB stick. Also selectable from -within the perltk and text installers. - -@item @strong{-print-platform} -@anchor{install-tl @strong{-print-platform}} - -Print the TeX Live identifier for the detected platform -(hardware/operating system) combination to standard output, and exit. -@code{-print-arch} is a synonym. - -@item @strong{-profile} @emph{profile_file} -@anchor{install-tl @strong{-profile} @emph{profile_file}} - -Load @emph{profile_file} and do the installation with no user interaction, -that is, a batch (unattended) install. Environment variables are -ignored. See @ref{install-tl PROFILES,, PROFILES} below. - -@item @strong{-q} -@anchor{install-tl @strong{-q}} - -Omit normal informational messages. - -@item @strong{-scheme} @emph{scheme} -@anchor{install-tl @strong{-scheme} @emph{scheme}} - -Schemes are the highest level of package grouping in TeX Live; the -default is to use the @code{full} scheme, which includes everything. This -option overrides that default. You can change the scheme again before -the actual installation with the usual menu. The @emph{scheme} argument may -optionally have a prefix @code{scheme-}. The list of supported scheme names -depends on what your package repository provides; see the interactive -menu list. - -@item @strong{-v} -@anchor{install-tl @strong{-v}} - -Include verbose debugging messages; repeat for maximum debugging: @code{-v --v}. (Further repeats are accepted but ignored.) - -@item @strong{-version}, @strong{--version} -@anchor{install-tl @strong{-version}@comma{} @strong{--version}} - -Output version information and exit. If @code{-v} is also given, the -versions of the TeX Live modules used are also reported. - -@end table - -@node install-tl PROFILES -@appendixsec PROFILES - -A @emph{profile} file contains all the values needed to perform an -installation. After a normal installation has finished, a profile for -that exact installation is written to the file @code{tlpkg/texlive.profile}. -In addition, from the text menu one can select @code{P} to save the current -setup as a profile at any time. - -Such a profile file can be given as the argument to @code{-profile}, for -example to redo the exact same installation on a different system. -Alternatively, you can use a custom profile, most easily created by -starting from a generated one and changing values, or an empty file, -which will take all the defaults. - -As mentioned above, the installer only supports selection by scheme and -collections, not individual packages, so packages cannot be specified in -profile files either. Use @code{tlmgr} to work at the package level. - -Within a profile file, each line consists of - -@emph{variable} [@emph{value}] - -except for comment lines starting with @code{#}. The possible variable -names are listed below. Values, when present, are either @code{0} or @code{1} -for booleans, or strings (which must be specified without any quote -characters). Leading whitespace is ignored. - -If the variable @code{selected_scheme} is defined and @emph{no} collection -variables at all are defined, then the collections required by the -specified scheme (which might change over time) are installed, without -explicitly listing them. This eases maintenance of profile files. If -any collections are specified in a profile, though, then all desired -collections must be given explicitly. - -For example, a line - -@verbatim - selected_scheme scheme-small -@end verbatim - -along with definitions for the installation directories (given below -under "path options") suffices to install the "small" scheme with all -default options. The schemes are described in the @code{S} menu in the -text installer, or equivalent. - -Besides @code{selected_scheme}, here is the list of variable names supported -in a profile: - -@strong{collection options} (prefix @code{collection-}) - -Collections are specified with a variable name with the prefix -@code{collection-} followed by a collection name; there is no value. For -instance, @code{collection-basic}. The collections are described in the -@code{C} menu. - -Schemes and collections (and packages) are ultimately defined by the -files in the @code{tlpkg/tlpsrc/} source directory. - -@strong{path options} - -It is best to define all of these, even though they may not be used in -the installation, so as to avoid unintentionally getting a default value -that could cause problems later. - -@verbatim - TEXDIR - TEXMFCONFIG - TEXMFVAR - TEXMFHOME - TEXMFLOCAL - TEXMFSYSCONFIG - TEXMFSYSVAR -@end verbatim - -@strong{installer options} (prefix @code{instopt_}) - -@table @asis -@item @code{instopt_adjustpath} (default 0 on Unix, 1 on Windows) -@anchor{install-tl @code{instopt_adjustpath} (default 0 on Unix@comma{} 1 on Windows)} - -Adjust @code{PATH} environment variable. - -@item @code{instopt_adjustrepo} (default 1) -@anchor{install-tl @code{instopt_adjustrepo} (default 1)} - -Set remote repository to a multiplexed CTAN mirror after installation; -see @code{-repository} above. - -@item @code{instopt_letter} (default 0) -@anchor{install-tl @code{instopt_letter} (default 0)} - -Set letter size paper as the default, instead of a4. - -@item @code{instopt_portable} (default 0) -@anchor{install-tl @code{instopt_portable} (default 0)} - -Install for portable use, e.g., on a USB stick. - -@item @code{instopt_write18_restricted} (default 1) -@anchor{install-tl @code{instopt_write18_restricted} (default 1)} - -Enable @code{\write18} for a restricted set of programs. - -@end table - -@strong{tlpdb options} (prefix @code{tlpdbopt_}) - -The definitive list is given in @code{tlpkg/TeXLive/TLConfig.pm}, in the hash -@code{%TeXLive::TLConfig::TLPDBOptions}, together with explanations. All -items given there @emph{except} for @code{tlpdbopt_location} can be specified. -Here is the current list: - -@verbatim - tlpdbopt_autobackup - tlpdbopt_backupdir - tlpdbopt_create_formats - tlpdbopt_desktop_integration - tlpdbopt_file_assocs - tlpdbopt_generate_updmap - tlpdbopt_install_docfiles - tlpdbopt_install_srcfiles - tlpdbopt_post_code - tlpdbopt_sys_bin - tlpdbopt_sys_info - tlpdbopt_sys_man - tlpdbopt_w32_multi_user -@end verbatim - -@strong{platform options} (prefix @code{binary_}) - -For each supported platform in TeX Live (directories under @code{bin/}), the -variable @code{binary_}@emph{PLATFORM} can be set with value 1. For example: - -@verbatim - binary_x86_64-linux 1 -@end verbatim - -If no @code{binary_} settings are made, the default is whatever the -current machine is running. - -In releases before 2017, many profile variables had different -names (not documented here; see the @code{install-tl} source). They are -accepted and transformed to the names given above. When a profile is -written, the names above are always used. - -For more details on all of the above options, consult the TeX Live -installation manual, linked from @url{https://tug.org/texlive/doc}. - -@node install-tl ENVIRONMENT VARIABLES -@appendixsec ENVIRONMENT VARIABLES - -For ease in scripting and debugging, @code{install-tl} looks for the -following environment variables. They are not of interest for normal -user installations. - -@table @asis -@item @code{TEXLIVE_DOWNLOADER} -@anchor{install-tl @code{TEXLIVE_DOWNLOADER}} - -@item @code{TL_DOWNLOAD_PROGRAM} -@anchor{install-tl @code{TL_DOWNLOAD_PROGRAM}} - -@item @code{TL_DOWNLOAD_ARGS} -@anchor{install-tl @code{TL_DOWNLOAD_ARGS}} - -These override the normal choice of a download program; see the @code{tlmgr} -documentation, e.g., -@url{https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT-VARIABLES}. - -@item @code{TEXLIVE_INSTALL_ENV_NOCHECK} -@anchor{install-tl @code{TEXLIVE_INSTALL_ENV_NOCHECK}} - -Omit the check for environment variables containing the string @code{tex}. -People developing TeX-related software are likely to have many such -variables. - -@item @code{TEXLIVE_INSTALL_NO_CONTEXT_CACHE} -@anchor{install-tl @code{TEXLIVE_INSTALL_NO_CONTEXT_CACHE}} - -Omit creating the ConTeXt cache. This is useful for redistributors. - -@item @code{TEXLIVE_INSTALL_NO_IMPORT} -@anchor{install-tl @code{TEXLIVE_INSTALL_NO_IMPORT}} - -Omit check for installing on top of a previous installation and then -asking about importing previous settings. - -@item @code{TEXLIVE_INSTALL_NO_WELCOME} -@anchor{install-tl @code{TEXLIVE_INSTALL_NO_WELCOME}} - -Omit printing the welcome message after successful installation, e.g., -when testing. - -@item @code{TEXLIVE_INSTALL_PREFIX} -@anchor{install-tl @code{TEXLIVE_INSTALL_PREFIX}} - -@item @code{TEXLIVE_INSTALL_TEXDIR} -@anchor{install-tl @code{TEXLIVE_INSTALL_TEXDIR}} - -@item @code{TEXLIVE_INSTALL_TEXMFCONFIG} -@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFCONFIG}} - -@item @code{TEXLIVE_INSTALL_TEXMFVAR} -@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFVAR}} - -@item @code{TEXLIVE_INSTALL_TEXMFHOME} -@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFHOME}} - -@item @code{TEXLIVE_INSTALL_TEXMFLOCAL} -@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFLOCAL}} - -@item @code{TEXLIVE_INSTALL_TEXMFSYSCONFIG} -@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFSYSCONFIG}} - -@item @code{TEXLIVE_INSTALL_TEXMFSYSVAR} -@anchor{install-tl @code{TEXLIVE_INSTALL_TEXMFSYSVAR}} - -Specify the respective directories. @code{TEXLIVE_INSTALL_PREFIX} defaults -to @code{/usr/local/texlive}, while @code{TEXLIVE_INSTALL_TEXDIR} defaults to -the release directory within that prefix, e.g., -@code{/usr/local/texlive/2016}. All the defaults can be seen by running the -installer interactively and then typing @code{D} for the directory menu. - -@item @code{NOPERLDOC} -@anchor{install-tl @code{NOPERLDOC}} - -Don't try to run the @code{--help} message through @code{perldoc}. - -@end table - -@node install-tl AUTHORS AND COPYRIGHT -@appendixsec AUTHORS AND COPYRIGHT - -This script and its documentation were written for the TeX Live -distribution (@url{https://tug.org/texlive}) and both are licensed under the -GNU General Public License Version 2 or later. - -$Id: install-tl 54143 2020-03-06 23:51:18Z karl $ - diff --git a/Build/source/doc/tlbuild-incl/tlmgr.texi b/Build/source/doc/tlbuild-incl/tlmgr.texi deleted file mode 100644 index 690b33848d6..00000000000 --- a/Build/source/doc/tlbuild-incl/tlmgr.texi +++ /dev/null @@ -1,2742 +0,0 @@ -@node tlmgr -@appendix tlmgr - -@menu -* tlmgr NAME:: -* tlmgr SYNOPSIS:: -* tlmgr DESCRIPTION:: -* tlmgr EXAMPLES:: -* tlmgr OPTIONS:: -* tlmgr ACTIONS:: -* tlmgr CONFIGURATION FILE FOR TLMGR:: -* tlmgr CRYPTOGRAPHIC VERIFICATION:: -* tlmgr USER MODE:: -* tlmgr MULTIPLE REPOSITORIES:: -* tlmgr GUI FOR TLMGR:: -* tlmgr MACHINE-READABLE OUTPUT:: -* tlmgr ENVIRONMENT VARIABLES:: -* tlmgr AUTHORS AND COPYRIGHT:: -@end menu - -@node tlmgr NAME -@appendixsec NAME - -tlmgr - the native TeX Live Manager - -@node tlmgr SYNOPSIS -@appendixsec SYNOPSIS - -tlmgr [@emph{option}...] @emph{action} [@emph{option}...] [@emph{operand}...] - -@node tlmgr DESCRIPTION -@appendixsec DESCRIPTION - -@strong{tlmgr} manages an existing TeX Live installation, both packages and -configuration options. For information on initially downloading and -installing TeX Live, see @url{https://tug.org/texlive/acquire.html}. - -The most up-to-date version of this documentation (updated nightly from -the development sources) is available at -@url{https://tug.org/texlive/tlmgr.html}, along with procedures for updating -@code{tlmgr} itself and information about test versions. - -TeX Live is organized into a few top-level @emph{schemes}, each of which is -specified as a different set of @emph{collections} and @emph{packages}, 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. - -See @url{https://tug.org/texlive/doc} for all the TeX Live documentation -available. - -@node tlmgr EXAMPLES -@appendixsec EXAMPLES - -After successfully installing TeX Live, here are a few common operations -with @code{tlmgr}: - -@table @asis -@item @code{tlmgr option repository ctan} -@anchor{tlmgr @code{tlmgr option repository ctan}} - -@item @code{tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet} -@anchor{tlmgr @code{tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet}} - -Tell @code{tlmgr} to use a nearby CTAN mirror for future updates; useful if -you installed TeX Live from the DVD image and want to have continuing -updates. The two commands are equivalent; @code{ctan} is just an alias for -the given url. - -Caveat: @code{mirror.ctan.org} resolves to many different hosts, and they -are not perfectly synchronized; we recommend updating only daily (at -most), and not more often. You can choose a particular mirror if -problems; the list of all CTAN mirrors with the status of each is at -@url{https://ctan.org/mirrors/mirmon}. - -@item @code{tlmgr update --list} -@anchor{tlmgr @code{tlmgr update --list}} - -Report what would be updated without actually updating anything. - -@item @code{tlmgr update --all} -@anchor{tlmgr @code{tlmgr update --all}} - -Make your local TeX installation correspond to what is in the package -repository (typically useful when updating from CTAN). - -@item @code{tlmgr info} @emph{what} -@anchor{tlmgr @code{tlmgr info} @emph{what}} - -Display detailed information about a package @emph{what}, such as the installation -status and description, of searches for @emph{what} in all packages. - -@end table - -For all the capabilities and details of @code{tlmgr}, please read the -following voluminous information. - -@node tlmgr OPTIONS -@appendixsec OPTIONS - -The following options to @code{tlmgr} 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, -@code{--}@emph{option} and @code{-}@emph{option} are equivalent, and an @code{=} is optional -between an option name and its value. - -@table @asis -@item @strong{--repository} @emph{url|path} -@anchor{tlmgr @strong{--repository} @emph{url|path}} - -Specify the package repository from which packages should be installed -or updated, either a local directory or network location, as below. This -overridesthe default package repository found in the installation's TeX -Live Package Database (a.k.a. the TLPDB, which is given entirely in the -file @code{tlpkg/texlive.tlpdb}). - -This @code{--repository} option changes the location only for the current -run; to make a permanent change, use @code{option repository} (see the -@ref{tlmgr option,, option} action). - -As an example, you can choose a particular CTAN mirror with something -like this: - -@verbatim - -repository http://ctan.example.org/its/ctan/dir/systems/texlive/tlnet -@end verbatim - -Of course a real hostname and its particular top-level CTAN directory -have to be specified. The list of CTAN mirrors is available at -@url{https://ctan.org/mirrors/mirmon}. - -Here's an example of using a local directory: - -@verbatim - -repository /local/TL/repository -@end verbatim - -For backward compatibility and convenience, @code{--location} and @code{--repo} -are accepted as aliases for this option. - -Locations can be specified as any of the following: - -@table @asis -@item @code{/some/local/dir} -@anchor{tlmgr @code{/some/local/dir}} - -@item @code{file:/some/local/dir} -@anchor{tlmgr @code{file:/some/local/dir}} - -Equivalent ways of specifying a local directory. - -@item @code{ctan} -@anchor{tlmgr @code{ctan}} - -@item @code{http://mirror.ctan.org/systems/texlive/tlnet} -@anchor{tlmgr @code{http://mirror.ctan.org/systems/texlive/tlnet}} - -Pick a CTAN mirror automatically, trying for one that is both nearby and -up-to-date. The chosen mirror is used for the entire download. The bare -@code{ctan} is merely an alias for the full url. (See @url{https://ctan.org} for -more about CTAN and its mirrors.) - -@item @code{http://server/path/to/tlnet} -@anchor{tlmgr @code{http://server/path/to/tlnet}} - -Standard HTTP. If the (default) LWP method is used, persistent -connections are supported. TL can also use @code{curl} or @code{wget} to do the -downloads, or an arbitrary user-specified program, as described in the -@code{tlmgr} documentation -(@url{https://tug.org/texlive/doc/tlmgr.html#ENVIRONMENT-VARIABLES}). - -@item @code{https://server/path/to/tlnet} -@anchor{tlmgr @code{https://server/path/to/tlnet}} - -Again, if the (default) LWP method is used, this supports persistent -connections. Unfortunately, some versions of @code{wget} and @code{curl} do not -support https, and even when @code{wget} supports https, certificates may be -rejected even when the certificate is fine, due to a lack of local -certificate roots. The simplest workaround for this problem is to use -http or ftp. - -@item @code{ftp://server/path/to/tlnet} -@anchor{tlmgr @code{ftp://server/path/to/tlnet}} - -If the (default) LWP method is used, persistent connections are -supported. - -@item @code{user@@machine:/path/to/tlnet} -@anchor{tlmgr @code{user@@machine:/path/to/tlnet}} - -@item @code{scp://user@@machine/path/to/tlnet} -@anchor{tlmgr @code{scp://user@@machine/path/to/tlnet}} - -@item @code{ssh://user@@machine/path/to/tlnet} -@anchor{tlmgr @code{ssh://user@@machine/path/to/tlnet}} - -These forms are equivalent; they all use @code{scp} to transfer files. Using -@code{ssh-agent} is recommended. (Info: -@url{https://en.wikipedia.org/wiki/OpenSSH}, -@url{https://en.wikipedia.org/wiki/Ssh-agent}.) - -@end table - -If the repository is on the network, trailing @code{/} characters and/or -trailing @code{/tlpkg} and/or @code{/archive} components are ignored. - -@item @strong{--gui} [@emph{action}] -@anchor{tlmgr @strong{--gui} [@emph{action}]} - -Two notable GUI front-ends for @code{tlmgr}, @code{tlshell} and @code{tlcockpit}, -are started up as separate programs; see their own documentation. - -@code{tlmgr} itself has a graphical interface as well as the command line -interface. You can give the option to invoke it, @code{--gui}, together with -an action to be brought directly into the respective screen of the GUI. -For example, running - -@verbatim - tlmgr --gui update -@end verbatim - -starts you directly at the update screen. If no action is given, the -GUI will be started at the main screen. See @ref{tlmgr GUI FOR TLMGR,, GUI FOR TLMGR}. - -However, the native GUI requires Perl/TK, which is no longer included in -TeX Live's Perl distribution for Windows. You may find @code{tlshell} or -@code{tlcockpit} easier to work with. - -@item @strong{--gui-lang} @emph{llcode} -@anchor{tlmgr @strong{--gui-lang} @emph{llcode}} - -By default, the GUI tries to deduce your language from the environment -(on Windows via the registry, on Unix via @code{LC_MESSAGES}). If that fails -you can select a different language by giving this option with a -language code (based on ISO 639-1). Currently supported (but not -necessarily completely translated) are: @w{English (en, default)}, -@w{Czech (cs)}, @w{German (de)}, @w{French (fr)}, @w{Italian (it)}, -@w{Japanese (ja)}, @w{Dutch (nl)}, @w{Polish (pl)}, @w{Brazilian Portuguese -(pt_BR)}, @w{Russian (ru)}, @w{Slovak (sk)}, @w{Slovenian (sl)}, @w{Serbian -(sr)}, @w{Ukrainian (uk)}, @w{Vietnamese (vi)}, @w{simplified Chinese -(zh_CN)}, and @w{traditional Chinese (zh_TW)}. - -tlshell shares its message catalog with tlmgr. - -@item @strong{--debug-translation} -@anchor{tlmgr @strong{--debug-translation}} - -In GUI mode, this switch tells @code{tlmgr} to report any untranslated (or -missing) messages to standard error. This can help translators to see -what remains to be done. - -@item @strong{--machine-readable} -@anchor{tlmgr @strong{--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 @ref{tlmgr MACHINE-READABLE OUTPUT,, MACHINE-READABLE OUTPUT} section below. - -@item @strong{--no-execute-actions} -@anchor{tlmgr @strong{--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. - -@item @strong{--package-logfile} @emph{file} -@anchor{tlmgr @strong{--package-logfile} @emph{file}} - -@code{tlmgr} logs all package actions (install, remove, update, failed -updates, failed restores) to a separate log file, by default -@code{TEXMFSYSVAR/web2c/tlmgr.log}. This option allows you to specify a -different file for the log. - -@item @strong{--pause} -@anchor{tlmgr @strong{--pause}} - -This option makes @code{tlmgr} wait for user input before exiting. Useful on -Windows to avoid disappearing command windows. - -@item @strong{--persistent-downloads} -@anchor{tlmgr @strong{--persistent-downloads}} - -@item @strong{--no-persistent-downloads} -@anchor{tlmgr @strong{--no-persistent-downloads}} - -For network-based installations, this option (on by default) makes -@code{tlmgr} try to set up a persistent connection (using the @code{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. - -If this is not possible, @code{tlmgr} will fall back to using @code{wget}. To -disable these persistent connections, use @code{--no-persistent-downloads}. - -@item @strong{--pin-file} -@anchor{tlmgr @strong{--pin-file}} - -Change the pinning file location from @code{TEXMFLOCAL/tlpkg/pinning.txt} -(see @ref{tlmgr Pinning,, Pinning} below). Documented only for completeness, as this is -only useful in debugging. - -@item @strong{--usermode} -@anchor{tlmgr @strong{--usermode}} - -Activates user mode for this run of @code{tlmgr}; see @ref{tlmgr USER MODE,, USER MODE} below. - -@item @strong{--usertree} @emph{dir} -@anchor{tlmgr @strong{--usertree} @emph{dir}} - -Uses @emph{dir} for the tree in user mode; see @ref{tlmgr USER MODE,, USER MODE} below. - -@item @strong{--verify-repo=[none|main|all]} -@anchor{tlmgr @strong{--verify-repo=[none|main|all]}} - -Defines the level of verification done: If @code{none} is specified, no -verification whatsoever is done. If @code{main} is given and a working GnuPG -(@code{gpg}) binary is available, all repositories are checked, but only the -main repository is required to be signed. If @code{all} is given, then all -repositories need to be signed. See @ref{tlmgr CRYPTOGRAPHIC VERIFICATION,, CRYPTOGRAPHIC VERIFICATION} below -for details. - -@end table - -The standard options for TeX Live programs are also accepted: -@code{--help/-h/-?}, @code{--version}, @code{-q} (no informational messages), @code{-v} -(debugging messages, can be repeated). For the details about these, see -the @code{TeXLive::TLUtils} documentation. - -The @code{--version} option shows version information about the TeX Live -release and about the @code{tlmgr} script itself. If @code{-v} is also given, -revision number for the loaded TeX Live Perl modules are shown, too. - -@node tlmgr ACTIONS -@appendixsec ACTIONS - -@menu -* tlmgr help:: -* tlmgr version:: -* tlmgr backup:: -* tlmgr candidates @emph{pkg}:: -* tlmgr check [@emph{option}...] [depends|executes|files|runfiles|texmfdbs|all]:: -* tlmgr conf:: -* tlmgr dump-tlpdb [@emph{option}...] [--json]:: -* tlmgr generate:: -* tlmgr gui:: -* tlmgr info:: -* tlmgr init-usertree:: -* tlmgr install [@emph{option}...] @emph{pkg}...:: -* tlmgr key:: -* tlmgr list:: -* tlmgr option:: -* tlmgr paper:: -* tlmgr path:: -* tlmgr pinning:: -* tlmgr platform:: -* tlmgr postaction:: -* tlmgr print-platform:: -* tlmgr print-platform-info:: -* tlmgr remove [@emph{option}...] @emph{pkg}...:: -* tlmgr repository:: -* tlmgr restore:: -* tlmgr search:: -* tlmgr shell:: -* tlmgr show:: -* tlmgr uninstall:: -* tlmgr update [@emph{option}...] [@emph{pkg}...]:: -@end menu - -@node tlmgr help -@appendixsubsec help - -Display this help information and exit (same as @code{--help}, and on the -web at @url{https://tug.org/texlive/doc/tlmgr.html}). Sometimes the -@code{perldoc} and/or @code{PAGER} programs on the system have problems, -resulting in control characters being literally output. This can't -always be detected, but you can set the @code{NOPERLDOC} environment -variable and @code{perldoc} will not be used. - -@node tlmgr version -@appendixsubsec version - -Gives version information (same as @code{--version}). - -If @code{-v} has been given the revisions of the used modules are reported, too. - -@node tlmgr backup -@appendixsubsec backup - -@table @asis -@item @strong{backup [@emph{option}...] --all} -@anchor{tlmgr @strong{backup [@emph{option}...] --all}} - -@item @strong{backup [@emph{option}...] @emph{pkg}...} -@anchor{tlmgr @strong{backup [@emph{option}...] @emph{pkg}...}} - -If the @code{--clean} option is not specified, this action makes a backup of -the given packages, or all packages given @code{--all}. These backups are -saved to the value of the @code{--backupdir} option, if that is an existing -and writable directory. If @code{--backupdir} is not given, the @code{backupdir} -option setting in the TLPDB is used, if present. If both are missing, no -backups are made. (The installer sets @code{backupdir} to -@code{.../tlpkg/backups}, under the TL root installation directory, so it is -usually defined; see the @ref{tlmgr option,, option} description for more information.) - -If the @code{--clean} option is specified, backups are pruned (removed) -instead of saved. The optional integer value @emph{N} may be specified to -set the number of backups that will be retained when cleaning. If @code{N} -is not given, the value of the @code{autobackup} option is used. If both are -missing, an error is issued. For more details of backup pruning, see -the @code{option} action. - -Options: - -@table @asis -@item @strong{--backupdir} @emph{directory} -@anchor{tlmgr @strong{--backupdir} @emph{directory}} - -Overrides the @code{backupdir} option setting in the TLPDB. -The @emph{directory} argument is required and must specify an existing, -writable directory where backups are to be placed. - -@item @strong{--all} -@anchor{tlmgr @strong{--all}} - -If @code{--clean} 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 -@code{--clean} is specified, all packages are pruned. - -@item @strong{--clean}[=@emph{N}] -@anchor{tlmgr @strong{--clean}[=@emph{N}]} - -Instead of making backups, prune the backup directory of old backups, as -explained above. The optional integer argument @emph{N} overrides the -@code{autobackup} option set in the TLPDB. You must use @code{--all} or a list -of packages together with this option, as desired. - -@item @strong{--dry-run} -@anchor{tlmgr @strong{--dry-run}} - -Nothing is actually backed up or removed; instead, the actions to be -performed are written to the terminal. - -@end table - -@end table - -@node tlmgr candidates @emph{pkg} -@appendixsubsec candidates @emph{pkg} - -Shows the available candidate repositories for package @emph{pkg}. -See @ref{tlmgr MULTIPLE REPOSITORIES,, MULTIPLE REPOSITORIES} below. - -@node tlmgr check [@emph{option}...] [depends|executes|files|runfiles|texmfdbs|all] -@appendixsubsec check [@emph{option}...] [depends|executes|files|runfiles|texmfdbs|all] - -Execute one (or all) check(s) of the consistency of the installation. -If no problems are found, there will be no output. (To get a view of -what is being done, run @code{tlmgr -v check}.) - -@table @asis -@item @strong{depends} -@anchor{tlmgr @strong{depends}} - -Lists those packages which occur as dependencies in an installed collection, -but are themselves not installed, and those packages which are not -contained in any collection. - -If you call @code{tlmgr check collections} this test will be carried out -instead since former versions for @code{tlmgr} called it that way. - -@item @strong{executes} -@anchor{tlmgr @strong{executes}} - -Check that the files referred to by @code{execute} directives in the TeX -Live Database are present. - -@item @strong{files} -@anchor{tlmgr @strong{files}} - -Checks that all files listed in the local TLPDB (@code{texlive.tlpdb}) are -actually present, and lists those missing. - -@item @strong{runfiles} -@anchor{tlmgr @strong{runfiles}} - -List those filenames that are occurring more than one time in the -runfiles sections, except for known duplicates. - -@item @strong{texmfdbs} -@anchor{tlmgr @strong{texmfdbs}} - -Checks related to the @code{ls-R} files. If you have defined new trees, or -changed the @code{TEXMF} or @code{TEXMFDBS} variables, it can't hurt to run -this. It checks that: - -@table @asis -@item - all items in @code{TEXMFDBS} have the @code{!!} prefix. -@anchor{tlmgr - all items in @code{TEXMFDBS} have the @code{!!} prefix.} - -@item - all items in @code{TEXMFBDS} have an @code{ls-R} file (if they exist at all). -@anchor{tlmgr - all items in @code{TEXMFBDS} have an @code{ls-R} file (if they exist at all).} - -@item - all items in @code{TEXMF} with @code{!!} are listed in @code{TEXMFDBS}. -@anchor{tlmgr - all items in @code{TEXMF} with @code{!!} are listed in @code{TEXMFDBS}.} - -@item - all items in @code{TEXMF} with an @code{ls-R} file are listed in @code{TEXMFDBS}. -@anchor{tlmgr - all items in @code{TEXMF} with an @code{ls-R} file are listed in @code{TEXMFDBS}.} - -@end table - -@end table - -Options: - -@table @asis -@item @strong{--use-svn} -@anchor{tlmgr @strong{--use-svn}} - -Use the output of @code{svn status} instead of listing the files; for -checking the TL development repository. (This is run nightly.) - -@end table - -@node tlmgr conf -@appendixsubsec conf - -@table @asis -@item @strong{conf [texmf|tlmgr|updmap [--conffile @emph{file}] [--delete] [@emph{key} [@emph{value}]]]} -@anchor{tlmgr @strong{conf [texmf|tlmgr|updmap [--conffile @emph{file}] [--delete] [@emph{key} [@emph{value}]]]}} - -@item @strong{conf auxtrees [--conffile @emph{file}] [show|add|remove] [@emph{value}]} -@anchor{tlmgr @strong{conf auxtrees [--conffile @emph{file}] [show|add|remove] [@emph{value}]}} - -With only @code{conf}, show general configuration information for TeX Live, -including active configuration files, path settings, and more. This is -like running @code{texconfig conf}, but works on all supported platforms. - -With one of @code{conf texmf}, @code{conf tlmgr}, or @code{conf updmap}, shows all -key/value pairs (i.e., all settings) as saved in @code{ROOT/texmf.cnf}, the -user-specific @code{tlmgr} configuration file (see below), or the first -found (via @code{kpsewhich}) @code{updmap.cfg} file, respectively. - -If @emph{key} is given in addition, shows the value of only that @emph{key} in -the respective file. If option @emph{--delete} is also given, the value in -the given configuration file is entirely removed (not just commented -out). - -If @emph{value} is given in addition, @emph{key} is set to @emph{value} in the -respective file. @emph{No error checking is done!} - -The @code{PATH} value shown by @code{conf} is as used by @code{tlmgr}. The -directory in which the @code{tlmgr} executable is found is automatically -prepended to the PATH value inherited from the environment. - -Here is a practical example of changing configuration values. If the -execution of (some or all) system commands via @code{\write18} was left -enabled during installation, you can disable it afterwards: - -@verbatim - tlmgr conf texmf shell_escape 0 -@end verbatim - -The subcommand @code{auxtrees} allows adding and removing arbitrary -additional texmf trees, completely under user control. @code{auxtrees show} -shows the list of additional trees, @code{auxtrees add} @emph{tree} adds a tree -to the list, and @code{auxtrees remove} @emph{tree} removes a tree from the list -(if present). The trees should not contain an @code{ls-R} file (or files -will not be found if the @code{ls-R} becomes stale). This works by -manipulating the Kpathsea variable @code{TEXMFAUXTREES}, in (by default) -@code{ROOT/texmf.cnf}. Example: - -@verbatim - tlmgr conf auxtrees add /quick/test/tree - tlmgr conf auxtrees remove /quick/test/tree -@end verbatim - -In all cases the configuration file can be explicitly specified via the -option @code{--conffile} @emph{file}, e.g., if you don't want to change the -system-wide configuration. - -Warning: The general facility for changing configuration values is here, -but tinkering with settings in this way is strongly discouraged. Again, -no error checking on either keys or values is done, so any sort of -breakage is possible. - -@end table - -@node tlmgr dump-tlpdb [@emph{option}...] [--json] -@appendixsubsec dump-tlpdb [@emph{option}...] [--json] - -Dump complete local or remote TLPDB to standard output, as-is. The -output is analogous to the @code{--machine-readable} output; see -@ref{tlmgr MACHINE-READABLE OUTPUT,, MACHINE-READABLE OUTPUT} section. - -Options: - -@table @asis -@item @strong{--local} -@anchor{tlmgr @strong{--local}} - -Dump the local TLPDB. - -@item @strong{--remote} -@anchor{tlmgr @strong{--remote}} - -Dump the remote TLPDB. - -@item @strong{--json} -@anchor{tlmgr @strong{--json}} - -Instead of dumping the actual content, the database is dumped as -JSON. For the format of JSON output see @code{tlpkg/doc/JSON-formats.txt}, -format definition @code{TLPDB}. - -@end table - -Exactly one of @code{--local} and @code{--remote} must be given. - -In either case, the first line of the output specifies the repository -location, in this format: - -@verbatim - "location-url" "\t" location -@end verbatim - -where @code{location-url} is the literal field name, followed by a tab, and -@emph{location} is the file or url to the repository. - -Line endings may be either LF or CRLF depending on the current platform. - -@node tlmgr generate -@appendixsubsec generate - -@table @asis -@item @strong{generate [@emph{option}...] language} -@anchor{tlmgr @strong{generate [@emph{option}...] language}} - -@item @strong{generate [@emph{option}...] language.dat} -@anchor{tlmgr @strong{generate [@emph{option}...] language.dat}} - -@item @strong{generate [@emph{option}...] language.def} -@anchor{tlmgr @strong{generate [@emph{option}...] language.def}} - -@item @strong{generate [@emph{option}...] language.dat.lua} -@anchor{tlmgr @strong{generate [@emph{option}...] language.dat.lua}} - -@end table - -The @code{generate} 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 @code{tlmgr} routinely call @code{generate} for -all of these files. - -For managing your own fonts, please read the @code{updmap --help} -information and/or @url{https://tug.org/fonts/fontinstall.html}. - -For managing your own formats, please read the @code{fmtutil --help} -information. - -In more detail: @code{generate} remakes any of the configuration files -@code{language.dat}, @code{language.def}, and @code{language.dat.lua} -from the information present in the local TLPDB, plus -locally-maintained files. - -The locally-maintained files are @code{language-local.dat}, -@code{language-local.def}, or @code{language-local.dat.lua}, -searched for in @code{TEXMFLOCAL} 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. - -(Historical note: The formerly supported @code{updmap-local.cfg} and -@code{fmtutil-local.cnf} are no longer read, since @code{updmap} and @code{fmtutil} -now reads and supports multiple configuration files. Thus, -local additions can and should be put into an @code{updmap.cfg} of @code{fmtutil.cnf} -file in @code{TEXMFLOCAL}. The @code{generate updmap} and @code{generate fmtutil} actions -no longer exist.) - -Local files specify entries to be disabled with a comment line, namely -one of these: - -@verbatim - %!NAME - --!NAME -@end verbatim - -where @code{language.dat} and @code{language.def} use @code{%}, -and @code{language.dat.lua} use @code{--}. In all cases, the @emph{name} is -the respective format name or hyphenation pattern identifier. -Examples: - -@verbatim - %!german - --!usenglishmax -@end verbatim - -(Of course, you're not likely to actually want to disable those -particular items. They're just examples.) - -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. - -The form @code{generate language} recreates all three files @code{language.dat}, -@code{language.def}, and @code{language.dat.lua}, while the forms with an -extension recreates only that given language file. - -Options: - -@table @asis -@item @strong{--dest} @emph{output_file} -@anchor{tlmgr @strong{--dest} @emph{output_file}} - -specifies the output file (defaults to the respective location in -@code{TEXMFSYSVAR}). If @code{--dest} is given to @code{generate language}, it -serves as a basename onto which @code{.dat} will be appended for the name of -the @code{language.dat} output file, @code{.def} will be appended to the value -for the name of the @code{language.def} output file, and @code{.dat.lua} to the -name of the @code{language.dat.lua} file. (This is just to avoid -overwriting; if you want a specific name for each output file, we -recommend invoking @code{tlmgr} twice.) - -@item @strong{--localcfg} @emph{local_conf_file} -@anchor{tlmgr @strong{--localcfg} @emph{local_conf_file}} - -specifies the (optional) local additions (defaults to the respective -location in @code{TEXMFLOCAL}). - -@item @strong{--rebuild-sys} -@anchor{tlmgr @strong{--rebuild-sys}} - -tells @code{tlmgr} to run necessary programs after config files have been -regenerated. These are: -@code{fmtutil-sys --all} after @code{generate fmtutil}, -@code{fmtutil-sys --byhyphen .../language.dat} after @code{generate language.dat}, -and -@code{fmtutil-sys --byhyphen .../language.def} after @code{generate language.def}. - -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. - -@end table - -The respective locations are as follows: - -@verbatim - 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) -@end verbatim - -@node tlmgr gui -@appendixsubsec gui - -Start the graphical user interface. See @strong{GUI} below. - -@node tlmgr info -@appendixsubsec info - -@table @asis -@item @strong{info [@emph{option}...] @emph{pkg}...} -@anchor{tlmgr @strong{info [@emph{option}...] @emph{pkg}...}} - -@item @strong{info [@emph{option}...] collections} -@anchor{tlmgr @strong{info [@emph{option}...] collections}} - -@item @strong{info [@emph{option}...] schemes} -@anchor{tlmgr @strong{info [@emph{option}...] schemes}} - -With no argument, lists all packages available at the package -repository, prefixing those already installed with @code{i}. - -With the single word @code{collections} or @code{schemes} as the argument, lists -the request type instead of all packages. - -With any other arguments, display information about @emph{pkg}: the name, -category, short and long description, sizes, installation status, and TeX Live -revision number. If @emph{pkg} is not locally installed, searches in the -remote installation source. - -For normal packages (not collections or schemes), the sizes of the four -groups of files (run/src/doc/bin files) are shown separately. For -collections, the cumulative size is shown, including all -directly-dependent packages (but not dependent collections). For -schemes, the cumulative size is also shown, including all -directly-dependent collections and packages. - -If @emph{pkg} is not found locally or remotely, the search action is used -and lists matching packages and files. - -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 @code{revision} value -comes directly from TL and is reliable. - -The former actions @code{show} and @code{list} are merged into this action, -but are still supported for backward compatibility. - -Options: - -@table @asis -@item @strong{--list} -@anchor{tlmgr @strong{--list}} - -If the option @code{--list} 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, @code{--list} outputs their -dependencies in a similar way. - -@item @strong{--only-installed} -@anchor{tlmgr @strong{--only-installed}} - -If this option is given, the installation source will not be used; only -locally installed packages, collections, or schemes are listed. - -@item @strong{--only-remote} -@anchor{tlmgr @strong{--only-remote}} - -Only list packages from the remote repository. Useful when checking what -is available in a remote repository using -@code{tlmgr --repo ... --only-remote info}. Note that -@code{--only-installed} and @code{--only-remote} cannot both be specified. - -@item @strong{--data @code{item1,item2,...}} -@anchor{tlmgr @strong{--data @code{item1@comma{}item2@comma{}...}}} - -If the option @code{--data} is given, its argument must be a comma separated -list of field names from: @code{name}, @code{category}, @code{localrev}, @code{remoterev}, -@code{shortdesc}, @code{longdesc}, @code{installed}, @code{size}, @code{relocatable}, @code{depends}, -@code{cat-version}, @code{cat-date}, or @code{cat-license}. In this case the requested -packages' information is listed in CSV format one package per line, and the -column information is given by the @code{itemN}. The @code{depends} column contains -the name of all dependencies separated by @code{:}. - -@item @strong{--json} -@anchor{tlmgr @strong{--json} 1} - -In case @code{--json} is specified, the output is a -JSON encoded array where each array element is the JSON representation of -a single @code{TLPOBJ} but with additional information. For details see -@code{tlpkg/doc/JSON-formats.txt}, format definition: @code{TLPOBJINFO}. -If both @code{--json} and @code{--data} are given, @code{--json} takes precedence. - -@end table - -@end table - -@node tlmgr init-usertree -@appendixsubsec init-usertree - -Sets up a texmf tree for so-called user mode management, either the -default user tree (@code{TEXMFHOME}), or one specified on the command line -with @code{--usertree}. See @ref{tlmgr USER MODE,, USER MODE} below. - -@node tlmgr install [@emph{option}...] @emph{pkg}... -@appendixsubsec install [@emph{option}...] @emph{pkg}... - -Install each @emph{pkg} given on the command line, if it is not already -installed. It does not touch existing packages; see the @code{update} -action for how to get the latest version of a package. - -By default this also installs all packages on which the given @emph{pkg}s are -dependent. Options: - -@table @asis -@item @strong{--dry-run} -@anchor{tlmgr @strong{--dry-run} 1} - -Nothing is actually installed; instead, the actions to be performed are -written to the terminal. - -@item @strong{--file} -@anchor{tlmgr @strong{--file}} - -Instead of fetching a package from the installation repository, use -the package files given on the command line. These files must -be standard TeX Live package files (with contained tlpobj file). - -@item @strong{--force} -@anchor{tlmgr @strong{--force}} - -If updates to @code{tlmgr} itself (or other parts of the basic -infrastructure) are present, @code{tlmgr} will bail out and not perform the -installation unless this option is given. Not recommended. - -@item @strong{--no-depends} -@anchor{tlmgr @strong{--no-depends}} - -Do not install dependencies. (By default, installing a package ensures -that all dependencies of this package are fulfilled.) - -@item @strong{--no-depends-at-all} -@anchor{tlmgr @strong{--no-depends-at-all}} - -Normally, when you install a package which ships binary files the -respective binary package will also be installed. That is, for a -package @code{foo}, the package @code{foo.i386-linux} will also be installed on -an @code{i386-linux} system. This option suppresses this behavior, and also -implies @code{--no-depends}. Don't use it unless you are sure of what you -are doing. - -@item @strong{--reinstall} -@anchor{tlmgr @strong{--reinstall}} - -Reinstall a package (including dependencies for collections) even if it -already seems to be installed (i.e, is present in the TLPDB). This is -useful to recover from accidental removal of files in the hierarchy. - -When re-installing, only dependencies on normal packages are followed -(i.e., not those of category Scheme or Collection). - -@item @strong{--with-doc} -@anchor{tlmgr @strong{--with-doc}} - -@item @strong{--with-src} -@anchor{tlmgr @strong{--with-src}} - -While not recommended, the @code{install-tl} program provides an option to -omit installation of all documentation and/or source files. (By -default, everything is installed.) After such an installation, you may -find that you want the documentation or source files for a given package -after all. You can get them by using these options in conjunction with -@code{--reinstall}, as in (using the @code{fontspec} package as the example): - -@verbatim - tlmgr install --reinstall --with-doc --with-src fontspec -@end verbatim - -@end table - -This action does not automatically add new symlinks in system -directories; you need to run @code{tlmgr path add} (@ref{tlmgr path,, path}) yourself if -you are using this feature and want new symlinks added. - -@node tlmgr key -@appendixsubsec key - -@table @asis -@item @strong{key list} -@anchor{tlmgr @strong{key list}} - -@item @strong{key add @emph{file}} -@anchor{tlmgr @strong{key add @emph{file}}} - -@item @strong{key remove @emph{keyid}} -@anchor{tlmgr @strong{key remove @emph{keyid}}} - -The action @code{key} allows listing, adding and removing additional GPG -keys to the set of trusted keys, that is, those that are used to verify -the TeX Live databases. - -With the @code{list} argument, @code{key} lists all keys. - -The @code{add} argument requires another argument, either a filename or -@code{-} for stdin, from which the key is added. The key is added to the -local keyring @code{GNUPGHOME/repository-keys.gpg}, which is normally -@code{tlpkg/gpg/repository-keys.gpg}. - -The @code{remove} argument requires a key id and removes the requested id -from the local keyring. - -@end table - -@node tlmgr list -@appendixsubsec list - -Synonym for @ref{tlmgr info,, info}. - -@node tlmgr option -@appendixsubsec option - -@table @asis -@item @strong{option [--json] [show]} -@anchor{tlmgr @strong{option [--json] [show]}} - -@item @strong{option [--json] showall|help} -@anchor{tlmgr @strong{option [--json] showall|help}} - -@item @strong{option @emph{key} [@emph{value}]} -@anchor{tlmgr @strong{option @emph{key} [@emph{value}]}} - -@end table - -The first form, @code{show}, shows the global TeX Live settings currently -saved in the TLPDB with a short description and the @code{key} used for -changing it in parentheses. - -The second form, @code{showall}, is similar, but also shows options which -can be defined but are not currently set to any value (@code{help} is a -synonym). - -Both @code{show...} forms take an option @code{--json}, which dumps the option -information in JSON format. In this case, both forms dump the same -data. For the format of the JSON output see -@code{tlpkg/doc/JSON-formats.txt}, format definition @code{TLOPTION}. - -In the third form, with @emph{key}, if @emph{value} is not given, the setting -for @emph{key} is displayed. If @emph{value} is present, @emph{key} is set to -@emph{value}. - -Possible values for @emph{key} are (run @code{tlmgr option showall} for -the definitive list): - -@verbatim - repository (default package repository), - formats (generate formats at installation or update 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) -@end verbatim - -One common use of @code{option} is to permanently change the installation to -get further updates from the Internet, after originally installing from -DVD. To do this, you can run - -@verbatim - tlmgr option repository http://mirror.ctan.org/systems/texlive/tlnet -@end verbatim - -The @code{install-tl} documentation has more information about the possible -values for @code{repository}. (For backward compatibility, @code{location} can -be used as a synonym for @code{repository}.) - -If @code{formats} 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 how and want to regenerate formats yourself whenever -needed (which is often, in practice). - -The @code{postcode} 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 to developers doing debugging. - -The @code{docfiles} and @code{srcfiles} options control the installation of -their respective file groups (documentation, sources; grouping is -approximate) per package. By default both are enabled (1). Either or -both can be disabled (set to 0) if disk space is limited or for minimal -testing installations, etc. When disabled, the respective files are not -downloaded at all. - -The options @code{autobackup} and @code{backupdir} determine the defaults for -the actions @code{update}, @code{backup} and @code{restore}. These three actions -need a directory in which to read or write the backups. If -@code{--backupdir} is not specified on the command line, the @code{backupdir} -option value is used (if set). The TL installer sets @code{backupdir} to -@code{.../tlpkg/backups}, under the TL root installation directory. - -The @code{autobackup} option (de)activates automatic generation of backups. -Its value is an integer. If the @code{autobackup} value is @code{-1}, no -backups are removed. If @code{autobackup} is 0 or more, it specifies the -number of backups to keep. Thus, backups are disabled if the value is -0. In the @code{--clean} mode of the @code{backup} action this option also -specifies the number to be kept. The default value is 1, so that -backups are made, but only one backup is kept. - -To setup @code{autobackup} to @code{-1} on the command line, use: - -@verbatim - tlmgr option -- autobackup -1 -@end verbatim - -The @code{--} avoids having the @code{-1} treated as an option. (The @code{--} -stops parsing for options at the point where it appears; this is a -general feature across most Unix programs.) - -The @code{sys_bin}, @code{sys_man}, and @code{sys_info} options are used on Unix -systems to control the generation of links for executables, Info files -and man pages. See the @code{path} action for details. - -The last three options affect behavior on Windows installations. If -@code{desktop_integration} is set, then some packages will install items in -a sub-folder of the Start menu for @code{tlmgr gui}, documentation, etc. If -@code{fileassocs} is set, Windows file associations are made (see also the -@code{postaction} action). Finally, if @code{multiuser} 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. - -@node tlmgr paper -@appendixsubsec paper - -@table @asis -@item @strong{paper [a4|letter]} -@anchor{tlmgr @strong{paper [a4|letter]}} - -@item @strong{<[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [@emph{papersize}|--list]}> -@anchor{tlmgr @strong{<[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [@emph{papersize}|--list]}>} - -@item @strong{paper --json} -@anchor{tlmgr @strong{paper --json}} - -@end table - -With no arguments (@code{tlmgr paper}), shows the default paper size setting -for all known programs. - -With one argument (e.g., @code{tlmgr paper a4}), sets the default for all -known programs to that paper size. - -With a program given as the first argument and no paper size specified -(e.g., @code{tlmgr dvips paper}), shows the default paper size for that -program. - -With a program given as the first argument and a paper size as the last -argument (e.g., @code{tlmgr dvips paper a4}), set the default for that -program to that paper size. - -With a program given as the first argument and @code{--list} given as the -last argument (e.g., @code{tlmgr dvips paper --list}), shows all valid paper -sizes for that program. The first size shown is the default. - -If @code{--json} is specified without other options, the paper setup is -dumped in JSON format. For the format of JSON output see -@code{tlpkg/doc/JSON-formats.txt}, format definition @code{TLPAPER}. - -Incidentally, this syntax of having a specific program name before the -@code{paper} keyword is unusual. It is inherited from the longstanding -@code{texconfig} script, which supports other configuration settings for -some programs, notably @code{dvips}. @code{tlmgr} does not support those extra -settings. - -@node tlmgr path -@appendixsubsec path - -@table @asis -@item @strong{path [--w32mode=user|admin] add} -@anchor{tlmgr @strong{path [--w32mode=user|admin] add}} - -@item @strong{path [--w32mode=user|admin] remove} -@anchor{tlmgr @strong{path [--w32mode=user|admin] remove}} - -On Unix, adds or removes symlinks for executables, man pages, and info -pages in the system directories specified by the respective options (see -the @ref{tlmgr option,, option} description above). Does not change any initialization -files, either system or personal. Furthermore, any executables added or -removed by future updates are not taken care of automatically; this -command must be rerun as needed. - -On Windows, the registry part where the binary directory is added or -removed is determined in the following way: - -If the user has admin rights, and the option @code{--w32mode} is not given, -the setting @emph{w32_multi_user} determines the location (i.e., if it is -on then the system path, otherwise the user path is changed). - -If the user has admin rights, and the option @code{--w32mode} is given, this -option determines the path to be adjusted. - -If the user does not have admin rights, and the option @code{--w32mode} -is not given, and the setting @emph{w32_multi_user} is off, the user path -is changed, while if the setting @emph{w32_multi_user} is on, a warning is -issued that the caller does not have enough privileges. - -If the user does not have admin rights, and the option @code{--w32mode} -is given, it must be @code{user} and the user path will be adjusted. If a -user without admin rights uses the option @code{--w32mode admin} a warning -is issued that the caller does not have enough privileges. - -@end table - -@node tlmgr pinning -@appendixsubsec pinning - -The @code{pinning} action manages the pinning file, see @ref{tlmgr Pinning,, Pinning} below. - -@table @asis -@item @code{pinning show} -@anchor{tlmgr @code{pinning show}} - -Shows the current pinning data. - -@item @code{pinning add} @emph{repo} @emph{pkgglob}... -@anchor{tlmgr @code{pinning add} @emph{repo} @emph{pkgglob}...} - -Pins the packages matching the @emph{pkgglob}(s) to the repository -@emph{repo}. - -@item @code{pinning remove} @emph{repo} @emph{pkgglob}... -@anchor{tlmgr @code{pinning remove} @emph{repo} @emph{pkgglob}...} - -Any packages recorded in the pinning file matching the <pkgglob>s for -the given repository @emph{repo} are removed. - -@item @code{pinning remove @emph{repo} --all} -@anchor{tlmgr @code{pinning remove @emph{repo} --all}} - -Remove all pinning data for repository @emph{repo}. - -@end table - -@node tlmgr platform -@appendixsubsec platform - -@table @asis -@item @strong{platform list|add|remove @emph{platform}...} -@anchor{tlmgr @strong{platform list|add|remove @emph{platform}...}} - -@item @strong{platform set @emph{platform}} -@anchor{tlmgr @strong{platform set @emph{platform}}} - -@item @strong{platform set auto} -@anchor{tlmgr @strong{platform set auto}} - -@code{platform list} lists the TeX Live names of all the platforms -(a.k.a. architectures), (@code{i386-linux}, ...) available at the package -repository. - -@code{platform add} @emph{platform}... adds the executables for each given platform -@emph{platform} to the installation from the repository. - -@code{platform remove} @emph{platform}... removes the executables for each given -platform @emph{platform} from the installation, but keeps the currently -running platform in any case. - -@code{platform set} @emph{platform} switches TeX Live to always use the given -platform instead of auto detection. - -@code{platform set auto} switches TeX Live to auto detection mode for platform. - -Platform detection is needed to select the proper @code{xz} and -@code{wget} binaries that are shipped with TeX Live. - -@code{arch} is a synonym for @code{platform}. - -Options: - -@table @asis -@item @strong{--dry-run} -@anchor{tlmgr @strong{--dry-run} 2} - -Nothing is actually installed; instead, the actions to be performed are -written to the terminal. - -@end table - -@end table - -@node tlmgr postaction -@appendixsubsec postaction - -@table @asis -@item @strong{postaction [@emph{option}...] install [shortcut|fileassoc|script] [@emph{pkg}...]} -@anchor{tlmgr @strong{postaction [@emph{option}...] install [shortcut|fileassoc|script] [@emph{pkg}...]}} - -@item @strong{postaction [@emph{option}...] remove [shortcut|fileassoc|script] [@emph{pkg}...]} -@anchor{tlmgr @strong{postaction [@emph{option}...] remove [shortcut|fileassoc|script] [@emph{pkg}...]}} - -Carry out the postaction @code{shortcut}, @code{fileassoc}, or @code{script} 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 @code{--all} is given. - -Options: - -@table @asis -@item @strong{--w32mode=[user|admin]} -@anchor{tlmgr @strong{--w32mode=[user|admin]}} - -If the option @code{--w32mode} is given the value @code{user}, all actions will -only be carried out in the user-accessible parts of the -registry/filesystem, while the value @code{admin} selects the system-wide -parts of the registry for the file associations. If you do not have -enough permissions, using @code{--w32mode=admin} will not succeed. - -@item @strong{--fileassocmode=[1|2]} -@anchor{tlmgr @strong{--fileassocmode=[1|2]}} - -@code{--fileassocmode} 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 -@code{option fileassocs}.) - -@item @strong{--all} -@anchor{tlmgr @strong{--all} 1} - -Carry out the postactions for all packages - -@end table - -@end table - -@node tlmgr print-platform -@appendixsubsec print-platform - -Print the TeX Live identifier for the detected platform -(hardware/operating system) combination to standard output, and exit. -@code{--print-arch} is a synonym. - -@node tlmgr print-platform-info -@appendixsubsec print-platform-info - -Print the TeX Live platform identifier, TL platform long name, and -original output from guess. - -@node tlmgr remove [@emph{option}...] @emph{pkg}... -@appendixsubsec remove [@emph{option}...] @emph{pkg}... - -Remove each @emph{pkg} specified. Removing a collection removes all package -dependencies (unless @code{--no-depends} is specified), but not any -collection dependencies of that collection. However, when removing a -package, dependencies are never removed. Options: - -@table @asis -@item @strong{--all} -@anchor{tlmgr @strong{--all} 2} - -Uninstalls all of TeX Live, asking for confirmation unless @code{--force} is -also specified. - -@item @strong{--backup} -@anchor{tlmgr @strong{--backup}} - -@item @strong{--backupdir} @emph{directory} -@anchor{tlmgr @strong{--backupdir} @emph{directory} 1} - -These options behave just as with the @ref{tlmgr update -[@emph{option}...] [...], update,, update} action (q.v.), except they apply to making -backups of packages before they are removed. The default is to make -such a backup, that is, to save a copy of packages before removal. - -The @ref{tlmgr restore,, restore} action explains how to restore from a backup. - -@item @strong{--no-depends} -@anchor{tlmgr @strong{--no-depends} 1} - -Do not remove dependent packages. - -@item @strong{--no-depends-at-all} -@anchor{tlmgr @strong{--no-depends-at-all} 1} - -See above under @ref{tlmgr install [@emph{option}...] @emph{pkg}..., install, install} (and beware). - -@item @strong{--force} -@anchor{tlmgr @strong{--force} 1} - -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. - -A package that has been removed using the @code{--force} option because it -is still listed in an installed collection or scheme will not be -updated, and will be mentioned as @code{forcibly removed} in the output of -@code{tlmgr update --list}. - -@item @strong{--dry-run} -@anchor{tlmgr @strong{--dry-run} 3} - -Nothing is actually removed; instead, the actions to be performed are -written to the terminal. - -@end table - -This action does not automatically remove symlinks to executables from -system directories; you need to run @code{tlmgr path remove} (@ref{tlmgr path,, path}) -yourself if you are using this feature and want stale symlinks removed. - -@node tlmgr repository -@appendixsubsec repository - -@table @asis -@item @strong{repository list} -@anchor{tlmgr @strong{repository list}} - -@item @strong{repository list @emph{path|url|tag}} -@anchor{tlmgr @strong{repository list @emph{path|url|tag}}} - -@item @strong{repository add @emph{path} [@emph{tag}]} -@anchor{tlmgr @strong{repository add @emph{path} [@emph{tag}]}} - -@item @strong{repository remove @emph{path|tag}} -@anchor{tlmgr @strong{repository remove @emph{path|tag}}} - -@item @strong{repository set @emph{path}[#@emph{tag}] [@emph{path}[#@emph{tag}] ...]} -@anchor{tlmgr @strong{repository set @emph{path}[#@emph{tag}] [@emph{path}[#@emph{tag}] ...]}} - -@item @strong{repository status} -@anchor{tlmgr @strong{repository status}} - -This action manages the list of repositories. See @ref{,,, MULTIPLE_REPOSITORIES} below for detailed explanations. - -The first form, @code{repository list}, lists all configured repositories -and the respective tags if set. If a path, url, or tag is given after -the @code{list} keyword, it is interpreted as the source from which to -initialize a TL database and lists the contained packages. This can also -be an otherwise-unused repository, either local or remote. If the option -@code{--with-platforms} is specified in addition, for each package the -available platforms (if any) are also listed. - -The form @code{repository add} adds a repository (optionally attaching a -tag) to the list of repositories, while @code{repository remove} removes a -repository, either by full path/url, or by tag. - -The form @code{repository set} sets the list of available repositories to -the items given on the command line, overwriting previous settings. - -The form @code{repository status} reports the verification status of the -loaded repositories with the format of one repository per line -with fields separated by a single space: - -@table @asis -@item The tag (which can be the same as the url); -@anchor{tlmgr The tag (which can be the same as the url);} - -= the url; - -= iff machine-readable output is specified, the verification code (a -number); - -= a textual description of the verification status, as the last field -extending to the end of line. - -@end table - -That is, in normal (not machine-readable) output, the third field -(numeric verification status) is not present. - -In all cases, one of the repositories must be tagged as @code{main}; -otherwise, all operations will fail! - -@end table - -@node tlmgr restore -@appendixsubsec restore - -@table @asis -@item @strong{restore [@emph{option}...] @emph{pkg} [@emph{rev}]} -@anchor{tlmgr @strong{restore [@emph{option}...] @emph{pkg} [@emph{rev}]}} - -@item @strong{restore [@emph{option}...] --all} -@anchor{tlmgr @strong{restore [@emph{option}...] --all}} - -Restore a package from a previously-made backup. - -If @code{--all} is given, try to restore the latest revision of all -package backups found in the backup directory. - -Otherwise, if neither @emph{pkg} nor @emph{rev} are given, list the available -backup revisions for all packages. With @emph{pkg} given but no @emph{rev}, -list all available backup revisions of @emph{pkg}. - -When listing available packages, @code{tlmgr} shows the revision, and in -parenthesis the creation time if available (in format yyyy-mm-dd hh:mm). - -If (and only if) both @emph{pkg} and a valid revision number @emph{rev} are -specified, try to restore the package from the specified backup. - -Options: - -@table @asis -@item @strong{--all} -@anchor{tlmgr @strong{--all} 3} - -Try to restore the latest revision of all package backups found in the -backup directory. Additional non-option arguments (like @emph{pkg}) are not -allowed. - -@item @strong{--backupdir} @emph{directory} -@anchor{tlmgr @strong{--backupdir} @emph{directory} 2} - -Specify the directory where the backups are to be found. If not given it -will be taken from the configuration setting in the TLPDB. - -@item @strong{--dry-run} -@anchor{tlmgr @strong{--dry-run} 4} - -Nothing is actually restored; instead, the actions to be performed are -written to the terminal. - -@item @strong{--force} -@anchor{tlmgr @strong{--force} 2} - -Don't ask questions. - -@item @strong{--json} -@anchor{tlmgr @strong{--json} 2} - -When listing backups, the option @code{--json} turn on JSON output. -The format is an array of JSON objects (@code{name}, @code{rev}, @code{date}). -For details see @code{tlpkg/doc/JSON-formats.txt}, format definition: @code{TLBACKUPS}. -If both @code{--json} and @code{--data} are given, @code{--json} takes precedence. - -@end table - -@end table - -@node tlmgr search -@appendixsubsec search - -@table @asis -@item @strong{search [@emph{option}...] @emph{what}} -@anchor{tlmgr @strong{search [@emph{option}...] @emph{what}}} - -@item @strong{search [@emph{option}...] --file @emph{what}} -@anchor{tlmgr @strong{search [@emph{option}...] --file @emph{what}}} - -@item @strong{search [@emph{option}...] --all @emph{what}} -@anchor{tlmgr @strong{search [@emph{option}...] --all @emph{what}}} - -By default, search the names, short descriptions, and long descriptions -of all locally installed packages for the argument @emph{what}, interpreted -as a (Perl) regular expression. - -Options: - -@table @asis -@item @strong{--file} -@anchor{tlmgr @strong{--file} 1} - -List all filenames containing @emph{what}. - -@item @strong{--all} -@anchor{tlmgr @strong{--all} 4} - -Search everything: package names, descriptions and filenames. - -@item @strong{--global} -@anchor{tlmgr @strong{--global}} - -Search the TeX Live Database of the installation medium, instead of the -local installation. - -@item @strong{--word} -@anchor{tlmgr @strong{--word}} - -Restrict the search of package names and descriptions (but not -filenames) to match only full words. For example, searching for -@code{table} with this option will not output packages containing the word -@code{tables} (unless they also contain the word @code{table} on its own). - -@end table - -@end table - -@node tlmgr shell -@appendixsubsec shell - -Starts an interactive mode, where tlmgr prompts for commands. This can -be used directly, or for scripting. The first line of output is -@code{protocol} @emph{n}, where @emph{n} is an unsigned number identifying the -protocol version (currently 1). - -In general, tlmgr actions that can be given on the command line -translate to commands in this shell mode. For example, you can say -@code{update --list} to see what would be updated. The TLPDB is loaded the -first time it is needed (not at the beginning), and used for the rest of -the session. - -Besides these actions, a few commands are specific to shell mode: - -@table @asis -@item protocol -@anchor{tlmgr protocol} - -Print @code{protocol @emph{n}}, the current protocol version. - -@item help -@anchor{tlmgr help 1} - -Print pointers to this documentation. - -@item version -@anchor{tlmgr version 1} - -Print tlmgr version information. - -@item quit, end, bye, byebye, EOF -@anchor{tlmgr quit@comma{} end@comma{} bye@comma{} byebye@comma{} EOF} - -Exit. - -@item restart -@anchor{tlmgr restart} - -Restart @code{tlmgr shell} with the original command line; most useful when -developing @code{tlmgr}. - -@item load [local|remote] -@anchor{tlmgr load [local|remote]} - -Explicitly load the local or remote, respectively, TLPDB. - -@item save -@anchor{tlmgr save} - -Save the local TLPDB, presumably after other operations have changed it. - -@item get [@emph{var}] =item set [@emph{var} [@emph{val}]] -@anchor{tlmgr get [@emph{var}] =item set [@emph{var} [@emph{val}]]} - -Get the value of @emph{var}, or set it to @emph{val}. Possible @emph{var} names: -@code{debug-translation}, @code{machine-readable}, @code{no-execute-actions}, -@code{require-verification}, @code{verify-downloads}, @code{repository}, and -@code{prompt}. All except @code{repository} and @code{prompt} are booleans, taking -values 0 and 1, and behave like the corresponding command line option. -The @code{repository} variable takes a string, and sets the remote -repository location. The @code{prompt} variable takes a string, and sets the -current default prompt. - -If @emph{var} or then @emph{val} is not specified, it is prompted for. - -@end table - -@node tlmgr show -@appendixsubsec show - -Synonym for @ref{tlmgr info,, info}. - -@node tlmgr uninstall -@appendixsubsec uninstall - -Synonym for @ref{tlmgr remove [@emph{option}...] @emph{pkg}..., remove, remove}. - -@node tlmgr update [@emph{option}...] [@emph{pkg}...] -@appendixsubsec update [@emph{option}...] [@emph{pkg}...] - -Updates the packages given as arguments to the latest version available -at the installation source. Either @code{--all} or at least one @emph{pkg} name -must be specified. Options: - -@table @asis -@item @strong{--all} -@anchor{tlmgr @strong{--all} 5} - -Update all installed packages except for @code{tlmgr} itself. If updates to -@code{tlmgr} itself are present, this gives an error, unless also the option -@code{--force} or @code{--self} is given. (See below.) - -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. - -This means that if a package has been removed on the server (and thus -has also been removed from the respective collection), @code{tlmgr} will -remove the package in the local installation. This is called -``auto-remove'' and is announced as such when using the option -@code{--list}. This auto-removal can be suppressed using the option -@code{--no-auto-remove} (not recommended, see option description). - -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 @code{--list}. This auto-installation can be -suppressed using the option @code{--no-auto-install} (also not recommended). - -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 @code{tlmgr remove --force} -on them. (See the @code{remove} action documentation.) To reinstall any -such forcibly removed packages use @code{--reinstall-forcibly-removed}. - -To reiterate: automatic removals and additions are entirely determined -by comparison of collections. Thus, if you manually install an -individual package @code{foo} which is later removed from the server, -@code{tlmgr} will not notice and will not remove it locally. (It has to be -this way, without major rearchitecture work, because the tlpdb does not -record the repository from which packages come from.) - -If you want to exclude some packages from the current update run (e.g., -due to a slow link), see the @code{--exclude} option below. - -@item @strong{--self} -@anchor{tlmgr @strong{--self}} - -Update @code{tlmgr} 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. - -If this option is given together with either @code{--all} or a list of -packages, then @code{tlmgr} will be updated first and, if this update -succeeds, the new version will be restarted to complete the rest of the -updates. - -In short: - -@verbatim - 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! -@end verbatim - -@item @strong{--dry-run} -@anchor{tlmgr @strong{--dry-run} 5} - -Nothing is actually installed; instead, the actions to be performed are -written to the terminal. This is a more detailed report than @code{--list}. - -@item @strong{--list} [@emph{pkg}] -@anchor{tlmgr @strong{--list} [@emph{pkg}]} - -Concisely list the packages which would be updated, newly installed, or -removed, without actually changing anything. -If @code{--all} is also given, all available updates are listed. -If @code{--self} is given, but not @code{--all}, only updates to the -critical packages (tlmgr, texlive infrastructure, perl on Windows, etc.) -are listed. -If neither @code{--all} nor @code{--self} is given, and in addition no @emph{pkg} is -given, then @code{--all} is assumed (thus, @code{tlmgr update --list} is the -same as @code{tlmgr update --list --all}). -If neither @code{--all} nor @code{--self} is given, but specific package names are -given, those packages are checked for updates. - -@item @strong{--exclude} @emph{pkg} -@anchor{tlmgr @strong{--exclude} @emph{pkg}} - -Exclude @emph{pkg} from the update process. If this option is given more -than once, its arguments accumulate. - -An argument @emph{pkg} excludes both the package @emph{pkg} itself and all -its related platform-specific packages @emph{pkg.ARCH}. For example, - -@verbatim - tlmgr update --all --exclude a2ping -@end verbatim - -will not update @code{a2ping}, @code{a2ping.i386-linux}, or -any other @code{a2ping.}@emph{ARCH} package. - -If this option specifies a package that would otherwise be a candidate -for auto-installation, auto-removal, or reinstallation of a forcibly -removed package, @code{tlmgr} quits with an error message. Excludes are not -supported in these circumstances. - -This option can also be set permanently in the tlmgr config file with -the key @code{update-exclude}. - -@item @strong{--no-auto-remove} [@emph{pkg}...] -@anchor{tlmgr @strong{--no-auto-remove} [@emph{pkg}...]} - -By default, @code{tlmgr} tries to remove packages in an existing collection -which have disappeared on the server, as described above under @code{--all}. -This option prevents such removals, either for all packages (with -@code{--all}), or for just the given @emph{pkg} names. This can lead to an -inconsistent TeX installation, since packages are not infrequently -renamed or replaced by their authors. Therefore this is not recommended. - -@item @strong{--no-auto-install} [@emph{pkg}...] -@anchor{tlmgr @strong{--no-auto-install} [@emph{pkg}...]} - -Under normal circumstances @code{tlmgr} will install packages which are new -on the server, as described above under @code{--all}. This option prevents -any such automatic installation, either for all packages (with -@code{--all}), or the given @emph{pkg} names. - -Furthermore, after the @code{tlmgr} run using this has finished, the -packages that would have been auto-installed @emph{will be considered as -forcibly removed}. So, if @code{foobar} is the only new package on the -server, then - -@verbatim - tlmgr update --all --no-auto-install -@end verbatim - -is equivalent to - -@verbatim - tlmgr update --all - tlmgr remove --force foobar -@end verbatim - -Again, since packages are sometimes renamed or replaced, using this -option is not recommended. - -@item @strong{--reinstall-forcibly-removed} -@anchor{tlmgr @strong{--reinstall-forcibly-removed}} - -Under normal circumstances @code{tlmgr} will not install packages that have -been forcibly removed by the user; that is, removed with @code{remove ---force}, or whose installation was prohibited by @code{--no-auto-install} -during an earlier update. - -This option makes @code{tlmgr} 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: - -@verbatim - tlmgr update --reinstall-forcibly-removed --all -@end verbatim - -@item @strong{--backup} -@anchor{tlmgr @strong{--backup} 1} - -@item @strong{--backupdir} @emph{directory} -@anchor{tlmgr @strong{--backupdir} @emph{directory} 3} - -These two options control the creation of backups of packages @emph{before} -updating; that is, backing up packages as currently installed. If -neither option is given, no backup will made. If @code{--backupdir} is -given and specifies a writable directory then a backup will be made in -that location. If only @code{--backup} is given, then a backup will be made -to the directory previously set via the @ref{tlmgr option,, option} action (see -below). If both are given then a backup will be made to the specified -@emph{directory}. - -You can also set options via the @ref{tlmgr option,, option} action to automatically make -backups for all packages, and/or keep only a certain number of backups. - -@code{tlmgr} always makes a temporary backup when updating packages, in case -of download or other failure during an update. In contrast, the purpose -of this @code{--backup} option is to save a persistent backup in case the -actual @emph{content} of the update causes problems, e.g., introduces an TeX -incompatibility. - -The @ref{tlmgr restore,, restore} action explains how to restore from a backup. - -@item @strong{--no-depends} -@anchor{tlmgr @strong{--no-depends} 2} - -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. - -@item @strong{--no-depends-at-all} -@anchor{tlmgr @strong{--no-depends-at-all} 2} - -See above under @ref{tlmgr install [@emph{option}...] @emph{pkg}..., install, install} (and beware). - -@item @strong{--force} -@anchor{tlmgr @strong{--force} 3} - -Force update of normal packages, without updating @code{tlmgr} itself -(unless the @code{--self} option is also given). Not recommended. - -Also, @code{update --list} is still performed regardless of this option. - -@end table - -If the package on the server is older than the package already installed -(e.g., if the selected mirror is out of date), @code{tlmgr} does not -downgrade. Also, packages for uninstalled platforms are not installed. - -@code{tlmgr} saves a copy of the @code{texlive.tlpdb} file used for an update -with a suffix representing the repository url, as in -@code{tlpkg/texlive.tlpdb.}@emph{long-hash-string}. These can be useful for -fallback information, but if you don't like them accumulating (e.g., -@code{mirror.ctan.org} resolves to many different hosts, each resulting in -a possibly different hash), it's harmless to delete them. - -This action does not automatically add or remove new symlinks in system -directories; you need to run @code{tlmgr} @ref{tlmgr path,, path} yourself if you are using -this feature and want new symlinks added. - -@node tlmgr CONFIGURATION FILE FOR TLMGR -@appendixsec CONFIGURATION FILE FOR TLMGR - -@code{tlmgr} reads two configuration files: one is system-wide, in -@code{TEXMFSYSCONFIG/tlmgr/config}, and the other is user-specific, in -@code{TEXMFCONFIG/tlmgr/config}. The user-specific one is the default for -the @code{conf tlmgr} action. (Run @code{kpsewhich --var-value=TEXMFSYSCONFIG} or @code{... TEXMFCONFIG ...} to see the actual -directory names.) - -A few defaults corresponding to command-line options can be set in these -configuration files. In addition, the system-wide file can contain a -directive to restrict the allowed actions. - -In these config files, empty lines and lines starting with # are -ignored. All other lines must look like: - -@verbatim - key = value -@end verbatim - -where the spaces are optional but the @code{=} is required. - -The allowed keys are: - -@table @asis -@item @code{auto-remove}, value 0 or 1 (default 1), same as command-line option. -@anchor{tlmgr @code{auto-remove}@comma{} value 0 or 1 (default 1)@comma{} same as command-line option.} - -@item @code{gui-expertmode}, value 0 or 1 (default 1). This switches between the full GUI and a simplified GUI with only the most common settings. -@anchor{tlmgr @code{gui-expertmode}@comma{} value 0 or 1 (default 1). This switches between the full GUI and a simplified GUI with only the most common settings.} - -@item @code{gui-lang} @emph{llcode}, with a language code value as with the command-line option. -@anchor{tlmgr @code{gui-lang} @emph{llcode}@comma{} with a language code value as with the command-line option.} - -@item @code{no-checksums}, value 0 or 1 (default 0, see below). -@anchor{tlmgr @code{no-checksums}@comma{} value 0 or 1 (default 0@comma{} see below).} - -@item @code{persistent-downloads}, value 0 or 1 (default 1), same as command-line option. -@anchor{tlmgr @code{persistent-downloads}@comma{} value 0 or 1 (default 1)@comma{} same as command-line option.} - -@item @code{require-verification}, value 0 or 1 (default 0), same as command-line option. -@anchor{tlmgr @code{require-verification}@comma{} value 0 or 1 (default 0)@comma{} same as command-line option.} - -@item @code{update-exclude}, value: comma-separated list of packages (no space allowed). Same as the command line option @code{--exclude} for the action @code{update}. -@anchor{tlmgr @code{update-exclude}@comma{} value: comma-separated list of packages (no space allowed). Same as the command line option @code{--exclude} for the action @code{update}.} - -@item @code{verify-downloads}, value 0 or 1 (default 1), same as command-line option. -@anchor{tlmgr @code{verify-downloads}@comma{} value 0 or 1 (default 1)@comma{} same as command-line option.} - -@end table - -The system-wide config file can contain one additional key: - -@table @asis -@item @code{allowed-actions} @emph{action1} [,@emph{action},...] The value is a comma-separated list of @code{tlmgr} actions which are allowed to be executed when @code{tlmgr} is invoked in system mode (that is, without @code{--usermode}). -@anchor{tlmgr @code{allowed-actions} @emph{action1} [@comma{}@emph{action}@comma{}...] The value is a comma-separated list of @code{tlmgr} actions which are allowed to be executed when @code{tlmgr} is invoked in system mode (that is@comma{} without @code{--usermode}).} - -This allows distributors to include the @code{tlmgr} in their packaging, but -allow only a restricted set of actions that do not interfere with their -distro package manager. For native TeX Live installations, it doesn't -make sense to set this. - -@end table - -The @code{no-checksums} key needs more explanation. By default, package -checksums computed and stored on the server (in the TLPDB) are compared -to checksums computed locally after downloading. @code{no-checksums} -disables this process. - -The checksum algorithm is SHA-512. Your system must have one of (looked -for in this order) the Perl @code{Digest::SHA} module, the @code{openssl} -program (@url{https://openssl.org}), the @code{sha512sum} program (from GNU -Coreutils, @url{https://www.gnu.org/software/coreutils}), or finally the -@code{shasum} program (just to support old Macs). If none of these are -available, a warning is issued and @code{tlmgr} proceeds without checking -checksums. (Incidentally, other SHA implementations, such as the pure -Perl and pure Lua modules, are much too slow to be usable in our -context.) @code{no-checksums} avoids the warning. - -@node tlmgr CRYPTOGRAPHIC VERIFICATION -@appendixsec CRYPTOGRAPHIC VERIFICATION - -@code{tlmgr} and @code{install-tl} perform cryptographic verification if -possible. If verification is performed and successful, the programs -report @code{(verified)} after loading the TLPDB; otherwise, they report -@code{(not verified)}. But either way, by default the installation and/or -updates proceed normally. - -If a program named @code{gpg} is available (that is, found in @code{PATH}), by -default cryptographic signatures will be checked: we require the main -repository be signed, but not any additional repositories. If @code{gpg} is -not available, by default signatures are not checked and no verification -is carried out, but @code{tlmgr} still proceeds normally. - -The behavior of the verification can be controlled by the command line -and config file option @code{verify-repo} which takes one of the following -values: @code{none}, @code{main}, or @code{all}. With @code{none}, no verification -whatsoever is attempted. With @code{main} (the default) verification is -required only for the main repository, and only if @code{gpg} is available; -though attempted for all, missing signatures of subsidiary repositories -will not result in an error. Finally, in the case of @code{all}, @code{gpg} -must be available and all repositories need to be signed. - -In all cases, if a signature is checked and fails to verify, an error -is raised. - -Cryptographic verification requires checksum checking (described just -above) to succeed, and a working GnuPG (@code{gpg}) program (see below for -search method). Then, unless cryptographic verification has been -disabled, a signature file (@code{texlive.tlpdb.*.asc}) of the checksum file -is downloaded and the signature verified. The signature is created by -the TeX Live Distribution GPG key 0x0D5E5D9106BAB6BC, which in turn is -signed by Karl Berry's key 0x0716748A30D155AD and -Norbert Preining's key 0x6CACA448860CDC13. All -of these keys are obtainable from the standard key servers. - -Additional trusted keys can be added using the @code{key} action. - -@menu -* tlmgr Configuration of GnuPG invocation:: -@end menu - -@node tlmgr Configuration of GnuPG invocation -@appendixsubsec Configuration of GnuPG invocation - -The executable used for GnuPG is searched as follows: If the environment -variable @code{TL_GNUPG} is set, it is tested and used; otherwise @code{gpg} is -checked; finally @code{gpg2} is checked. - -Further adaptation of the @code{gpg} invocation can be made using the two -environment variables @code{TL_GNUPGHOME}, which is passed to @code{gpg} as the -value for @code{--homedir}, and @code{TL_GNUPGARGS}, which replaces the default -options @code{--no-secmem-warning --no-permission-warning}. - -@node tlmgr USER MODE -@appendixsec USER MODE - -@code{tlmgr} provides a restricted way, called ``user mode'', to manage -arbitrary texmf trees in the same way as the main installation. For -example, this allows people without write permissions on the -installation location to update/install packages into a tree of their -own. - -@code{tlmgr} is switched into user mode with the command line option -@code{--usermode}. It does not switch automatically, nor is there any -configuration file setting for it. Thus, this option has to be -explicitly given every time user mode is to be activated. - -This mode of @code{tlmgr} works on a user tree, by default the value of the -@code{TEXMFHOME} variable. This can be overridden with the command line -option @code{--usertree}. In the following when we speak of the user tree -we mean either @code{TEXMFHOME} or the one given on the command line. - -Not all actions are allowed in user mode; @code{tlmgr} will warn you and not -carry out any problematic actions. Currently not supported (and -probably will never be) is the @code{platform} action. The @code{gui} action is -currently not supported, but may be in a future release. - -Some @code{tlmgr} actions don't need any write permissions and thus work the -same in user mode and normal mode. Currently these are: @code{check}, -@code{help}, @code{list}, @code{print-platform}, @code{print-platform-info}, @code{search}, -@code{show}, @code{version}. - -On the other hand, most of the actions dealing with package management -do need write permissions, and thus behave differently in user mode, as -described below: @code{install}, @code{update}, @code{remove}, @code{option}, @code{paper}, -@code{generate}, @code{backup}, @code{restore}, @code{uninstall}, @code{symlinks}. - -Before using @code{tlmgr} in user mode, you have to set up the user tree -with the @code{init-usertree} action. This creates @emph{usertree}@code{/web2c} and -@emph{usertree}@code{/tlpkg/tlpobj}, and a minimal -@emph{usertree}@code{/tlpkg/texlive.tlpdb}. At that point, you can tell -@code{tlmgr} to do the (supported) actions by adding the @code{--usermode} -command line option. - -In user mode the file @emph{usertree}@code{/tlpkg/texlive.tlpdb} contains only -the packages that have been installed into the user tree using @code{tlmgr}, -plus additional options from the ``virtual'' package -@code{00texlive.installation} (similar to the main installation's -@code{texlive.tlpdb}). - -All actions on packages in user mode can only be carried out on packages -that are known as @code{relocatable}. This excludes all packages containing -executables and a few other core packages. Of the 2500 or so packages -currently in TeX Live the vast majority are relocatable and can be -installed into a user tree. - -Description of changes of actions in user mode: - -@menu -* tlmgr User mode install:: -* tlmgr User mode backup@comma{} restore@comma{} remove@comma{} update:: -* tlmgr User mode generate@comma{} option@comma{} paper:: -@end menu - -@node tlmgr User mode install -@appendixsubsec User mode install - -In user mode, the @code{install} action checks that the package and all -dependencies are all either relocated or already installed in the system -installation. If this is the case, it unpacks all containers to be -installed into the user tree (to repeat, that's either @code{TEXMFHOME} or -the value of @code{--usertree}) and add the respective packages to the user -tree's @code{texlive.tlpdb} (creating it if need be). - -Currently installing a collection in user mode installs all dependent -packages, but in contrast to normal mode, does @emph{not} install dependent -collections. For example, in normal mode @code{tlmgr install -collection-context} would install @code{collection-basic} and other -collections, while in user mode, @emph{only} the packages mentioned in -@code{collection-context} are installed. - -If a package shipping map files is installed in user mode, a backup of -the user's @code{updmap.cfg} in @code{USERTREE/web2c/} is made, and then this file -regenerated from the list of installed packages. - -@node tlmgr User mode backup@comma{} restore@comma{} remove@comma{} update -@appendixsubsec User mode backup, restore, remove, update - -In user mode, these actions check that all packages to be acted on are -installed in the user tree before proceeding; otherwise, they behave -just as in normal mode. - -@node tlmgr User mode generate@comma{} option@comma{} paper -@appendixsubsec User mode generate, option, paper - -In user mode, these actions operate only on the user tree's -configuration files and/or @code{texlive.tlpdb}. -creates configuration files in user tree - -@node tlmgr MULTIPLE REPOSITORIES -@appendixsec 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. - -The simplest and most reliable method is to temporarily set the -installation source to any repository (with the @code{-repository} or -@code{option repository} command line options), and perform your operations. - -When you are using multiple repositories over a sustained length of -time, however, explicitly switching between them becomes inconvenient. -Thus, it's possible to tell @code{tlmgr} about additional repositories you -want to use. The basic command is @code{tlmgr repository add}. The rest of -this section explains further. - -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. - -By default, even if multiple repositories are configured, packages are -@emph{still} @emph{only} 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. - -@menu -* tlmgr Pinning:: -@end menu - -@node tlmgr Pinning -@appendixsubsec Pinning - -When a package @code{foo} is pinned to a repository, a package @code{foo} in any -other repository, even if it has a higher revision number, will not be -considered an installable candidate. - -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. - -First, check that we have support for multiple repositories, and have -only one enabled (as is the case by default): - -@verbatim - $ tlmgr repository list - List of repositories (with tags if set): - /var/www/norbert/tlnet -@end verbatim - -Ok. Let's add the @code{tlcontrib} repository (this is a real -repository hosted at @url{http://contrib.texlive.info}) with the tag @code{tlcontrib}: - -@verbatim - $ tlmgr repository add http://contrib.texlive.info/current tlcontrib -@end verbatim - -Check the repository list again: - -@verbatim - $ tlmgr repository list - List of repositories (with tags if set): - http://contrib.texlive.info/current (tlcontrib) - /var/www/norbert/tlnet (main) -@end verbatim - -Now we specify a pinning entry to get the package @code{classico} from -@code{tlcontrib}: - -@verbatim - $ tlmgr pinning add tlcontrib classico -@end verbatim - -Check that we can find @code{classico}: - -@verbatim - $ tlmgr show classico - package: classico - ... - shortdesc: URW Classico fonts - ... -@end verbatim - -- install @code{classico}: - -@verbatim - $ tlmgr install classico - tlmgr: package repositories: - ... - [1/1, ??:??/??:??] install: classico @tlcontrib [737k] -@end verbatim - -In the output here you can see that the @code{classico} package has been -installed from the @code{tlcontrib} repository (@code{@@tlcontrib}). - -Finally, @code{tlmgr pinning} also supports removing certain or all packages -from a given repository: - -@verbatim - $ tlmgr pinning remove tlcontrib classico # remove just classico - $ tlmgr pinning remove tlcontrib --all # take nothing from tlcontrib -@end verbatim - -A summary of @code{tlmgr pinning} actions is given above. - -@node tlmgr GUI FOR TLMGR -@appendixsec GUI FOR TLMGR - -The graphical user interface for @code{tlmgr} requires Perl/Tk -@url{https://search.cpan.org/search?query=perl%2Ftk}. For Unix-based -systems Perl/Tk (as well as Perl of course) has to be installed -outside of TL. @url{https://tug.org/texlive/distro.html#perltk} has a -list of invocations for some distros. For Windows the necessary -modules are no longer shipped within TeX Live, so you'll have to have an -external Perl available that includes them. - -We are talking here about the GUI built into tlmgr itself, not about the -other tlmgr GUIs, which are: tlshell (Tcl/Tk-based), tlcockpit -(Java-based) and, only on Macs, TeX Live Utility. These are invoked as -separate programs. - -The GUI mode of tlmgr is started with the invocation @code{tlmgr gui}; -assuming Tk is loadable, 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. - -Within the main display there are three main parts: the @code{Display -configuration} area, the list of packages, and the action buttons. - -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 @code{tlmgr} menu item. - -Finally, the status area at the bottom of the window gives additional -information about what is going on. - -@menu -* tlmgr Main display:: -* tlmgr Menu bar:: -* tlmgr GUI options:: -@end menu - -@node tlmgr Main display -@appendixsubsec Main display - -@menu -* tlmgr Display configuration area:: -* tlmgr Package list area:: -* tlmgr Main display action buttons:: -@end menu - -@node tlmgr Display configuration area -@appendixsubsubsec Display configuration area - -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. - -@table @asis -@item Status -@anchor{tlmgr Status} - -Select whether to show all packages (the default), only those installed, -only those @emph{not} installed, or only those with update available. - -@item Category -@anchor{tlmgr Category} - -Select which categories are shown: packages, collections, and/or -schemes. These are briefly explained in the @ref{tlmgr DESCRIPTION,, DESCRIPTION} section -above. - -@item Match -@anchor{tlmgr Match} - -Select packages matching for a specific pattern. By default, this -searches both descriptions and filenames. You can also select a subset -for searching. - -@item Selection -@anchor{tlmgr 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. - -@item Display configuration buttons -@anchor{tlmgr 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. - -@end table - -@node tlmgr Package list area -@appendixsubsubsec Package list area - -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. - -Double clicking on a package line pops up an informational window with -further details: the long description, included files, etc. - -Each line of the package list consists of the following items: - -@table @asis -@item a checkbox -@anchor{tlmgr a checkbox} - -Used to select particular packages; some of the action buttons (see -below) work only on the selected packages. - -@item package name -@anchor{tlmgr package name} - -The name (identifier) of the package as given in the database. - -@item local revision (and version) -@anchor{tlmgr 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 TL revision, is not -guaranteed to reflect what is actually installed. - -@item remote revision (and version) -@anchor{tlmgr 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. - -@item short description -@anchor{tlmgr short description} - -The short description of the package. - -@end table - -@node tlmgr Main display action buttons -@appendixsubsubsec Main display action buttons - -Below the list of packages are several buttons: - -@table @asis -@item Update all installed -@anchor{tlmgr Update all installed} - -This calls @code{tlmgr update --all}, 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. - -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. - -@item Update -@anchor{tlmgr Update} - -Update only the selected packages. - -@item Install -@anchor{tlmgr Install} - -Install the selected packages; acts like @code{tlmgr install}, i.e., also -installs dependencies. Thus, installing a collection installs all its -constituent packages. - -@item Remove -@anchor{tlmgr Remove} - -Removes the selected packages; acts like @code{tlmgr remove}, i.e., it will -also remove dependencies of collections (but not dependencies of normal -packages). - -@item Backup -@anchor{tlmgr Backup} - -Makes a backup of the selected packages; acts like @code{tlmgr backup}. This -action needs the option @code{backupdir} set (see @code{Options -} General>). - -@end table - -@node tlmgr Menu bar -@appendixsubsec Menu bar - -The following entries can be found in the menu bar: - -@table @asis -@item @code{tlmgr} menu -@anchor{tlmgr @code{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 @code{quit} operation. - -@item @code{Options menu} -@anchor{tlmgr @code{Options menu}} - -Provides access to several groups of options: @code{Paper} (configuration of -default paper sizes), @code{Platforms} (only on Unix, configuration of the -supported/installed platforms), @code{GUI Language} (select language used in -the GUI interface), and @code{General} (everything else). - -Several toggles are also here. The first is @code{Expert options}, which is -set by default. If you turn this off, the next time you start the GUI a -simplified screen will be shown that display only the most important -functionality. This setting is saved in the configuration file of -@code{tlmgr}; see @ref{tlmgr CONFIGURATION FILE FOR TLMGR,, CONFIGURATION FILE FOR TLMGR} for details. - -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. - -@item @code{Actions menu} -@anchor{tlmgr @code{Actions menu}} - -Provides access to several actions: update the filename database (aka -@code{ls-R}, @code{mktexlsr}, @code{texhash}), rebuild all formats (@code{fmtutil-sys ---all}), update the font map database (@code{updmap-sys}), restore from a backup -of a package, and use of symbolic links in system directories (not on -Windows). - -The final action is to remove the entire TeX Live installation (also not -on Windows). - -@item @code{Help menu} -@anchor{tlmgr @code{Help menu}} - -Provides access to the TeX Live manual (also on the web at -@url{https://tug.org/texlive/doc.html}) and the usual ``About'' box. - -@end table - -@node tlmgr GUI options -@appendixsubsec GUI options - -Some generic Perl/Tk options can be specified with @code{tlmgr gui} to -control the display: - -@table @asis -@item @code{-background} @emph{color} -@anchor{tlmgr @code{-background} @emph{color}} - -Set background color. - -@item @code{-font "} @emph{fontname} @emph{fontsize} @code{"} -@anchor{tlmgr @code{-font "} @emph{fontname} @emph{fontsize} @code{"}} - -Set font, e.g., @code{tlmgr gui -font "helvetica 18"}. The argument to -@code{-font} must be quoted, i.e., passed as a single string. - -@item @code{-foreground} @emph{color} -@anchor{tlmgr @code{-foreground} @emph{color}} - -Set foreground color. - -@item @code{-geometry} @emph{geomspec} -@anchor{tlmgr @code{-geometry} @emph{geomspec}} - -Set the X geometry, e.g., @code{tlmgr gui -geometry 1024x512-0+0} creates -the window of (approximately) the given size in the upper-right corner -of the display. - -@item @code{-xrm} @emph{xresource} -@anchor{tlmgr @code{-xrm} @emph{xresource}} - -Pass the arbitrary X resource string @emph{xresource}. - -@end table - -A few other obscure options are recognized but not mentioned here. See -the Perl/Tk documentation (@url{https://search.cpan.org/perldoc?Tk}) for the -complete list, and any X documentation for general information. - -@node tlmgr MACHINE-READABLE OUTPUT -@appendixsec MACHINE-READABLE OUTPUT - -With the @code{--machine-readable} option, @code{tlmgr} 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. - -Currently this option only applies to the -@ref{tlmgr update [@emph{option}...] [@emph{pkg}...], update, update}, -@ref{tlmgr install [@emph{option}...] @emph{pkg}..., install, install}, and -@ref{tlmgr option,, option} actions. - -@menu -* tlmgr Machine-readable @code{update} and @code{install} output:: -* tlmgr Machine-readable @code{option} output:: -@end menu - -@node tlmgr Machine-readable @code{update} and @code{install} output -@appendixsubsec Machine-readable @code{update} and @code{install} output - -The output format is as follows: - -@verbatim - fieldname "\t" value - ... - "end-of-header" - pkgname status localrev serverrev size runtime esttot - ... - "end-of-updates" - other output from post actions, not in machine readable form -@end verbatim - -The header section currently has two fields: @code{location-url} (the -repository source from which updates are being drawn), and -@code{total-bytes} (the total number of bytes to be downloaded). - -The @emph{localrev} and @emph{serverrev} fields for each package are the -revision numbers in the local installation and server repository, -respectively. The @emph{size} 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. - -Line endings may be either LF or CRLF depending on the current platform. - -@table @asis -@item @code{location-url} @emph{location} -@anchor{tlmgr @code{location-url} @emph{location}} - -The @emph{location} may be a url (including @code{file:///foo/bar/...}), or a -directory name (@code{/foo/bar}). It is the package repository from which -the new package information was drawn. - -@item @code{total-bytes} @emph{count} -@anchor{tlmgr @code{total-bytes} @emph{count}} - -The @emph{count} is simply a decimal number, the sum of the sizes of all the -packages that need updating or installing (which are listed subsequently). - -@end table - -Then comes a line with only the literal string @code{end-of-header}. - -Each following line until a line with literal string @code{end-of-updates} -reports on one package. The fields on -each line are separated by a tab. Here are the fields. - -@table @asis -@item @emph{pkgname} -@anchor{tlmgr @emph{pkgname}} - -The TeX Live package identifier, with a possible platform suffix for -executables. For instance, @code{pdftex} and @code{pdftex.i386-linux} are given -as two separate packages, one on each line. - -@item @emph{status} -@anchor{tlmgr @emph{status}} - -The status of the package update. One character, as follows: - -@table @asis -@item @code{d} -@anchor{tlmgr @code{d}} - -The package was removed on the server. - -@item @code{f} -@anchor{tlmgr @code{f}} - -The package was removed in the local installation, even though a -collection depended on it. (E.g., the user ran @code{tlmgr remove ---force}.) - -@item @code{u} -@anchor{tlmgr @code{u}} - -Normal update is needed. - -@item @code{r} -@anchor{tlmgr @code{r}} - -Reversed non-update: the locally-installed version is newer than the -version on the server. - -@item @code{a} -@anchor{tlmgr @code{a}} - -Automatically-determined need for installation, the package is new on -the server and is (most probably) part of an installed collection. - -@item @code{i} -@anchor{tlmgr @code{i}} - -Package will be installed and isn't present in the local installation -(action install). - -@item @code{I} -@anchor{tlmgr @code{I}} - -Package is already present but will be reinstalled (action install). - -@end table - -@item @emph{localrev} -@anchor{tlmgr @emph{localrev}} - -The revision number of the installed package, or @code{-} if it is not -present locally. - -@item @emph{serverrev} -@anchor{tlmgr @emph{serverrev}} - -The revision number of the package on the server, or @code{-} if it is not -present on the server. - -@item @emph{size} -@anchor{tlmgr @emph{size}} - -The size in bytes of the package on the server. The sum of all the -package sizes is given in the @code{total-bytes} header field mentioned above. - -@item @emph{runtime} -@anchor{tlmgr @emph{runtime}} - -The run time since start of installations or updates. - -@item @emph{esttot} -@anchor{tlmgr @emph{esttot}} - -The estimated total time. - -@end table - -@node tlmgr Machine-readable @code{option} output -@appendixsubsec Machine-readable @code{option} output - -The output format is as follows: - -@verbatim - key "\t" value -@end verbatim - -If a value is not saved in the database the string @code{(not set)} is shown. - -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. - -@node tlmgr ENVIRONMENT VARIABLES -@appendixsec ENVIRONMENT VARIABLES - -@code{tlmgr} uses many of the standard TeX environment variables, as -reported by, e.g., @code{tlmgr conf} (@ref{tlmgr conf,, conf}). - -In addition, for ease in scripting and debugging, @code{tlmgr} looks for the -following environment variables. These are not of interest for normal -user installations. - -@table @asis -@item @code{TEXLIVE_COMPRESSOR} -@anchor{tlmgr @code{TEXLIVE_COMPRESSOR}} - -This variable allows selecting a different compressor program for -backups and intermediate rollback containers. The order of selection is: - -@enumerate -@item If the environment variable @code{TEXLIVE_COMPRESSOR} is -defined, use it; abort if it doesn't work. Possible values: -@code{lz4}, @code{gzip}, @code{xz}. The necessary options are added internally. - -@item If lz4 is available (either from the system or TL) and working, use that. - -@item If gzip is available (from the system) and working, use that. - -@item If xz is available (either from the system or TL) and working, use that. - -@end enumerate - -lz4 and gzip are faster in creating tlmgr's local backups, hence they -are preferred. The unconditional use of xz for the tlnet containers is -unaffected, to minimize download sizes. - -@item @code{TEXLIVE_DOWNLOADER} -@anchor{tlmgr @code{TEXLIVE_DOWNLOADER}} - -@item @code{TL_DOWNLOAD_PROGRAM} -@anchor{tlmgr @code{TL_DOWNLOAD_PROGRAM}} - -@item @code{TL_DOWNLOAD_ARGS} -@anchor{tlmgr @code{TL_DOWNLOAD_ARGS}} - -These options allow selecting different download programs then the ones -automatically selected by the installer. The order of selection is: - -@enumerate -@item If the environment variable @code{TEXLIVE_DOWNLOADER} is defined, use it; -abort if the specified program doesn't work. Possible values: @code{lwp}, -@code{curl}, @code{wget}. The necessary options are added internally. - -@item If the environment variable @code{TL_DOWNLOAD_PROGRAM} is -defined (can be any value), use it together with -@code{TL_DOWNLOAD_ARGS}; abort if it doesn't work. - -@item If LWP is available and working, use that (by far the most -efficient method, as it supports persistent downloads). - -@item If curl is available (from the system) and working, use that. - -@item If wget is available (either from the system or TL) and working, use that. - -@end enumerate - -TL provides @code{wget} binaries for platforms where necessary, so some -download method should always be available. - -@item @code{TEXLIVE_PREFER_OWN} -@anchor{tlmgr @code{TEXLIVE_PREFER_OWN}} - -By default, compression and download programs provided by the system, -i.e., found along @code{PATH} are preferred over those shipped with TeX -Live. - -This can create problems with systems that are too old, and so can be -overridden by setting the environment variable @code{TEXLIVE_PREFER_OWN} to -1. In this case, executables shipped with TL will be preferred. - -Extra compression/download programs not provided by TL, such as gzip, -lwp, and curl, are still checked for on the system and used if -available, per the above. @code{TEXLIVE_PREFER_OWN} only applies when the -program being checked for is shipped with TL, namely the lz4 and -xz compressors and wget downloader. - -Exception: on Windows, the @code{tar.exe} shipped with TL is always used, -regardless of any setting. - -@end table - -@node tlmgr AUTHORS AND COPYRIGHT -@appendixsec AUTHORS AND COPYRIGHT - -This script and its documentation were written for the TeX Live -distribution (@url{https://tug.org/texlive}) and both are licensed under the -GNU General Public License Version 2 or later. - -$Id: tlmgr.pl 54118 2020-03-05 22:27:22Z karl $ - |