add POD documentation for pinning action,

restructure POD action docs to be in alphabetic order (after the
initial help and version)


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

1 files changed, 558 insertions, 529 deletions

diff --git a/Master/texmf/scripts/texlive/tlmgr.pl b/Master/texmf/scripts/texlive/tlmgr.pl
index eaa3134334c..afa73537ef8 100755
--- a/Master/texmf/scripts/texlive/tlmgr.pl
+++ b/Master/texmf/scripts/texlive/tlmgr.pl
@@ -1,7 +1,7 @@
 #!/usr/bin/env perl
 # $Id$
 #
-# Copyright 2008, 2009, 2010, 2011, 2012, 2013 Norbert Preining
+# Copyright 2008-2013 Norbert Preining
 # This file is licensed under the GNU General Public License version 2
 # or any later version.
 
@@ -5924,420 +5924,392 @@ Gives version information (same as C<--version>).
 
 If C<-v> has been given the revisions of the used modules are reported, too.
 
-=head2 gui
-
-Start the graphical user interface. See B<GUI> below.
+=head2 backup [--clean[=I<N>]] [--backupdir I<dir>] [--all | I<pkg>]...
 
+If the C<--clean> option is not specified, this action makes a backup of
+the given packages, or all packages given C<--all>. These backups are
+saved to the value of the C<--backupdir> option, if that is an existing and
+writable directory. If C<--backupdir> is not given, the C<backupdir>
+option setting in the TLPDB is used, if present.  If both are missing,
+no backups are made.
 
-=head2 install [I<option>]... I<pkg>...
+If the C<--clean> option is specified, backups are pruned (removed)
+instead of saved. The optional integer value I<N> may be specified to
+set the number of backups that will be retained when cleaning. If C<N>
+is not given, the value of the C<autobackup> option is used. If both are
+missing, an error is issued. For more details of backup pruning, see
+the C<option> action.
 
-Install each I<pkg> given on the command line. By default this installs
-all packages on which the given I<pkg>s are dependent, also.  Options:
+Options:
 
 =over 4
 
-=item B<--file>
+=item B<--backupdir> I<directory>
 
-Instead of fetching a package from the installation repository, use
-the packages files given on the command line. These files need
-to be proper TeX Live package files (with contained tlpobj file).
+Overrides the C<backupdir> option setting in the TLPDB.
+The I<directory> argument is required and must specify an existing,
+writable directory where backups are to be placed.
 
-=item B<--reinstall>
+=item B<--all>
 
-Reinstall a package (including dependencies for collections) even if it
-seems to be already installed (i.e, is present in the TLPDB).  This is
-useful to recover from accidental removal of files in the hierarchy.
+If C<--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
+C<--clean> is specified, all packages are pruned.
 
-When re-installing, only dependencies on normal packages are followed
-(not those of category Scheme or Collection).
+=item B<--clean>[=I<N>]
 
-=item B<--no-depends>
+Instead of making backups, prune the backup directory of old backups, as
+explained above. The optional integer argument I<N> overrides the
+C<autobackup> option set in the TLPDB.  You must use C<--all> or a list
+of packages together with this option, as desired.
 
-Do not install dependencies.  (By default, installing a package ensures
-that all dependencies of this package are fulfilled.)
+=item B<--dry-run>
 
-=item B<--no-depends-at-all>
+Nothing is actually backed up or removed; instead, the actions to be
+performed are written to the terminal.
 
-When you install a package which ships binary files the respective
-binary package will also be installed.  That is, for a package C<foo>,
-the package C<foo.i386-linux> will also be installed on an C<i386-linux>
-system.  This switch suppresses this behavior, and also implies
-C<--no-depends>.  Don't use it unless you are sure of what you are
-doing.
+=back
 
-=item B<--dry-run>
 
-Nothing is actually installed; instead, the actions to be performed are
-written to the terminal.
+=head2 candidates
 
-=item B<--force>
+=over 4
 
-If updates to C<tlmgr> itself (or other parts of the basic
-infrastructure) are present, C<tlmgr> will bail out and not perform the
-installation unless this option is given.  Not recommended.
+=item B<candidates I<pkg>>
 
-=back
+Shows the available candidate repositories for package I<pkg>.
+See L</"MULTIPLE REPOSITORIES"> below.
 
 
-=head2 update [I<option>]... [I<pkg>]...
+=back
 
-Updates the packages given as arguments to the latest version available
-at the installation source.  Either C<--all> or at least one I<pkg> name
-must be specified.  Options:
+=head2 check [I<option>]... [files|depends|executes|runfiles|all]
+
+Executes one (or all) check(s) on the consistency of the installation.
 
 =over 4
 
-=item B<--all>
+=item B<files>
 
-Update all installed packages except for C<tlmgr> itself.  Thus, if
-updates to C<tlmgr> itself are present, this will simply give an error,
-unless also the option C<--force> or C<--self> is given.  (See below.)
+Checks that all files listed in the local TLPDB (C<texlive.tlpdb>) are
+actually present, and lists those missing.
 
-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.
+=item B<depends>
 
-This means that if a package has been removed on the server (and thus
-has also been removed from the respective collection), C<tlmgr> will
-remove the package in the local installation.  This is called
-``auto-remove'' and is announced as such when using the option
-C<--list>.  This auto-removal can be suppressed using the option
-C<--no-auto-remove>.
+Lists those packages which occur as dependencies in an installed collections,
+but are themselves not installed, and those packages that are not
+contained in any collection.
 
-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 C<--list>.  This auto-installation can be
-suppressed using the option C<--no-auto-install>.
+If you call C<tlmgr check collections> this test will be carried out
+instead since former versions for C<tlmgr> called it that way.
 
-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 C<tlmgr remove --force>
-on them.  (See the C<remove> action documentation.)  To reinstall any
-such forcibly removed packages use C<--reinstall-forcibly-removed>.
+=item B<executes>
 
-If you want to exclude some packages from the current update run (e.g.,
-due to a slow link), see the C<--exclude> option below.
+Check that the files referred to by C<execute> directives in the TeX
+Live Database are present.
 
-=item B<--self>
+=item B<runfiles>
 
-Update C<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.
+List those filenames that are occurring more than one time in the runfiles.
 
-If this option is given together with either C<--all> or a list of
-packages, then C<tlmgr> will be updated first and, if this update
-succeeds, the new version will be restarted to complete the rest of the
-updates.
+=back
 
-In short:
+Options:
 
-  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!
+=over 4
 
-=item B<--dry-run>
+=item B<--use-svn>
 
-Nothing is actually installed; instead, the actions to be performed are
-written to the terminal.  This is a more detailed report than C<--list>.
+Use the output of C<svn status> instead of listing the files; for
+checking the TL development repository.
 
-=item B<--list> [I<pkg>]
+=back
 
-Concisely list the packages which would be updated, newly installed, or
-removed, without actually changing anything. 
-If C<--all> is also given, all available updates are listed.
-If C<--self> is given, but not C<--all>, only updates to the
-critical packages (tlmgr, texlive infrastructure, perl on Windows, etc.)
-are listed.
-If neither C<--all> nor C<--self> is given, and in addition no I<pkg> is
-given, then C<--all> is assumed (thus, C<tlmgr update --list> is the
-same as C<tlmgr update --list --all>).
-If neither C<--all> nor C<--self> is given, but specific package names are
-given, those packages are checked for updates.
 
-=item B<--exclude> I<pkg>
+=head2 conf [texmf|tlmgr [I<key> [I<value>]]]
 
-Exclude I<pkg> from the update process.  If this option is given more
-than once, its arguments accumulate.
+With only C<conf>, show general configuration information for TeX Live,
+including active configuration files, path settings, and more.  This is
+like the C<texconfig conf> call, but works on all supported platforms.
 
-An argument I<pkg> excludes both the package I<pkg> itself and all
-its related platform-specific packages I<pkg.ARCH>.  For example,
+With either C<conf texmf> or C<conf tlmgr> given in addition, shows all
+key/value pairs (i.e., all settings) as saved in C<ROOT/texmf.cnf> or
+the tlmgr configuration file (see below), respectively.
 
-  tlmgr update --all --exclude a2ping
+If I<key> is given in addition, shows the value of only that given
+I<key> in the respective file.
 
-will not update C<a2ping>, C<a2ping.i386-linux>, or
-any other C<a2ping.>I<ARCH> package.
+If I<value> is given in addition, I<key> is set to I<value> in the 
+respective file.  I<No error checking is done!>
 
-If this option specifies a package that would otherwise be a candidate
-for auto-installation, auto-removal, or reinstallation of a forcibly
-removed package, C<tlmgr> quits with an error message.  Excludes are not
-supported in these circumstances.
+Practical application: if the execution of (some or all) system commands
+via C<\write18> was left enabled during installation, you can disable
+it afterwards:
+  
+  tlmgr conf texmf shell_escape 0
 
-=item B<--no-auto-remove> [I<pkg>]...
+Warning: The general facility is here, but tinkering with settings in
+this way is very strongly discouraged.  Again, no error checking is
+done, so any sort of breakage is possible.
 
-Under normal circumstances C<tlmgr> tries to remove packages which have
-disappeared on the server, as described above under C<--all>.  This
-option prevents any such removals, either for all packages (with
-C<--all>), or the given I<pkg> names.
 
-=item B<--no-auto-install> [I<pkg>]...
+=head2 dump-tlpdb [--local|--remote]
 
-Under normal circumstances C<tlmgr> will install packages which are new
-on the server, as described above under C<--all>.  This option prevents
-any such automatic installation, either for all packages (with
-C<--all>), or the given I<pkg> names.
+Dump complete local or remote TLPDB to standard output, as-is.  The
+output is analogous to the C<--machine-readable> output; see
+L<MACHINE-READABLE OUTPUT> section.
 
-Furthermore, after the C<tlmgr> run using this has finished, the
-packages that would have been auto-installed I<will be considered as
-forcibly removed>.  So, if C<foobar> is the only new package on the
-server, then
+Options:
 
-  tlmgr update --all --no-auto-install
+=over 4
 
-is equivalent to
+=item B<--local>
 
-  tlmgr update --all
-  tlmgr remove --force foobar
+Dump the local tlpdb.
 
-=item B<--reinstall-forcibly-removed>
+=item B<--remote>
 
-Under normal circumstances C<tlmgr> will not install packages that have
-been forcibly removed by the user; that is, removed with C<remove
---force>, or whose installation was prohibited by C<--no-auto-install>
-during an earlier update.
+Dump the remote tlpdb.
 
-This option makes C<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:
+=back
 
-  tlmgr update --reinstall-forcibly-removed --all
+Exactly one of C<--local> and C<--remote> must be given.
 
-=item B<--backup> and B<--backupdir> I<directory>
+In either case, the first line of the output specifies the repository
+location, in this format:
 
-These two options control the creation of backups of packages I<before>
-updating; that is, backup of packages as currently installed.  If
-neither of these options are given, no backup package will be saved. If
-C<--backupdir> is given and specifies a writable directory then a backup
-will be made in that location. If only C<--backup> is given, then a
-backup will be made to the directory previously set via the C<option>
-action (see below). If both are given then a backup will be made to the
-specified I<directory>.
+  "location-url" "\t" location
 
-You can set options via the C<option> action to automatically create
-backups for all packages, and/or keep only a certain number of
-backups.  Please see the C<option> action for details.
+where C<location-url> is the literal field name, followed by a tab, and
+I<location> is the file or url to the repository.
 
-C<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 C<--backup> option is to allow you to save a persistent backup
-in case the actual I<content> of the update causes problems, e.g.,
-introduces an incompatibility.
+Line endings may be either LF or CRLF depending on the current platform.
 
-The C<restore> action explains how to restore from a backup.
 
-=item B<--no-depends>
+=head2 generate [I<option>]... I<what>
 
-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.
+=over 4
 
-=item B<--no-depends-at-all>
+=item B<generate language>
 
-See above under B<install> (and beware).
+=item B<generate language.dat>
 
-=item B<--force>
+=item B<generate language.def>
 
-Force update of normal packages, without updating C<tlmgr> itself 
-(unless the C<--self> option is also given).  Not recommended.
+=item B<generate language.dat.lua>
 
-Also, C<update --list> is still performed regardless of this option.
+=item B<generate fmtutil>
 
 =back
 
-If the package on the server is older than the package already installed
-(e.g., if the selected mirror is out of date), C<tlmgr> does not
-downgrade.  Also, packages for uninstalled platforms are not installed.
-
-
-=head2 backup [--clean[=I<N>]] [--backupdir I<dir>] [--all | I<pkg>]...
-
-If the C<--clean> option is not specified, this action makes a backup of
-the given packages, or all packages given C<--all>. These backups are
-saved to the value of the C<--backupdir> option, if that is an existing and
-writable directory. If C<--backupdir> is not given, the C<backupdir>
-option setting in the TLPDB is used, if present.  If both are missing,
-no backups are made.
+The C<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 C<tlmgr> routinely call C<generate> for
+all of these files.
 
-If the C<--clean> option is specified, backups are pruned (removed)
-instead of saved. The optional integer value I<N> may be specified to
-set the number of backups that will be retained when cleaning. If C<N>
-is not given, the value of the C<autobackup> option is used. If both are
-missing, an error is issued. For more details of backup pruning, see
-the C<option> action.
+For managing your own fonts, please read the C<updmap --help>
+information and/or L<http://tug.org/fonts/fontinstall.html>.
 
-Options:
+In more detail: C<generate> remakes any of the configuration files
+C<language.dat>, C<language.def>, C<language.dat.lua>, and
+C<fmtutil.cnf>, from the information present in the local TLPDB, plus
+locally-maintained files.
 
-=over 4
+The locally-maintained files are C<language-local.dat>,
+C<language-local.def>, C<language-local.dat.lua>, or
+C<fmtutil-local.cnf>, searched for in C<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.
 
-=item B<--backupdir> I<directory>
+(Historical note: The formerly supported C<updmap-local.cfg> is no longer
+read, since C<updmap> now supports multiple C<updmap.cfg> files.  Thus,
+local additions can and should be put into an C<updmap.cfg> file in
+C<TEXMFLOCAL>.  The C<generate updmap> action no longer exists.)
 
-Overrides the C<backupdir> option setting in the TLPDB.
-The I<directory> argument is required and must specify an existing,
-writable directory where backups are to be placed.
+Local files specify entries to be disabled with a comment line, namely
+one of these:
 
-=item B<--all>
+  #!NAME
+  %!NAME
+  --!NAME
 
-If C<--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
-C<--clean> is specified, all packages are pruned.
+where C<fmtutil.cnf> uses C<#>, C<language.dat> and C<language.def> use
+C<%>, and C<language.dat.lua> use C<-->.  In all cases, the I<name> is
+the respective format name or hyphenation pattern identifier.
+Examples:
 
-=item B<--clean>[=I<N>]
+  #!pdflatex
+  %!german
+  --!usenglishmax
 
-Instead of making backups, prune the backup directory of old backups, as
-explained above. The optional integer argument I<N> overrides the
-C<autobackup> option set in the TLPDB.  You must use C<--all> or a list
-of packages together with this option, as desired.
+(Of course, you're not likely to actually want to disable those
+particular items.  They're just examples.)
 
-=item B<--dry-run>
+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.
 
-Nothing is actually backed up or removed; instead, the actions to be
-performed are written to the terminal.
+The form C<generate language> recreates all three files C<language.dat>,
+C<language.def>, and C<language.dat.lua>, while the forms with an
+extension recreates only that given language file.
 
-=back
+Options:
 
+=over 4
 
-=head2 restore [--backupdir I<dir>] [--all | I<pkg> [I<rev>]]
+=item B<--dest> I<output_file>
 
-Restore a package from a previously-made backup.
+specifies the output file (defaults to the respective location in
+C<TEXMFSYSVAR>).  If C<--dest> is given to C<generate language>, it
+serves as a basename onto which C<.dat> will be appended for the name of
+the C<language.dat> output file, C<.def> will be appended to the value
+for the name of the C<language.def> output file, and C<.dat.lua> to the
+name of the C<language.dat.lua> file.  (This is just to avoid
+overwriting; if you want a specific name for each output file, we
+recommend invoking C<tlmgr> twice.)
 
-If C<--all> is given, try to restore the latest revision of all 
-package backups found in the backup directory.
+=item B<--localcfg> I<local_conf_file>
 
-Otherwise, if neither I<pkg> nor I<rev> are given, list the available backup
-revisions for all packages.
+specifies the (optional) local additions (defaults to the respective
+location in C<TEXMFLOCAL>).
 
-With I<pkg> given but no I<rev>, list all available backup revisions of
-I<pkg>.
+=item B<--rebuild-sys>
 
-When listing available packages tlmgr shows the revision and in 
-parenthesis the creation time if available (in format yyyy-mm-dd hh:mm).
+tells tlmgr to run necessary programs after config files have been
+regenerated. These are:
+C<fmtutil-sys --all> after C<generate fmtutil>,
+C<fmtutil-sys --byhyphen .../language.dat> after C<generate language.dat>,
+and
+C<fmtutil-sys --byhyphen .../language.def> after C<generate language.def>.
 
-With both I<pkg> and I<rev>, tries to restore the package from the
-specified backup.
+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.
 
-Options:
+=back
 
-=over 4
+The respective locations are as follows:
 
-=item B<--all>
+  tex/generic/config/language.dat (and language-local.dat);
+  tex/generic/config/language.def (and language-local.def);
+  tex/generic/config/language.dat.lua (and language-local.dat.lua);
+  web2c/fmtutil.cnf (and fmtutil-local.cnf);
 
-Try to restore the latest revision of all package backups found in the
-backup directory. Additional non-option arguments (like I<pkg>) are not
-allowed.
 
-=item B<--backupdir> I<directory>
+=head2 gui
 
-Specify the directory where the backups are to be found. If not given it
-will be taken from the configuration setting in the TLPDB.
+Start the graphical user interface. See B<GUI> below.
 
-=item B<--dry-run>
 
-Nothing is actually restored; instead, the actions to be performed are
-written to the terminal.
+=head2 info [I<option>...] [collections|schemes|I<pkg>...]
 
-=item B<--force>
+With no argument, lists all packages available at the package
+repository, prefixing those already installed with C<i>.
 
-Don't ask questions.
+With the single word C<collections> or C<schemes> as the argument, lists
+the request type instead of all packages.
 
-=back
+With any other arguments, display information about I<pkg>: the name,
+category, short and long description, installation status, and TeX Live
+revision number.  If I<pkg> is not locally installed, searches in the
+remote installation source.
 
+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 C<revision> value
+comes directly from TL and is reliable.
 
-=head2 remove [I<option>]... I<pkg>...
+The former actions C<show> and C<list> are merged into this action,
+but are still supported for backward compatibility.
 
-Remove each I<pkg> specified.  Removing a collection removes all package
-dependencies (unless C<--no-depends> is specified), but not any
-collection dependencies of that collection.  However, when removing a
-package, dependencies are never removed.  Options:
+Options:
 
 =over 4
 
-=item B<--no-depends>
+=item B<--list>
 
-Do not remove dependent packages.
+If the option C<--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, C<--list> outputs their
+dependencies in a similar way.
 
-=item B<--no-depends-at-all>
+=item B<--only-installed>
 
-See above under B<install> (and beware).
+If this options is given,  the installation source will
+not be used; only locally installed packages, collections, or schemes
+are listed.
+(Does not work for listing of packages for now)
 
-=item B<--force>
+=item B<--taxonomy>
 
-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.
+=item B<--keyword>
 
-A package that has been removed using the C<--force> option because it
-is still listed in an installed collection or scheme will not be
-updated, and will be mentioned as B<forcibly removed> in the output of
-B<tlmgr update --list>.
+=item B<--functionality>
 
-=item B<--dry-run>
+=item B<--characterization>
 
-Nothing is actually removed; instead, the actions to be performed are
-written to the terminal.
+In addition to the normal data displayed, also display information for
+given packages from the corresponding taxonomy (or all of them).  See
+L</"TAXONOMIES"> below for details.
 
 =back
 
 
-=head2 repository
-
-=over 4
-
-=item B<repository list>
+=head2 install [I<option>]... I<pkg>...
 
-=item B<repository list I<path|tag>>
+Install each I<pkg> given on the command line. By default this installs
+all packages on which the given I<pkg>s are dependent, also.  Options:
 
-=item B<repository add I<path> [I<tag>]>
+=over 4
 
-=item B<repository remove I<path|tag>>
+=item B<--file>
 
-=item B<repository set I<path>[#I<tag>] [I<path>[#I<tag>] ...]>
+Instead of fetching a package from the installation repository, use
+the packages files given on the command line. These files need
+to be proper TeX Live package files (with contained tlpobj file).
 
-This action manages the list of repositories.  See L</"MULTIPLE
-REPOSITORIES"> below for detailed explanations.
+=item B<--reinstall>
 
-The first form (C<list>) lists all configured repositories and the
-respective tags if set. If a path, url, or tag is given after the
-C<list> keyword, it is interpreted as source from where to 
-initialize a TeX Live Database and lists the contained packages.
-This can also be an up-to-now not used repository, both locally
-and remote. If one pass in addition C<--with-platforms>, for each
-package the available platforms (if any) are listed, too.
+Reinstall a package (including dependencies for collections) even if it
+seems to be already installed (i.e, is present in the TLPDB).  This is
+useful to recover from accidental removal of files in the hierarchy.
 
-The third form (C<add>) adds a repository
-(optionally attaching a tag) to the list of repositories.  The forth
-form (C<remove>) removes a repository, either by full path/url, or by
-tag.  The last form (C<set>) sets the list of repositories to the items
-given on the command line, not keeping previous settings
+When re-installing, only dependencies on normal packages are followed
+(not those of category Scheme or Collection).
 
-In all cases, one of the repositories must be tagged as C<main>;
-otherwise, all operations will fail!
+=item B<--no-depends>
 
-=back
+Do not install dependencies.  (By default, installing a package ensures
+that all dependencies of this package are fulfilled.)
 
+=item B<--no-depends-at-all>
 
-=head2 candidates
+When you install a package which ships binary files the respective
+binary package will also be installed.  That is, for a package C<foo>,
+the package C<foo.i386-linux> will also be installed on an C<i386-linux>
+system.  This switch suppresses this behavior, and also implies
+C<--no-depends>.  Don't use it unless you are sure of what you are
+doing.
 
-=over 4
+=item B<--dry-run>
 
-=item B<candidates I<pkg>>
+Nothing is actually installed; instead, the actions to be performed are
+written to the terminal.
 
-Shows the available candidate repositories for package I<pkg>.
-See L</"MULTIPLE REPOSITORIES"> below.
+=item B<--force>
 
+If updates to C<tlmgr> itself (or other parts of the basic
+infrastructure) are present, C<tlmgr> will bail out and not perform the
+installation unless this option is given.  Not recommended.
 
 =back
 
+
 =head2 option
 
 =over 4
@@ -6437,33 +6409,6 @@ 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.
 
 
-=head2 conf [texmf|tlmgr [I<key> [I<value>]]]
-
-With only C<conf>, show general configuration information for TeX Live,
-including active configuration files, path settings, and more.  This is
-like the C<texconfig conf> call, but works on all supported platforms.
-
-With either C<conf texmf> or C<conf tlmgr> given in addition, shows all
-key/value pairs (i.e., all settings) as saved in C<ROOT/texmf.cnf> or
-the tlmgr configuration file (see below), respectively.
-
-If I<key> is given in addition, shows the value of only that given
-I<key> in the respective file.
-
-If I<value> is given in addition, I<key> is set to I<value> in the 
-respective file.  I<No error checking is done!>
-
-Practical application: if the execution of (some or all) system commands
-via C<\write18> was left enabled during installation, you can disable
-it afterwards:
-  
-  tlmgr conf texmf shell_escape 0
-
-Warning: The general facility is here, but tinkering with settings in
-this way is very strongly discouraged.  Again, no error checking is
-done, so any sort of breakage is possible.
-
-
 =head2 paper
 
 =over 4
@@ -6499,6 +6444,63 @@ settings for some programs, notably C<dvips>.  C<tlmgr> does not support
 those extra settings at present.
 
 
+=head2 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 L<option> description above).  Does not change any
+initialization files, either system or personal.
+
+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 C<--w32mode> is not given,
+the setting I<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 C<--w32mode> is given, this
+option determines the path to be adjusted.
+
+If the user does not have admin rights, and the option C<--w32mode>
+is not given, and the setting I<w32_multi_user> is off, the user path
+is changed, while if the setting I<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 C<--w32mode>
+is given, it must be B<user> and the user path will be adjusted. If a
+user without admin rights uses the option C<--w32mode admin> a warning
+is issued that the caller does not have enough privileges.
+
+
+=head2 pinning 
+
+The pinning action manages the pinning file, see L<Pinning> for details.
+
+=over 4
+
+=item B<pinning show>
+
+Shows the current pinning data.
+
+=item B<pinning check>
+
+Not implemented at the moment.
+
+=item B<pinning add I<repo> I<pgkglob> [I<pkgglob>]>
+
+Pins the packages specified by I<pkgglob> to the repo I<repo>.
+
+=item B<pinning remove I<repo> I<pgkglob> [I<pkgglob>]>
+
+If there is a the very package glob <pkgglob> recorded in the pinning file 
+for the given repo I<repo>, it is removed.
+
+=item B<pinning remove I<repo> --all>
+
+Remove all pinning data for repo I<repo>.
+
+=back
+
 =head2 platform list|add|remove I<platform>...
 
 =head2 platform set I<platform>
@@ -6538,6 +6540,32 @@ written to the terminal.
 =back
 
 
+=cut
+
+# keep the following on *ONE* line otherwise Losedows perldoc does
+# not show it!!!!
+
+=pod
+
+=head2 postaction [--w32mode=user|admin] [--fileassocmode=1|2] [--all] [install|remove] [shortcut|fileassoc|script] [I<pkg>]...
+
+Carry out the postaction C<shortcut>, C<fileassoc>, or C<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 C<--all> is given.
+
+If the option C<--w32mode> is given the value C<user>, all actions will
+only be carried out in the user-accessible parts of the
+registry/filesystem, while the value C<admin> selects the system-wide
+parts of the registry for the file associations.  If you do not have
+enough permissions, using C<--w32mode=admin> will not succeed.
+
+C<--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
+C<option fileassocs>.)
+
+
 =head2 print-platform
 
 Print the TeX Live identifier for the detected platform
@@ -6545,57 +6573,121 @@ Print the TeX Live identifier for the detected platform
 C<--print-arch> is a synonym.
 
 
-=head2 info [I<option>...] [collections|schemes|I<pkg>...]
+=head2 restore [--backupdir I<dir>] [--all | I<pkg> [I<rev>]]
 
-With no argument, lists all packages available at the package
-repository, prefixing those already installed with C<i>.
+Restore a package from a previously-made backup.
 
-With the single word C<collections> or C<schemes> as the argument, lists
-the request type instead of all packages.
+If C<--all> is given, try to restore the latest revision of all 
+package backups found in the backup directory.
 
-With any other arguments, display information about I<pkg>: the name,
-category, short and long description, installation status, and TeX Live
-revision number.  If I<pkg> is not locally installed, searches in the
-remote installation source.
+Otherwise, if neither I<pkg> nor I<rev> are given, list the available backup
+revisions for all packages.
 
-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 C<revision> value
-comes directly from TL and is reliable.
+With I<pkg> given but no I<rev>, list all available backup revisions of
+I<pkg>.
 
-The former actions C<show> and C<list> are merged into this action,
-but are still supported for backward compatibility.
+When listing available packages tlmgr shows the revision and in 
+parenthesis the creation time if available (in format yyyy-mm-dd hh:mm).
+
+With both I<pkg> and I<rev>, tries to restore the package from the
+specified backup.
 
 Options:
 
 =over 4
 
-=item B<--list>
+=item B<--all>
 
-If the option C<--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, C<--list> outputs their
-dependencies in a similar way.
+Try to restore the latest revision of all package backups found in the
+backup directory. Additional non-option arguments (like I<pkg>) are not
+allowed.
 
-=item B<--only-installed>
+=item B<--backupdir> I<directory>
 
-If this options is given,  the installation source will
-not be used; only locally installed packages, collections, or schemes
-are listed.
-(Does not work for listing of packages for now)
+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 B<--taxonomy>
+=item B<--dry-run>
 
-=item B<--keyword>
+Nothing is actually restored; instead, the actions to be performed are
+written to the terminal.
 
-=item B<--functionality>
+=item B<--force>
 
-=item B<--characterization>
+Don't ask questions.
 
-In addition to the normal data displayed, also display information for
-given packages from the corresponding taxonomy (or all of them).  See
-L</"TAXONOMIES"> below for details.
+=back
+
+
+=head2 remove [I<option>]... I<pkg>...
+
+Remove each I<pkg> specified.  Removing a collection removes all package
+dependencies (unless C<--no-depends> is specified), but not any
+collection dependencies of that collection.  However, when removing a
+package, dependencies are never removed.  Options:
+
+=over 4
+
+=item B<--no-depends>
+
+Do not remove dependent packages.
+
+=item B<--no-depends-at-all>
+
+See above under B<install> (and beware).
+
+=item B<--force>
+
+By default, removal of a package or collection that is a dependency of
+another collection or scheme is not allowed.  With this option, the
+package will be removed unconditionally.  Use with care.
+
+A package that has been removed using the C<--force> option because it
+is still listed in an installed collection or scheme will not be
+updated, and will be mentioned as B<forcibly removed> in the output of
+B<tlmgr update --list>.
+
+=item B<--dry-run>
+
+Nothing is actually removed; instead, the actions to be performed are
+written to the terminal.
+
+=back
+
+
+=head2 repository
+
+=over 4
+
+=item B<repository list>
+
+=item B<repository list I<path|tag>>
+
+=item B<repository add I<path> [I<tag>]>
+
+=item B<repository remove I<path|tag>>
+
+=item B<repository set I<path>[#I<tag>] [I<path>[#I<tag>] ...]>
+
+This action manages the list of repositories.  See L</"MULTIPLE
+REPOSITORIES"> below for detailed explanations.
+
+The first form (C<list>) lists all configured repositories and the
+respective tags if set. If a path, url, or tag is given after the
+C<list> keyword, it is interpreted as source from where to 
+initialize a TeX Live Database and lists the contained packages.
+This can also be an up-to-now not used repository, both locally
+and remote. If one pass in addition C<--with-platforms>, for each
+package the available platforms (if any) are listed, too.
+
+The third form (C<add>) adds a repository
+(optionally attaching a tag) to the list of repositories.  The forth
+form (C<remove>) removes a repository, either by full path/url, or by
+tag.  The last form (C<set>) sets the list of repositories to the items
+given on the command line, not keeping previous settings
+
+In all cases, one of the repositories must be tagged as C<main>;
+otherwise, all operations will fail!
 
 =back
 
@@ -6668,261 +6760,198 @@ Search for package names, descriptions, and taxonomies, but not files.
 =back
 
 
-=head2 dump-tlpdb [--local|--remote]
-
-Dump complete local or remote TLPDB to standard output, as-is.  The
-output is analogous to the C<--machine-readable> output; see
-L<MACHINE-READABLE OUTPUT> section.
+=head2 uninstall
 
-Options:
+Uninstalls the entire TeX Live installation.  Options:
 
 =over 4
 
-=item B<--local>
-
-Dump the local tlpdb.
-
-=item B<--remote>
+=item B<--force>
 
-Dump the remote tlpdb.
+Do not ask for confirmation, remove immediately.
 
 =back
 
-Exactly one of C<--local> and C<--remote> must be given.
-
-In either case, the first line of the output specifies the repository
-location, in this format:
-
-  "location-url" "\t" location
-
-where C<location-url> is the literal field name, followed by a tab, and
-I<location> is the file or url to the repository.
-
-Line endings may be either LF or CRLF depending on the current platform.
-
-
-=head2 check [I<option>]... [files|depends|executes|runfiles|all]
-
-Executes one (or all) check(s) on the consistency of the installation.
-
-=over 4
-
-=item B<files>
-
-Checks that all files listed in the local TLPDB (C<texlive.tlpdb>) are
-actually present, and lists those missing.
-
-=item B<depends>
-
-Lists those packages which occur as dependencies in an installed collections,
-but are themselves not installed, and those packages that are not
-contained in any collection.
-
-If you call C<tlmgr check collections> this test will be carried out
-instead since former versions for C<tlmgr> called it that way.
-
-=item B<executes>
-
-Check that the files referred to by C<execute> directives in the TeX
-Live Database are present.
-
-=item B<runfiles>
-
-List those filenames that are occurring more than one time in the runfiles.
 
-=back
+=head2 update [I<option>]... [I<pkg>]...
 
-Options:
+Updates the packages given as arguments to the latest version available
+at the installation source.  Either C<--all> or at least one I<pkg> name
+must be specified.  Options:
 
 =over 4
 
-=item B<--use-svn>
-
-Use the output of C<svn status> instead of listing the files; for
-checking the TL development repository.
-
-=back
-
-
-=head2 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 L<option> description above).  Does not change any
-initialization files, either system or personal.
-
-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 C<--w32mode> is not given,
-the setting I<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 C<--w32mode> is given, this
-option determines the path to be adjusted.
-
-If the user does not have admin rights, and the option C<--w32mode>
-is not given, and the setting I<w32_multi_user> is off, the user path
-is changed, while if the setting I<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 C<--w32mode>
-is given, it must be B<user> and the user path will be adjusted. If a
-user without admin rights uses the option C<--w32mode admin> a warning
-is issued that the caller does not have enough privileges.
+=item B<--all>
 
+Update all installed packages except for C<tlmgr> itself.  Thus, if
+updates to C<tlmgr> itself are present, this will simply give an error,
+unless also the option C<--force> or C<--self> is given.  (See below.)
 
-=cut
+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.
 
-# keep the following on *ONE* line otherwise Losedows perldoc does
-# not show it!!!!
+This means that if a package has been removed on the server (and thus
+has also been removed from the respective collection), C<tlmgr> will
+remove the package in the local installation.  This is called
+``auto-remove'' and is announced as such when using the option
+C<--list>.  This auto-removal can be suppressed using the option
+C<--no-auto-remove>.
 
-=pod
+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 C<--list>.  This auto-installation can be
+suppressed using the option C<--no-auto-install>.
 
-=head2 postaction [--w32mode=user|admin] [--fileassocmode=1|2] [--all] [install|remove] [shortcut|fileassoc|script] [I<pkg>]...
+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 C<tlmgr remove --force>
+on them.  (See the C<remove> action documentation.)  To reinstall any
+such forcibly removed packages use C<--reinstall-forcibly-removed>.
 
-Carry out the postaction C<shortcut>, C<fileassoc>, or C<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 C<--all> is given.
+If you want to exclude some packages from the current update run (e.g.,
+due to a slow link), see the C<--exclude> option below.
 
-If the option C<--w32mode> is given the value C<user>, all actions will
-only be carried out in the user-accessible parts of the
-registry/filesystem, while the value C<admin> selects the system-wide
-parts of the registry for the file associations.  If you do not have
-enough permissions, using C<--w32mode=admin> will not succeed.
+=item B<--self>
 
-C<--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
-C<option fileassocs>.)
+Update C<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 C<--all> or a list of
+packages, then C<tlmgr> will be updated first and, if this update
+succeeds, the new version will be restarted to complete the rest of the
+updates.
 
-=head2 uninstall
+In short:
 
-Uninstalls the entire TeX Live installation.  Options:
+  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!
 
-=over 4
+=item B<--dry-run>
 
-=item B<--force>
+Nothing is actually installed; instead, the actions to be performed are
+written to the terminal.  This is a more detailed report than C<--list>.
 
-Do not ask for confirmation, remove immediately.
+=item B<--list> [I<pkg>]
 
-=back
+Concisely list the packages which would be updated, newly installed, or
+removed, without actually changing anything. 
+If C<--all> is also given, all available updates are listed.
+If C<--self> is given, but not C<--all>, only updates to the
+critical packages (tlmgr, texlive infrastructure, perl on Windows, etc.)
+are listed.
+If neither C<--all> nor C<--self> is given, and in addition no I<pkg> is
+given, then C<--all> is assumed (thus, C<tlmgr update --list> is the
+same as C<tlmgr update --list --all>).
+If neither C<--all> nor C<--self> is given, but specific package names are
+given, those packages are checked for updates.
 
+=item B<--exclude> I<pkg>
 
-=head2 generate [I<option>]... I<what>
+Exclude I<pkg> from the update process.  If this option is given more
+than once, its arguments accumulate.
 
-=over 4
+An argument I<pkg> excludes both the package I<pkg> itself and all
+its related platform-specific packages I<pkg.ARCH>.  For example,
 
-=item B<generate language>
+  tlmgr update --all --exclude a2ping
 
-=item B<generate language.dat>
+will not update C<a2ping>, C<a2ping.i386-linux>, or
+any other C<a2ping.>I<ARCH> package.
 
-=item B<generate language.def>
+If this option specifies a package that would otherwise be a candidate
+for auto-installation, auto-removal, or reinstallation of a forcibly
+removed package, C<tlmgr> quits with an error message.  Excludes are not
+supported in these circumstances.
 
-=item B<generate language.dat.lua>
+=item B<--no-auto-remove> [I<pkg>]...
 
-=item B<generate fmtutil>
+Under normal circumstances C<tlmgr> tries to remove packages which have
+disappeared on the server, as described above under C<--all>.  This
+option prevents any such removals, either for all packages (with
+C<--all>), or the given I<pkg> names.
 
-=back
+=item B<--no-auto-install> [I<pkg>]...
 
-The C<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 C<tlmgr> routinely call C<generate> for
-all of these files.
+Under normal circumstances C<tlmgr> will install packages which are new
+on the server, as described above under C<--all>.  This option prevents
+any such automatic installation, either for all packages (with
+C<--all>), or the given I<pkg> names.
 
-For managing your own fonts, please read the C<updmap --help>
-information and/or L<http://tug.org/fonts/fontinstall.html>.
+Furthermore, after the C<tlmgr> run using this has finished, the
+packages that would have been auto-installed I<will be considered as
+forcibly removed>.  So, if C<foobar> is the only new package on the
+server, then
 
-In more detail: C<generate> remakes any of the configuration files
-C<language.dat>, C<language.def>, C<language.dat.lua>, and
-C<fmtutil.cnf>, from the information present in the local TLPDB, plus
-locally-maintained files.
+  tlmgr update --all --no-auto-install
 
-The locally-maintained files are C<language-local.dat>,
-C<language-local.def>, C<language-local.dat.lua>, or
-C<fmtutil-local.cnf>, searched for in C<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.
+is equivalent to
 
-(Historical note: The formerly supported C<updmap-local.cfg> is no longer
-read, since C<updmap> now supports multiple C<updmap.cfg> files.  Thus,
-local additions can and should be put into an C<updmap.cfg> file in
-C<TEXMFLOCAL>.  The C<generate updmap> action no longer exists.)
+  tlmgr update --all
+  tlmgr remove --force foobar
 
-Local files specify entries to be disabled with a comment line, namely
-one of these:
+=item B<--reinstall-forcibly-removed>
 
-  #!NAME
-  %!NAME
-  --!NAME
+Under normal circumstances C<tlmgr> will not install packages that have
+been forcibly removed by the user; that is, removed with C<remove
+--force>, or whose installation was prohibited by C<--no-auto-install>
+during an earlier update.
 
-where C<fmtutil.cnf> uses C<#>, C<language.dat> and C<language.def> use
-C<%>, and C<language.dat.lua> use C<-->.  In all cases, the I<name> is
-the respective format name or hyphenation pattern identifier.
-Examples:
+This option makes C<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:
 
-  #!pdflatex
-  %!german
-  --!usenglishmax
+  tlmgr update --reinstall-forcibly-removed --all
 
-(Of course, you're not likely to actually want to disable those
-particular items.  They're just examples.)
+=item B<--backup> and B<--backupdir> I<directory>
 
-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.
+These two options control the creation of backups of packages I<before>
+updating; that is, backup of packages as currently installed.  If
+neither of these options are given, no backup package will be saved. If
+C<--backupdir> is given and specifies a writable directory then a backup
+will be made in that location. If only C<--backup> is given, then a
+backup will be made to the directory previously set via the C<option>
+action (see below). If both are given then a backup will be made to the
+specified I<directory>.
 
-The form C<generate language> recreates all three files C<language.dat>,
-C<language.def>, and C<language.dat.lua>, while the forms with an
-extension recreates only that given language file.
+You can set options via the C<option> action to automatically create
+backups for all packages, and/or keep only a certain number of
+backups.  Please see the C<option> action for details.
 
-Options:
+C<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 C<--backup> option is to allow you to save a persistent backup
+in case the actual I<content> of the update causes problems, e.g.,
+introduces an incompatibility.
 
-=over 4
+The C<restore> action explains how to restore from a backup.
 
-=item B<--dest> I<output_file>
+=item B<--no-depends>
 
-specifies the output file (defaults to the respective location in
-C<TEXMFSYSVAR>).  If C<--dest> is given to C<generate language>, it
-serves as a basename onto which C<.dat> will be appended for the name of
-the C<language.dat> output file, C<.def> will be appended to the value
-for the name of the C<language.def> output file, and C<.dat.lua> to the
-name of the C<language.dat.lua> file.  (This is just to avoid
-overwriting; if you want a specific name for each output file, we
-recommend invoking C<tlmgr> twice.)
+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 B<--localcfg> I<local_conf_file>
+=item B<--no-depends-at-all>
 
-specifies the (optional) local additions (defaults to the respective
-location in C<TEXMFLOCAL>).
+See above under B<install> (and beware).
 
-=item B<--rebuild-sys>
+=item B<--force>
 
-tells tlmgr to run necessary programs after config files have been
-regenerated. These are:
-C<fmtutil-sys --all> after C<generate fmtutil>,
-C<fmtutil-sys --byhyphen .../language.dat> after C<generate language.dat>,
-and
-C<fmtutil-sys --byhyphen .../language.def> after C<generate language.def>.
+Force update of normal packages, without updating C<tlmgr> itself 
+(unless the C<--self> option is also given).  Not recommended.
 
-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.
+Also, C<update --list> is still performed regardless of this option.
 
 =back
 
-The respective locations are as follows:
-
-  tex/generic/config/language.dat (and language-local.dat);
-  tex/generic/config/language.def (and language-local.def);
-  tex/generic/config/language.dat.lua (and language-local.dat.lua);
-  web2c/fmtutil.cnf (and fmtutil-local.cnf);
+If the package on the server is older than the package already installed
+(e.g., if the selected mirror is out of date), C<tlmgr> does not
+downgrade.  Also, packages for uninstalled platforms are not installed.
 
 
 =head1 TLMGR CONFIGURATION FILE