diff options
author | Karl Berry <karl@freefriends.org> | 2021-04-23 20:37:36 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2021-04-23 20:37:36 +0000 |
commit | 3c1ab1c6a0a621a16c807ecca8a0d184466c9081 (patch) | |
tree | 17e21aa59b743867ffaca9416bcd9c540e26114b /Master/texmf-dist/doc/latex | |
parent | af292fa34af3a489b65592b6ebde4c963fa07d8b (diff) |
tlmgrbasics (23apr21)
git-svn-id: svn://tug.org/texlive/trunk@58974 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex')
-rw-r--r-- | Master/texmf-dist/doc/latex/tlmgrbasics/README | 10 | ||||
-rw-r--r-- | Master/texmf-dist/doc/latex/tlmgrbasics/tlmgr.pdf | bin | 144470 -> 0 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/tlmgrbasics/tlmgr.tex | 699 |
3 files changed, 0 insertions, 709 deletions
diff --git a/Master/texmf-dist/doc/latex/tlmgrbasics/README b/Master/texmf-dist/doc/latex/tlmgrbasics/README deleted file mode 100644 index d5b81524a67..00000000000 --- a/Master/texmf-dist/doc/latex/tlmgrbasics/README +++ /dev/null @@ -1,10 +0,0 @@ -This is the README for the tlmgrBasics package, version 2020-08-31. - -This package provides simplified documentation for tlmgr, -the TeX Live Native Manager. It is derived from tlmgr.1, the -man page. This document describes the most commonly-used -actions and options in a convenient hyperlinked PDF format. - -This document is licensed under the GNU General Public -License, Version 2 or later and is maintained by Bob Tennent -(rdt at cs.queensu.ca). diff --git a/Master/texmf-dist/doc/latex/tlmgrbasics/tlmgr.pdf b/Master/texmf-dist/doc/latex/tlmgrbasics/tlmgr.pdf Binary files differdeleted file mode 100644 index 204a7dc5137..00000000000 --- a/Master/texmf-dist/doc/latex/tlmgrbasics/tlmgr.pdf +++ /dev/null diff --git a/Master/texmf-dist/doc/latex/tlmgrbasics/tlmgr.tex b/Master/texmf-dist/doc/latex/tlmgrbasics/tlmgr.tex deleted file mode 100644 index f0c5eb78135..00000000000 --- a/Master/texmf-dist/doc/latex/tlmgrbasics/tlmgr.tex +++ /dev/null @@ -1,699 +0,0 @@ -\documentclass[11pt]{article} -\usepackage[T1]{fontenc} -\usepackage{microtype} -\usepackage[osf]{mathpazo} - -% using OT1 encoding for tt to avoid need for cm-super fonts -\renewcommand{\ttfamily}{\fontencoding{OT1}\fontfamily{cmtt}\selectfont} - -\usepackage{hyperref} - -\title{Basic Usage of \texttt{tlmgr}, the \TeX\,Live Manager} -\author{edited by Bob Tennent\thanks{\scriptsize Derived -from the man page \texttt{tlmgr.1} and licensed under -the GNU General Public Licence, Version 2 or later.}\\ -\url{rdt@cs.queensu.ca}} - -\usepackage[headheight=14pt]{geometry} -\usepackage{fancyhdr} -\pagestyle{fancy} -\begin{document} -\maketitle -\thispagestyle{empty} - - -\tableofcontents - -\clearpage - -\section{Introduction} - -\texttt{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}. - -\TeX\,Live is organized into a few top-level -\textit{schemes}, each of which specifies a set of -\textit{collections} and \textit{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. - -We will describe usage of \texttt{tlmgr} in the -command-line interface. There are graphical front-ends -for \texttt{tlmgr}: \texttt{tlshell}, \texttt{tlcockpit} -and, for Macs, a \TeX\,Live Utility; these must -be started as separate programs. These is also a -graphical user interface in \texttt{tlmgr} itself; -consult the documentation here: -\begin{center} - \url{https://tug.org/texlive/doc/tlmgr.html#GUI-FOR-TLMGR}. -\end{center} - - - -\section{Usage} - -\begin{quote} - \texttt{tlmgr} - \verb|[|\textit{global options} \verb|]| - \textit{action} - \verb|[|\textit{action-specific options}\verb|]| - \verb|[|\textit{operands}\verb|]| -\end{quote} - -The actions and relevant action-specific options and -operands are described in Section~\ref{Actions}. The global -options are described in Section~\ref{GlobalOptions}. - -Options, whether global or action-specific, may be -given anywhere on the command line, and in any order. -The first non-option argument will be treated as the -main action. In all cases, \verb|--|\textit{option} and -\verb|-|\textit{option} are equivalent, and an \verb|=| is -optional between an option name and its value. - -This report documents only the most commonly-used actions -and options for \texttt{tlmgr}. Complete documentation may -be found at -\begin{center} - \url{https://tug.org/texlive/doc/tlmgr.html}. -\end{center} - -\clearpage -\section{Examples} - -After successfully installing \TeX\,Live, the following are -examples of common operations with \texttt{tlmgr}: -\begin{description} - -\item\texttt{tlmgr -help install}\par - -Displays reference documentation on the \texttt{install} action. - -\item\texttt{tlmgr option repository ctan}\par - -Tells \texttt{tlmgr} to use a nearby CTAN mirror for -future updates; \texttt{ctan} is just an alias for -\url{http://mirror.ctan.org/systems/texlive/tlnet}. Caveat: -\texttt{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 in place of -\texttt{mirror.ctan.org} if there are problems; the -list of all CTAN mirrors with the status of each is at -\url{https://ctan.org/mirrors/mirmon}. Don't forget to add -\texttt{.../systems/texlive/tlnet} to the path. - -\item\texttt{tlmgr update -all}\par - -Makes your local \TeX\ installation correspond to what is in -the default package repository. - -\item\texttt{tlmgr update -self}\par - -Updates \texttt{tlmgr} itself (that is, the infrastructure -packages) if updates to it are present. If the -\texttt{-self} option is given together with either -\texttt{-all} or a list of packages, then \texttt{tlmgr} -will be updated first and, if this update succeeds, the -new version will be restarted to complete the rest of the -updates. - -\item\texttt{tlmgr info fontspec}\par - -Displays detailed information about package -\texttt{fontspec}, such as the installation status and -description. - -\item\texttt{tlmgr info -list fontspec}\par - -The list of files in package \texttt{fontspec} is -also displayed, including those for platform-specific -dependencies. - -\item\texttt{tlmgr install fontspec}\par - -Installs the \texttt{fontspec} package (unless it is already -installed). By default all packages on which the given -package is dependent are also installed. Existing packages -are not touched. - -\item\texttt{tlmgr search -file cabin}\par - -Searches locally installed packages and displays all filenames -containing \texttt{cabin}. - -\end{description} - -\clearpage - -\section{Actions} -\label{Actions} - -\subsection{The {\tt info} Action} -\label{info} - -\paragraph{Usage:} - -\begin{list}{}{} -\item \texttt{tlmgr info} -\item \texttt{tlmgr info collections} -\item \texttt{tlmgr info schemes} -\item \texttt{tlmgr info} \textsl{pkgs} -\end{list} - -With no argument, lists all packages available at the -package repository, prefixing those already installed with -\texttt{i}. - -With the single word \texttt{collections} or -\texttt{schemes} as the argument, lists all the collections -and schemes, respectively, instead of all packages. - -With any other arguments, displays information about each -of the \textsl{pkgs}: the name, category, short and long -description, sizes, installation status, and \TeX\,Live -revision number. If the package 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) 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 a package is not found locally or remotely, the -\texttt{search} action (see Section~\ref{search}) 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 \texttt{revision} value comes -directly from TL and is reliable. - - -\paragraph{Options for \mdseries\texttt{info}:} - -\begin{description} - -\item\texttt{-list}\par - -If the option \texttt{-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, \texttt{-list} outputs their dependencies in a -similar way. - -\item\texttt{-only-installed}\par - -If this option is given, the installation source will not -be used; only locally installed packages, collections, or -schemes are listed. - -\item\texttt{-only-remote}\par - -Only list packages from the remote repository. Useful when -checking what is available in a remote repository using -\begin{center} -\texttt{tlmgr -repo ... -only-remote info}. -\end{center} - -\end{description} - -Note that \texttt{-only-installed} and \texttt{-only-remote} -cannot both be specified. - -\clearpage - -\subsection{The {\tt search} Action} -\label{search} - -\paragraph{Usage:} -\begin{list}{}{} - -\item \texttt{tlmgr search} \textsl{what} \end{list} By -default, search the names, short descriptions, and long -descriptions of all locally installed packages for the -argument \textsl{what}, interpreted as a (Perl) regular -expression. - -\paragraph{Options for {\tt search}:} - -\begin{description} - -\item\texttt{-file}\par - -List all filenames containing \textsl{what}. - -\item\texttt{-global}\par - -Search the \TeX\,Live Database of the installation medium, -instead of the local installation. - -\item\texttt{-word}\par - -Restrict the search of package names and descriptions (but -not filenames) to match only full words. For example, -searching for \texttt{table} with this option will not -output a package containing the word \texttt{tables} (unless -it also contains the word \texttt{table} on its own). - -\end{description} - -\clearpage - -\subsection{The {\tt install} Action} -\label{install} - -\paragraph{Usage:} -\begin{list}{}{} -\item \texttt{tlmgr install} \textsl{pkgs} -\end{list} - -Install each of the \textsl{pkgs} (unless it is already -installed). By default all packages on which the given -package is dependent are also installed. Existing packages -are not touched; use the \texttt{update} action described in -Section~\ref{update} to get the latest version of a package. - - -\paragraph{Options for \mdseries\texttt{install}:} - -\begin{description} - -\item\texttt{-dry-run}\par - -Nothing is actually installed; instead, the actions to be -performed are written to the terminal. - -\item\texttt{-reinstall}\par - -Reinstall a package (including dependencies for collections) -even if it already seems to be installed (i.e, is present in -the \TeX\,Live Package Database). 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\texttt{-with-doc}, \texttt{-with-src}\par - -The \texttt{install-tl} program provides the option of -omitting 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 -\texttt{-reinstall}, as in -\begin{center} - \texttt{tlmgr install -reinstall -with-doc -with-src} \textsl{pkgs} -\end{center} - -\item\texttt{-no-depends}\par - -Do not install dependencies. (By default, installing a -package ensures that all dependencies of this package are -fulfilled.) - -\end{description} - -\par\noindent -The \texttt{install} action does not -automatically add new symlinks in system directories; you -need to run -\begin{center} - \texttt{tlmgr path add} -\end{center} -yourself if you are using this feature and want new symlinks -added; see Section~\ref{path}. - -\clearpage - -\subsection{The {\tt update} Action} -\label{update} - -\paragraph{Usage:} - -\begin{list}{}{} -\item \texttt{tlmgr update} \textsl{pkgs} -\end{list} -Updates the packages given as arguments to the latest -version available at the installation source. Either -\texttt{-all} or at least one package name must be -specified. - -\paragraph{Options for {\tt update}:} - -\begin{description} - -\item\texttt{-all}\par - -Update all installed packages (except for \texttt{tlmgr} -itself). If updates to \texttt{tlmgr} itself are listed, -this gives an error, unless also the option \texttt{-force} -or \texttt{-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), \texttt{tlmgr} will remove the package in the -local installation. This is called ``auto-remove'' and is -announced as such when using the option \texttt{-list}. - -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 \texttt{-list}. - -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 \texttt{tlmgr remove -force} on -them. (See the \texttt{remove} action documentation.) -To reinstall any such forcibly removed packages use -\texttt{-reinstall-forcibly-removed}. - -If you want to exclude some packages from the current update -run (e.g., due to a slow link), see the \texttt{-exclude} -option below. - -\item\texttt{-self}\par - -Update \texttt{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 \texttt{-all} -or a list of packages, then \texttt{tlmgr} will be updated -first and, if this update succeeds, the new version will be -restarted to complete the rest of the updates. - -\item\texttt{-dry-run}\par - -Nothing is actually installed; instead, the actions to -be performed are written to the terminal. This is a more -detailed report than using \texttt{-list}. - -\item\texttt{-list} [\textsl{pkg}]\par - -Concisely list the packages which would be updated, newly -installed, or removed, without actually changing anything. -If \texttt{-all} is also given, all available updates are -listed. If \texttt{-self} is given, but not \texttt{-all}, -only updates to the critical packages (\texttt{tlmgr}, -\TeX\,Live infrastructure, Perl on Windows, etc.) are listed. - -If neither \texttt{-all} nor \texttt{-self} is given, and -in addition no \textsl{pkg} is given, then \texttt{-all} is -assumed. Thus, \mbox{\texttt{tlmgr update -list}} is the -same as \mbox{\texttt{tlmgr update -list -all}}. If neither -\texttt{-all} nor \texttt{-self} is given, but specific -package names are given, those packages are checked for -updates. - -\item\texttt{-exclude} \textsl{pkg}\par - -Exclude \textsl{pkg} from the update process. If this option -is given more than once, its arguments accumulate. - -An argument \textsl{pkg} excludes both the package -\textsl{pkg} itself and any related platform-specific -packages. For example, - -\begin{center} - \texttt{tlmgr update -all -exclude a2ping} -\end{center} - -will not update \texttt{a2ping}, \texttt{a2ping.i386-linux}, -or any other \mbox{\texttt{a2ping}.xxx} 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, \texttt{tlmgr} -quits with an error message. Excludes are not supported in -these circumstances. - - - -\item\texttt{-no-depends}\par - -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. - -\end{description} - -\noindent -If the package on the server is older than the package -already installed (e.g., if the selected mirror is out of -date), \texttt{tlmgr} does not downgrade. Also, packages for -uninstalled platforms are not installed. - -This action does not automatically add or remove -new symlinks in system directories. You need to run -\texttt{tlmgr path} yourself if you are using this feature -and want new symlinks added; see Section~\ref{path}. - -\clearpage - -\subsection{The {\tt remove} Action} -\label{remove} - -\paragraph{Usage:} -\begin{list}{}{} -\item \texttt{tlmgr remove} \textsl{pkgs} -\end{list} - -Remove each of the \textsl{pkgs}. Removing a collection -removes all package dependencies (unless \texttt{-no-depends} -is specified), but not any collection dependencies of that -collection. However, when removing a package, dependencies -are never removed. - - - -\paragraph{Options for \mdseries\texttt{remove}:} - -\begin{description} - -\item\texttt{-dry-run}\par - -Nothing is actually removed; instead, the actions to be -performed are written to the terminal. - -\item\texttt{-no-depends}\par - -Do not remove dependent packages. - -\item\texttt{-all}\par - -Uninstalls all of \TeX\,Live, asking for confirmation unless -\texttt{-force} is also specified. - -\end{description} - -\par\noindent -The \texttt{remove} action does not automatically remove -symlinks in system directories; you need to run -\begin{center} -\texttt{tlmgr path remove} -\end{center} -yourself if you are using this feature and want stale -symlinks removed; see Section~\ref{path}. - -\clearpage - -\subsection{The {\tt option} Action} -\label{option} - -\paragraph{Usage:} - -\begin{list}{}{} -\item \texttt{tlmgr option} -\item \texttt{tlmgr option help} -\item \texttt{tlmgr option} \textsl{key} -\item \texttt{tlmgr option} \textsl{key value} -\end{list} - -The first form shows the global \TeX\,Live settings currently -saved with a short description and the \texttt{key} -used for changing it in parentheses. The second form is -similar, but also shows options which can be defined but -are not currently set to any value. In the third form, the -setting for \textsl{key} is displayed. In the fourth form, -\textsl{key} is set to \textsl{value}. - -Some of the possible values for \textsl{key} are (run \texttt{tlmgr -option help} for the definitive list): - -\begin{center} -\begin{small} -\begin{tabular}{@{\ttfamily}ll} - repository &default package repository,\\ - docfiles & install documentation files,\\ - srcfiles & install source files,\\ - sys\_bin & directory to which executables are linked by the \texttt{path} action\\ - sys\_man & directory to which man pages are linked by the \texttt{path} action\\ - sys\_info& directory to which info files are linked by the \texttt{path} action\\ - desktop\_integration & Windows-only: create Start menu shortcuts\\ - fileassocs& Windows-only: change file associations\\ - multiuser &Windows-only: install for all users\\ -\end{tabular} -\end{small} -\end{center} - -\noindent -One common use of \texttt{option} is to permanently change -the installation to get further updates from the Internet, -after originally installing from DVD\@. For example, you can -run -\begin{center}\ttfamily - tlmgr option repository ctan -\end{center} -to use a nearby CTAN mirror for future updates. - -The \texttt{docfiles} and \texttt{srcfiles} keys control the -installation of their respective file groups (documentation, -sources; grouping is approximate) per package. By default -both are enabled (\verb|1|). Either or both can be disabled -(set to \verb|0|) if disk space is limited or for minimal -testing installations, etc. When disabled, the respective -files are not downloaded at all. - -The \verb|sys_bin|, \verb|sys_man|, and \verb|sys_info| -options are used on Unix systems to control the generation -of links for executables, info files and man pages. See the -\texttt{path} action in Section~\ref{path} for details. - -The remaining options affect behavior on Windows installations. - -\begin{itemize} - \item If \texttt{desktop\_integration} is set, -then some packages will install items in a sub-folder of the Start menu for \texttt{tlmgr gui}, -documentation, etc. - \item If \texttt{fileassocs} is set, Windows file associations are made (see also the -\texttt{postaction} action). - \item If \texttt{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. -\end{itemize} -All three of these options are on by default. - -\clearpage - -\subsection{The {\tt path} Action} -\label{path} - -\paragraph{Usage:} - -\begin{list}{}{} - \item \texttt{tlmgr path [-w32mode=user|admin] add} - \item \texttt{tlmgr path [--w32mode=user|admin] remove} -\end{list} - -On Unix, adds or removes symlinks for executables, man -pages, and info pages in the system directories specified by -the respective options (see the \texttt{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: -\begin{itemize} - -\item If the user has admin rights, and the option -\texttt{-w32mode} is not given, the setting -\texttt{w32\_multi\_user} determines the location (i.e., -if it is on the system path, otherwise the user path is -changed). - -\item If the user has admin rights, and the option -\texttt{-w32mode} is given, this option determines the path -to be adjusted. - -\item If the user does not have admin rights, and the -option \texttt{-w32mode} is not given, and the setting -\texttt{w32\_multi\_user} is off, the user path is changed, -while if the setting \texttt{w32\_multi\_user} is on, a -warning is issued that the caller does not have enough -privileges. - -\item If the user does not have admin rights, and the option -\texttt{-w32mode} is given, it must be \texttt{user} and -the user path will be adjusted. If a user without admin -rights uses the option \texttt{-w32mode admin} a warning -is issued that the caller does not have enough privileges. -\end{itemize} - - -\clearpage - -\clearpage -\section{Global Options} -\label{GlobalOptions} - -\begin{description} - -\item\texttt{-\relax-help}, \texttt{-help}, \texttt{-h}, \texttt{-?}\par - -These options display reference documentation for any -action. - -\item\texttt{-\relax-version}, \texttt{-version}\par - -Displays version information about the \TeX\,Live release -and the \texttt{tlmgr} script itself. If \texttt{-v} is -also given, revision numbers for the loaded \TeX\,Live Perl -modules are shown as well. - -\item\texttt{-q}\par - -Suppresses informational messages. - -\item\texttt{-v}\par - -Displays debugging messages; can be repeated for more -output. - -\item\texttt{-command-logfile} \textsl{file}\par - -\texttt{tlmgr} logs the output of all programs invoked -(\verb|mktexlr|, \verb|mtxrun|, \verb|fmtutil|, -\verb|updmap|) to a log file, by default -\texttt{TEXMFSYSVAR/web2c/tlmgr-commands.log}. This option -allows you to specify a different \textsl{file} for the log. - -\item\texttt{-package-logfile} \textsl{file}\par - -\texttt{tlmgr} logs all package actions (\verb|install|, -\verb|remove|, \verb|update|, failed updates, -failed restores) to a log file, by default -\texttt{TEXMFSYSVAR/web2c/tlmgr.log}. This option allows you -to specify a different \textsl{file} for the log. - -\item\texttt{-pause}\par - -This option makes \texttt{tlmgr} wait for user input before -exiting. Useful on Windows to avoid disappearing command -windows. - - -\end{description} - - -\end{document} |