/home/texlive/karl/Master/tlpkg/bin/tl-update-auto

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

2 files changed, 127 insertions, 113 deletions

diff --git a/Master/texmf-dist/doc/man/man1/tlmgr.1 b/Master/texmf-dist/doc/man/man1/tlmgr.1
index 61978dc9379..95ab30a31e6 100644
--- a/Master/texmf-dist/doc/man/man1/tlmgr.1
+++ b/Master/texmf-dist/doc/man/man1/tlmgr.1
@@ -199,13 +199,13 @@ entirely in the file \f(CW\*(C`tlpkg/texlive.tlpdb\*(C'\fR).  The documentation
 .Sp
 \&\f(CW\*(C`\-\-repository\*(C'\fR changes the repository location only for the current
 run; to make a permanent change, use \f(CW\*(C`option repository\*(C'\fR (see the
-option action).
+\&\*(L"option\*(R" action).
 .Sp
 For backward compatibility and convenience, \f(CW\*(C`\-\-location\*(C'\fR and \f(CW\*(C`\-\-repo\*(C'\fR
 are accepted as aliases for this option.
 .IP "\fB\-\-gui\fR [\fIaction\fR]" 4
 .IX Item "--gui [action]"
-\&\f(CW\*(C`tlmgr\*(C'\fR has a graphical interface as well as the command-line
+\&\f(CW\*(C`tlmgr\*(C'\fR has a graphical interface as well as the command line
 interface.  You can give this option, \f(CW\*(C`\-\-gui\*(C'\fR, together with an action
 to be brought directly into the respective screen of the \s-1GUI\s0.  For
 example, running
@@ -214,7 +214,7 @@ example, running
 \&  tlmgr \-\-gui update
 .Ve
 .Sp
-starts you directly at the update screen.  Without any action, the
+starts you directly at the update screen.  If no action is given, the
 \&\s-1GUI\s0 will be started at the main screen.
 .IP "\fB\-\-gui\-lang\fR \fIllcode\fR" 4
 .IX Item "--gui-lang llcode"
@@ -227,11 +227,21 @@ necessarily completely translated) are: English (en, default), Czech
 Polish (pl), Brazilian Portuguese (pt_BR), Russian (ru), Slovak (sk),
 Slovenian (sl), Serbian (sr), Vietnamese (vi), simplified Chinese
 (zh_CN), and traditional Chinese (zh_TW).
+.IP "\fB\-\-debug\-translation\fR" 4
+.IX Item "--debug-translation"
+In \s-1GUI\s0 mode, this switch tells \f(CW\*(C`tlmgr\*(C'\fR to report any untranslated (or
+missing) messages to standard error.  This can help translators to see
+what remains to be done.
 .IP "\fB\-\-machine\-readable\fR" 4
 .IX Item "--machine-readable"
 Instead of the normal output intended for human consumption, write (to
 standard output) a fixed format more suitable for machine parsing.  See
 the \*(L"MACHINE-READABLE \s-1OUTPUT\s0\*(R" section below.
+.IP "\fB\-\-no\-execute\-actions\fR" 4
+.IX Item "--no-execute-actions"
+Suppress the execution of the execute actions as defined in the tlpsrc
+files.  Documented only for completeness, as this is only useful in
+debugging.
 .IP "\fB\-\-package\-logfile\fR \fIfile\fR" 4
 .IX Item "--package-logfile file"
 \&\f(CW\*(C`tlmgr\*(C'\fR logs all package actions (install, remove, update, failed
@@ -249,38 +259,33 @@ Windows to avoid disappearing command windows.
 .IX Item "--no-persistent-downloads"
 .PD
 For network-based installations, this option (on by default) makes
-\&\f(CW\*(C`tlmgr\*(C'\fR try to set up a persistent connection (using the Net::LWP
-Perl module).  The idea is to open and reuse only one connection per
-session between your computer and the server, instead of initiating a
-new download for each package.
+\&\f(CW\*(C`tlmgr\*(C'\fR try to set up a persistent connection (using the \f(CW\*(C`LWP\*(C'\fR Perl
+module).  The idea is to open and reuse only one connection per session
+between your computer and the server, instead of initiating a new
+download for each package.
 .Sp
 If this is not possible, \f(CW\*(C`tlmgr\*(C'\fR will fall back to using \f(CW\*(C`wget\*(C'\fR.  To
 disable these persistent connections, use \f(CW\*(C`\-\-no\-persistent\-downloads\*(C'\fR.
-.IP "\fB\-\-no\-execute\-actions\fR" 4
-.IX Item "--no-execute-actions"
-Suppress the execution of the execute actions as defined in the tlpsrc
-files.  Documented only for completeness, as this is only useful in
-debugging.
-.IP "\fB\-\-debug\-translation\fR" 4
-.IX Item "--debug-translation"
-In \s-1GUI\s0 mode, this switch makes \f(CW\*(C`tlmgr\*(C'\fR report any missing, or more
-likely untranslated, messages to standard error.  This can help
-translators to see what remains to be done.
+.IP "\fB\-\-pin\-file\fR" 4
+.IX Item "--pin-file"
+Change the pinning file location from \f(CW\*(C`TEXMFLOCAL/tlpkg/pinning.txt\*(C'\fR
+(see \*(L"Pinning\*(R" below).  Documented only for completeness, as this is
+only useful in debugging.
 .IP "\fB\-\-usermode\fR" 4
 .IX Item "--usermode"
-Activates the user mode, see \*(L"\s-1USER\s0 \s-1MODE\s0\*(R" below.
+Activates user mode for this run of \f(CW\*(C`tlmgr\*(C'\fR; see \*(L"\s-1USER\s0 \s-1MODE\s0\*(R" below.
 .IP "\fB\-\-usertree\fR \fIdir\fR" 4
 .IX Item "--usertree dir"
-Uses \fIdir\fR as user tree in user mode, seel \*(L"\s-1USER\s0 \s-1MODE\s0\*(R" below.
+Uses \fIdir\fR for the tree in user mode; see \*(L"\s-1USER\s0 \s-1MODE\s0\*(R" below.
 .PP
 The standard options for TeX Live programs are also accepted:
 \&\f(CW\*(C`\-\-help/\-h/\-?\*(C'\fR, \f(CW\*(C`\-\-version\*(C'\fR, \f(CW\*(C`\-q\*(C'\fR (no informational messages), \f(CW\*(C`\-v\*(C'\fR
 (debugging messages, can be repeated).  For the details about these, see
-the TeXLive::TLUtils documentation.
+the \f(CW\*(C`TeXLive::TLUtils\*(C'\fR documentation.
 .PP
 The \f(CW\*(C`\-\-version\*(C'\fR option shows version information about the TeX Live
-release and about the \f(CW\*(C`tlmgr\*(C'\fR script itself.  If \f(CW\*(C`\-v\*(C'\fR is given as
-well, revision number for the used TeX Live Perl modules are shown, too.
+release and about the \f(CW\*(C`tlmgr\*(C'\fR script itself.  If \f(CW\*(C`\-v\*(C'\fR is also given,
+revision number for the loaded TeX Live Perl modules are shown, too.
 .SH "ACTIONS"
 .IX Header "ACTIONS"
 .SS "help"
@@ -577,6 +582,11 @@ are listed.
 In addition to the normal data displayed, also display information for
 given packages from the corresponding taxonomy (or all of them).  See
 \&\*(L"\s-1TAXONOMIES\s0\*(R" below for details.
+.SS "init-usertree"
+.IX Subsection "init-usertree"
+Sets up a texmf tree for so-called user mode management, either the
+default user tree (\f(CW\*(C`TEXMFHOME\*(C'\fR), or one specified on the command line
+with \f(CW\*(C`\-\-usertree\*(C'\fR.  See \*(L"\s-1USER\s0 \s-1MODE\s0\*(R" below.
 .SS "install [\fIoption\fP]... \fIpkg\fP..."
 .IX Subsection "install [option]... pkg..."
 Install each \fIpkg\fR given on the command line. By default this installs
@@ -755,7 +765,7 @@ those extra settings at present.
 .IX Subsection "path [--w32mode=user|admin] [add|remove]"
 On Unix, merely adds or removes symlinks for binaries, man pages, and
 info pages in the system directories specified by the respective options
-(see the option description above).  Does not change any
+(see the \*(L"option\*(R" description above).  Does not change any
 initialization files, either system or personal.
 .PP
 On Windows, the registry part where the binary directory is added or
@@ -779,7 +789,7 @@ user without admin rights uses the option \f(CW\*(C`\-\-w32mode admin\*(C'\fR a
 is issued that the caller does not have enough privileges.
 .SS "pinning"
 .IX Subsection "pinning"
-The \f(CW\*(C`pinning\*(C'\fR action manages the pinning file, see Pinning below.
+The \f(CW\*(C`pinning\*(C'\fR action manages the pinning file, see \*(L"Pinning\*(R" below.
 .ie n .IP """pinning show""" 4
 .el .IP "\f(CWpinning show\fR" 4
 .IX Item "pinning show"
@@ -1188,99 +1198,91 @@ Also, \f(CW\*(C`update \-\-list\*(C'\fR is still performed regardless of this op
 If the package on the server is older than the package already installed
 (e.g., if the selected mirror is out of date), \f(CW\*(C`tlmgr\*(C'\fR does not
 downgrade.  Also, packages for uninstalled platforms are not installed.
-.SS "init-usertree"
-.IX Subsection "init-usertree"
-sets up the default user tree (\f(CW\*(C`TEXMFHOME\*(C'\fR) or the one specified
-on the command line using \f(CW\*(C`\-\-usertree\*(C'\fR for user mode management.
-See \*(L"\s-1USER\s0 \s-1MODE\s0\*(R" below.
 .SH "USER MODE"
 .IX Header "USER MODE"
-\&\fB\s-1WARNING\s0\fR \fB\s-1WARNING\s0\fR \fB\s-1WARNING\s0\fR 
-This is very much work in progress
-and experimental. Expect breakage, and the need to reinstall your 
-user tree a new.
-.PP
-\&\f(CW\*(C`tlmgr\*(C'\fR provides a restricted way to manage arbitrary texmf trees
-in the same way as the installation. This allows a user without write
-permissions to the installation location to update/install packages
-into a user tree.
-.PP
-\&\f(CW\*(C`tlmgr\*(C'\fR is set into user mode by giving the command line option 
-\&\f(CW\*(C`\-\-usermode\*(C'\fR. It will not switch automatically, nor does it support
-a config file by now. Thus, this option has to be given every time.
-.PP
-This mode of \f(CW\*(C`tlmgr\*(C'\fR works on a user tree, which by default will be
-the value of \f(CW\*(C`TEXMFHOME\*(C'\fR, but can be overridden with the command line
-option \f(CW\*(C`\-\-usertree\*(C'\fR. In the following when we speak of the user tree
+\&\fB\s-1WARNING:\s0\fR This is new work in \s-1TL\s0 2013.  Expect breakage, and the need
+to reinstall your user tree.
+.PP
+\&\f(CW\*(C`tlmgr\*(C'\fR 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.
+.PP
+\&\f(CW\*(C`tlmgr\*(C'\fR is switched into user mode with the command line option
+\&\f(CW\*(C`\-\-usermode\*(C'\fR.  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.
+.PP
+This mode of \f(CW\*(C`tlmgr\*(C'\fR works on a user tree, by default the value of the
+\&\f(CW\*(C`TEXMFHOME\*(C'\fR variable.  This can be overridden with the command line
+option \f(CW\*(C`\-\-usertree\*(C'\fR.  In the following when we speak of the user tree
 we mean either \f(CW\*(C`TEXMFHOME\*(C'\fR or the one given on the command line.
 .PP
-Not all actions are allowed in user mode, \f(CW\*(C`tlmgr\*(C'\fR will warn you and
-not carry out this action. The actions of \f(CW\*(C`tlmgr\*(C'\fR can be classified into
-those that don't need write permissions and thus are working the same
-in user mode or normal mode. Currently these are 
-\&\fBhelp\fR, \fBversion\fR, \fBsearch\fR, \fBshow\fR, \fBlist\fR, \fBcheck\fR, \fBprint-arch\fR.
+Not all actions are allowed in user mode; \f(CW\*(C`tlmgr\*(C'\fR will warn you and not
+carry out any problematic actions.  Currently not supported (and
+probably will never be) is the \f(CW\*(C`platform\*(C'\fR action.  The \f(CW\*(C`gui\*(C'\fR action is
+currently not supported, but may be in a future release.
 .PP
-Most of the actions dealing with package management on the other hand
-need write permissions, and behave differently:
-\&\fBinstall\fR, \fBupdate\fR, \fBremove\fR, \fBoption\fR, \fBpaper\fR, \fBgenerate\fR,
-\&\fBbackup\fR, \fBrestore\fR, \fBuninstall\fR, \fBsymlinks\fR.
+Some \f(CW\*(C`tlmgr\*(C'\fR actions don't need any write permissions and thus work the
+same in user mode and normal mode.  Currently these are: \f(CW\*(C`check\*(C'\fR,
+\&\f(CW\*(C`help\*(C'\fR, \f(CW\*(C`list\*(C'\fR, \f(CW\*(C`print\-platform\*(C'\fR, \f(CW\*(C`search\*(C'\fR, \f(CW\*(C`show\*(C'\fR, \f(CW\*(C`version\*(C'\fR.
 .PP
-Currently not supported (and probably will never be) is the \fBarch\fR
-action.
-.PP
-As for the \fBgui\fR action it is currently not supported, but might be
-in future.
+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: \f(CW\*(C`install\*(C'\fR, \f(CW\*(C`update\*(C'\fR, \f(CW\*(C`remove\*(C'\fR, \f(CW\*(C`option\*(C'\fR, \f(CW\*(C`paper\*(C'\fR,
+\&\f(CW\*(C`generate\*(C'\fR, \f(CW\*(C`backup\*(C'\fR, \f(CW\*(C`restore\*(C'\fR, \f(CW\*(C`uninstall\*(C'\fR, \f(CW\*(C`symlinks\*(C'\fR.
 .PP
 Before using \f(CW\*(C`tlmgr\*(C'\fR in user mode, you have to set up the user tree
-with the \fBinit-usertree\fR action. This will create \f(CW\*(C`USERTREE/web2c\*(C'\fR,
-\&\f(CW\*(C`USERTREE/tlpkg/tlpobj\*(C'\fR and set up a minimal \f(CW\*(C`USERTREE/tlpkg/texlive.tlpdb\*(C'\fR.
-From then on you can use the supported actions as normal by adding
-the \f(CW\*(C`\-\-usermode\*(C'\fR command line switch.
-.PP
-In user mode the file \f(CW\*(C`USERTREE/tlpkg/texlive.tlpdb\*(C'\fR contains only the 
-packages that have been installed into the user tree \f(CW\*(C`USERTREE\*(C'\fR using
-\&\f(CW\*(C`tlmgr\*(C'\fR, plus additional options in the virtual package 
-00texlive.installation (like with the main installation's texlive.tlpdb).
+with the \f(CW\*(C`init\-usertree\*(C'\fR action.  This creates \fIusertree\fR\f(CW\*(C`/web2c\*(C'\fR and
+\&\fIusertree\fR\f(CW\*(C`/tlpkg/tlpobj\*(C'\fR, and a minimal
+\&\fIusertree\fR\f(CW\*(C`/tlpkg/texlive.tlpdb\*(C'\fR.  At that point, you can tell
+\&\f(CW\*(C`tlmgr\*(C'\fR to do the (supported) actions by adding the \f(CW\*(C`\-\-usermode\*(C'\fR
+command line option.
+.PP
+In user mode the file \fIusertree\fR\f(CW\*(C`/tlpkg/texlive.tlpdb\*(C'\fR contains only
+the packages that have been installed into the user tree using \f(CW\*(C`tlmgr\*(C'\fR,
+plus additional options from the ``virtual'' package
+\&\f(CW\*(C`00texlive.installation\*(C'\fR (similar to the main installation's
+\&\f(CW\*(C`texlive.tlpdb\*(C'\fR).
 .PP
 All actions on packages in user mode can only be carried out on packages
-that are marked as \fBrelocatable\fR. Basically that means that the contained
-files all reside in the \f(CW\*(C`texmd\-dist\*(C'\fR tree. \fB\s-1NOTE\s0\fR That already excludes
-all binary packages! Of the currently about 1900 packages the majority, 
-currently about 1750, are relocatable, i.e., they can be installed into 
-a user tree.
+that are known as \f(CW\*(C`relocatable\*(C'\fR.  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.
 .PP
 Description of changes of actions in user mode:
-.SS "install"
+.PP
+\fIinstall\fR
 .IX Subsection "install"
-in usermode the tlmgr action install will check that the package
-and all depending packages are either all relocated, or those that
-are not relocated are already installed in the system installation.
-If this is true it will unpack all containers to be installed into
-the user tree (\s-1TEXMFHOME\s0 or the value of \-\-user\-tree) and add the
-respective packages to the user texlive.tlpdb (creating it if there
-has non be created till now).
-.PP
-Currently installing a collection installs all depending packages,
-but in contrast to normal mode does not install depending collections.
-So in *normal* mode tlmgr install collection-context would install
-collection-metapost, c\-basic, c\-documentation-base, too. In *usermode*
-only the packages mentioned in collection-context are installed.
+.PP
+In user mode, the \f(CW\*(C`install\*(C'\fR 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 \f(CW\*(C`TEXMFHOME\*(C'\fR or
+the value of \f(CW\*(C`\-\-usertree\*(C'\fR) and add the respective packages to the user
+tree's \f(CW\*(C`texlive.tlpdb\*(C'\fR (creating it if need be).
+.PP
+Currently installing a collection in user mode installs all dependent
+packages, but in contrast to normal mode, does \fInot\fR install dependent
+collections.  For example, in normal mode \f(CW\*(C`tlmgr install
+collection\-context\*(C'\fR would install \f(CW\*(C`collection\-basic\*(C'\fR and other
+collections, while in user mode, \fIonly\fR the packages mentioned in
+\&\f(CW\*(C`collection\-context\*(C'\fR are installed.
 .SS "backup, restore, remove, update"
 .IX Subsection "backup, restore, remove, update"
-in usermode the tlmgr action update will check that all packages
-to be updated are installed in the user tree, otherwise it behaves
-exactely like the system tlmgr.
-.SS "option"
-.IX Subsection "option"
-only acts upon the user's texlive.tlpdb
-.SS "paper"
-.IX Subsection "paper"
-changes configuration files in user tree
-.SS "generate"
-.IX Subsection "generate"
+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.
+.SS "generate, option, paper"
+.IX Subsection "generate, option, paper"
+In user mode, these actions operate only on the user tree's
+configuration files and/or \f(CW\*(C`texlive.tlpdb\*(C'\fR.
 creates configuration files in user tree
 .PP
-\&\fB\s-1WARNING\s0 \s-1WARNING\s0 \s-1WARNING\s0\fR Be again warned that this is very experimental!
+\&\fB\s-1WARNING\s0\fR repeated: this is still has to be considered experimental!
+Please report bugs to \f(CW\*(C`tex\-live@tug.org\*(C'\fR as usual
 .SH "TLMGR CONFIGURATION FILE"
 .IX Header "TLMGR CONFIGURATION FILE"
 A small subset of the command line options can be set in a config file
@@ -1315,18 +1317,22 @@ a given area.
 .PP
 There are three different taxonomies, specified by the following
 options:
-.IP "\fB\-\-keyword\fR" 4
+.ie n .IP """\-\-keyword""" 4
+.el .IP "\f(CW\-\-keyword\fR" 4
 .IX Item "--keyword"
 The keywords, as specified at <http://az.ctan.org/keyword>.
-.IP "\fB\-\-functionality\fR" 4
+.ie n .IP """\-\-functionality""" 4
+.el .IP "\f(CW\-\-functionality\fR" 4
 .IX Item "--functionality"
 The ``by\-topic'' categorization created by J\e"urgen Fenn, as specified
 at http://az.ctan.org/characterization/by\-function <http://az.ctan.org/characterization/by-function>.
-.IP "\fB\-\-characterization\fR" 4
+.ie n .IP """\-\-characterization""" 4
+.el .IP "\f(CW\-\-characterization\fR" 4
 .IX Item "--characterization"
 Both the primary and secondary functionalities, as specified at
 <http://az.ctan.org/characterization/choose_dimen>.
-.IP "\fB\-\-taxonomy\fR" 4
+.ie n .IP """\-\-taxonomy""" 4
+.el .IP "\f(CW\-\-taxonomy\fR" 4
 .IX Item "--taxonomy"
 Operate on all the taxonomies.
 .PP
@@ -1569,13 +1575,15 @@ action needs the option \f(CW\*(C`backupdir\*(C'\fR set (see \f(CW\*(C`Options \
 .SS "Menu bar"
 .IX Subsection "Menu bar"
 The following entries can be found in the menu bar:
-.IP "\fBtlmgr\fR menu" 4
+.ie n .IP """tlmgr"" menu" 4
+.el .IP "\f(CWtlmgr\fR menu" 4
 .IX Item "tlmgr menu"
 The items here load various repositories: the default as specified in
 the TeX Live database, the default network repository, the repository
 specified on the command line (if any), and an arbitrarily
 manually-entered one.  Also has the so-necessary \f(CW\*(C`quit\*(C'\fR operation.
-.IP "\fBOptions menu\fR" 4
+.ie n .IP """Options menu""" 4
+.el .IP "\f(CWOptions menu\fR" 4
 .IX Item "Options menu"
 Provides access to several groups of options: \f(CW\*(C`Paper\*(C'\fR (configuration of
 default paper sizes), \f(CW\*(C`Platforms\*(C'\fR (only on Unix, configuration of the
@@ -1593,7 +1601,8 @@ disable the automatic installation of new packages, and to disable the
 automatic removal of packages deleted from the server.  Playing with the
 choices of what is or isn't installed may lead to an inconsistent TeX Live
 installation; e.g., when a package is renamed.
-.IP "\fBActions menu\fR" 4
+.ie n .IP """Actions menu""" 4
+.el .IP "\f(CWActions menu\fR" 4
 .IX Item "Actions menu"
 Provides access to several actions: update the filename database (aka
 \&\f(CW\*(C`ls\-R\*(C'\fR, \f(CW\*(C`mktexlsr\*(C'\fR, \f(CW\*(C`texhash\*(C'\fR), rebuild all formats (\f(CW\*(C`fmtutil\-sys
@@ -1603,7 +1612,8 @@ Windows).
 .Sp
 The final action is to remove the entire TeX Live installation (also not
 on Windows).
-.IP "\fBHelp menu\fR" 4
+.ie n .IP """Help menu""" 4
+.el .IP "\f(CWHelp menu\fR" 4
 .IX Item "Help menu"
 Provides access to the TeX Live manual (also on the web at
 <http://tug.org/texlive/doc.html>) and the usual ``About'' box.
@@ -1618,9 +1628,11 @@ information it needs by reading stdout.
 Currently this option only applies to the 
 update, the
 install, and the
-option actions.
-.SS "update and install actions"
-.IX Subsection "update and install actions"
+\&\*(L"option\*(R" actions.
+.PP
+\fIupdate, install\fR
+.IX Subsection "update, install"
+.PP
 The output format is as follows:
 .PP
 .Vb 7
@@ -1727,8 +1739,10 @@ The run time since start of installations or updates.
 .IP "\fIesttot\fR" 4
 .IX Item "esttot"
 The estimated total time.
-.SS "option action"
-.IX Subsection "option action"
+.PP
+\fIoption\fR
+.IX Subsection "option"
+.PP
 The output format is as follows:
 .PP
 .Vb 1
diff --git a/Master/texmf-dist/doc/man/man1/tlmgr.man1.pdf b/Master/texmf-dist/doc/man/man1/tlmgr.man1.pdf
index 96480aae439..9bab2825b73 100644
--- a/Master/texmf-dist/doc/man/man1/tlmgr.man1.pdf
+++ b/Master/texmf-dist/doc/man/man1/tlmgr.man1.pdf