doc changes for user mode, etc.

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

1 files changed, 117 insertions, 119 deletions

diff --git a/Master/texmf-dist/scripts/texlive/tlmgr.pl b/Master/texmf-dist/scripts/texlive/tlmgr.pl
index 05017552c36..36937fd12fd 100755
--- a/Master/texmf-dist/scripts/texlive/tlmgr.pl
+++ b/Master/texmf-dist/scripts/texlive/tlmgr.pl
@@ -126,16 +126,16 @@ sub main {
     "gui" => 1,
     "gui-lang" => "=s",
     "debug-translation" => 1,
-    "location|repository|repo" => "=s",
+    "repository|repo|location" => "=s",
     "machine-readable" => 1,
+    "no-execute-actions" => 1,
     "package-logfile" => "=s",
     "persistent-downloads" => "!",
-    "no-execute-actions" => 1,
-    "pin-file" => "=s",
     "pause" => 1,
-    "usermode" => 1,
-    "usertree" => "=s",
+    "pin-file" => "=s",
     "print-platform|print-arch" => 1,
+    "usermode|user-mode" => 1,
+    "usertree|user-tree" => "=s",
     "version" => 1,
     "help" => 1,
     "h|?" => 1);
@@ -481,7 +481,7 @@ sub give_version {
   #
   # add the list of revisions
   if ($::opt_verbosity > 0) {
-    $::version_string .= "Revision of modules:";
+    $::version_string .= "Revisions of TeXLive:: modules:";
     $::version_string .= "\nTLConfig: " . TeXLive::TLConfig->module_revision();
     $::version_string .= "\nTLUtils:  " . TeXLive::TLUtils->module_revision();
     $::version_string .= "\nTLPOBJ:   " . TeXLive::TLPOBJ->module_revision();
@@ -613,7 +613,7 @@ sub execute_action {
 
   # close the special log file
   if ($packagelogfile && !$::gui_mode) {
-    info("tlmgr: package log updated at $packagelogfile\n") if $packagelogged;
+    info("$prg: package log updated: $packagelogfile\n") if $packagelogged;
     close(PACKAGELOG);
   }
 
@@ -5933,7 +5933,7 @@ C<install-tl> has more details about this
 
 C<--repository> changes the repository location only for the current
 run; to make a permanent change, use C<option repository> (see the
-L<option> action).
+L</option> action).
 
 For backward compatibility and convenience, C<--location> and C<--repo>
 are accepted as aliases for this option.
@@ -5941,14 +5941,14 @@ are accepted as aliases for this option.
 
 =item B<--gui> [I<action>]
 
-C<tlmgr> has a graphical interface as well as the command-line
+C<tlmgr> has a graphical interface as well as the command line
 interface.  You can give this option, C<--gui>, together with an action
 to be brought directly into the respective screen of the GUI.  For
 example, running
 
   tlmgr --gui update
 
-starts you directly at the update screen.  Without any action, the
+starts you directly at the update screen.  If no action is given, the
 GUI will be started at the main screen.
 
 =for comment Keep language list in sync with install-tl.
@@ -5965,12 +5965,24 @@ 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).
 
+=item B<--debug-translation>
+
+In GUI mode, this switch tells C<tlmgr> to report any untranslated (or
+missing) messages to standard error.  This can help translators to see
+what remains to be done.
+
 =item B<--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 OUTPUT"> section below.
 
+=item B<--no-execute-actions>
+
+Suppress the execution of the execute actions as defined in the tlpsrc
+files.  Documented only for completeness, as this is only useful in
+debugging.
+
 =item B<--package-logfile> I<file>
 
 C<tlmgr> logs all package actions (install, remove, update, failed
@@ -5988,45 +6000,39 @@ Windows to avoid disappearing command windows.
 =item B<--no-persistent-downloads>
 
 For network-based installations, this option (on by default) makes
-C<tlmgr> try to set up a persistent connection (using the L<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.
+C<tlmgr> try to set up a persistent connection (using the C<LWP> Perl
+module).  The idea is to open and reuse only one connection per session
+between your computer and the server, instead of initiating a new
+download for each package.
 
 If this is not possible, C<tlmgr> will fall back to using C<wget>.  To
 disable these persistent connections, use C<--no-persistent-downloads>.
 
-=item B<--no-execute-actions>
+=item B<--pin-file>
 
-Suppress the execution of the execute actions as defined in the tlpsrc
-files.  Documented only for completeness, as this is only useful in
-debugging.
-
-=item B<--debug-translation>
-
-In GUI mode, this switch makes C<tlmgr> report any missing, or more
-likely untranslated, messages to standard error.  This can help
-translators to see what remains to be done.
+Change the pinning file location from C<TEXMFLOCAL/tlpkg/pinning.txt>
+(see L</Pinning> below).  Documented only for completeness, as this is
+only useful in debugging.
 
 =item B<--usermode>
 
-Activates the user mode, see L<USER MODE> below.
+Activates user mode for this run of C<tlmgr>; see L<USER MODE> below.
 
 =item B<--usertree> I<dir>
 
-Uses I<dir> as user tree in user mode, seel L<USER MODE> below.
-
+Uses I<dir> for the tree in user mode; see L<USER MODE> below.
 
 =back
 
 The standard options for TeX Live programs are also accepted:
 C<--help/-h/-?>, C<--version>, C<-q> (no informational messages), C<-v>
 (debugging messages, can be repeated).  For the details about these, see
-the L<TeXLive::TLUtils> documentation.
+the C<TeXLive::TLUtils> documentation.
 
 The C<--version> option shows version information about the TeX Live
-release and about the C<tlmgr> script itself.  If C<-v> is given as
-well, revision number for the used TeX Live Perl modules are shown, too.
+release and about the C<tlmgr> script itself.  If C<-v> is also given,
+revision number for the loaded TeX Live Perl modules are shown, too.
+
 
 =head1 ACTIONS
 
@@ -6376,6 +6382,13 @@ L</"TAXONOMIES"> below for details.
 =back
 
 
+=head2 init-usertree
+
+Sets up a texmf tree for so-called user mode management, either the
+default user tree (C<TEXMFHOME>), or one specified on the command line
+with C<--usertree>.  See L<USER MODE> below.
+
+
 =head2 install [I<option>]... I<pkg>...
 
 Install each I<pkg> given on the command line. By default this installs
@@ -6564,7 +6577,7 @@ those extra settings at present.
 
 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
+(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
@@ -6590,7 +6603,7 @@ is issued that the caller does not have enough privileges.
 
 =head2 pinning 
 
-The C<pinning> action manages the pinning file, see L<Pinning> below.
+The C<pinning> action manages the pinning file, see L</Pinning> below.
 
 =over 4
 
@@ -7070,107 +7083,92 @@ downgrade.  Also, packages for uninstalled platforms are not installed.
 
 
   
-=head2 init-usertree
-
-sets up the default user tree (C<TEXMFHOME>) or the one specified
-on the command line using C<--usertree> for user mode management.
-See L<USER MODE> below.
-
-
 =head1 USER MODE
 
-B<WARNING> B<WARNING> B<WARNING> 
-This is very much work in progress
-and experimental. Expect breakage, and the need to reinstall your 
-user tree a new. 
+B<WARNING:> This is new work in TL 2013.  Expect breakage, and the need
+to reinstall your user tree.
 
-C<tlmgr> 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.
+C<tlmgr> provides a restricted way, called ``user mode'', to manage
+arbitrary texmf trees in the same way as the main installation.  For
+example, this allows people without write permissions on the
+installation location to update/install packages into a tree of their
+own.
 
-C<tlmgr> is set into user mode by giving the command line option 
-C<--usermode>. It will not switch automatically, nor does it support
-a config file by now. Thus, this option has to be given every time.
+C<tlmgr> is switched into user mode with the command line option
+C<--usermode>.  It does not switch automatically, nor is there any
+configuration file setting for it.  Thus, this option has to be
+explicitly given every time user mode is to be activated.
 
-This mode of C<tlmgr> works on a user tree, which by default will be
-the value of C<TEXMFHOME>, but can be overridden with the command line
-option C<--usertree>. In the following when we speak of the user tree
+This mode of C<tlmgr> works on a user tree, by default the value of the
+C<TEXMFHOME> variable.  This can be overridden with the command line
+option C<--usertree>.  In the following when we speak of the user tree
 we mean either C<TEXMFHOME> or the one given on the command line.
 
-Not all actions are allowed in user mode, C<tlmgr> will warn you and
-not carry out this action. The actions of C<tlmgr> 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 
-B<help>, B<version>, B<search>, B<show>, B<list>, B<check>, B<print-arch>.
-
-Most of the actions dealing with package management on the other hand
-need write permissions, and behave differently:
-B<install>, B<update>, B<remove>, B<option>, B<paper>, B<generate>,
-B<backup>, B<restore>, B<uninstall>, B<symlinks>.
+Not all actions are allowed in user mode; C<tlmgr> will warn you and not
+carry out any problematic actions.  Currently not supported (and
+probably will never be) is the C<platform> action.  The C<gui> action is
+currently not supported, but may be in a future release.
 
-Currently not supported (and probably will never be) is the B<arch>
-action.
+Some C<tlmgr> actions don't need any write permissions and thus work the
+same in user mode and normal mode.  Currently these are: C<check>,
+C<help>, C<list>, C<print-platform>, C<search>, C<show>, C<version>.
 
-As for the B<gui> 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: C<install>, C<update>, C<remove>, C<option>, C<paper>,
+C<generate>, C<backup>, C<restore>, C<uninstall>, C<symlinks>.
 
 Before using C<tlmgr> in user mode, you have to set up the user tree
-with the B<init-usertree> action. This will create C<USERTREE/web2c>,
-C<USERTREE/tlpkg/tlpobj> and set up a minimal C<USERTREE/tlpkg/texlive.tlpdb>.
-From then on you can use the supported actions as normal by adding
-the C<--usermode> command line switch.
-
-In user mode the file C<USERTREE/tlpkg/texlive.tlpdb> contains only the 
-packages that have been installed into the user tree C<USERTREE> using
-C<tlmgr>, plus additional options in the virtual package 
-00texlive.installation (like with the main installation's texlive.tlpdb).
+with the C<init-usertree> action.  This creates I<usertree>C</web2c> and
+I<usertree>C</tlpkg/tlpobj>, and a minimal
+I<usertree>C</tlpkg/texlive.tlpdb>.  At that point, you can tell
+C<tlmgr> to do the (supported) actions by adding the C<--usermode>
+command line option.
+
+In user mode the file I<usertree>C</tlpkg/texlive.tlpdb> contains only
+the packages that have been installed into the user tree using C<tlmgr>,
+plus additional options from the ``virtual'' package
+C<00texlive.installation> (similar to the main installation's
+C<texlive.tlpdb>).
 
 All actions on packages in user mode can only be carried out on packages
-that are marked as B<relocatable>. Basically that means that the contained
-files all reside in the C<texmd-dist> tree. B<NOTE> 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 C<relocatable>.  This excludes all packages containing
+executables and a few other core packages.  Of the 2500 or so packages
+currently in TeX Live the vast majority are relocatable and can be
+installed into a user tree.
 
 Description of changes of actions in user mode:
 
-=head2 install
+=head3 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 (TEXMFHOME 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).
+In user mode, the C<install> action checks that the package and all
+dependencies are all either relocated or already installed in the system
+installation.  If this is the case, it unpacks all containers to be
+installed into the user tree (to repeat, that's either C<TEXMFHOME> or
+the value of C<--usertree>) and add the respective packages to the user
+tree's C<texlive.tlpdb> (creating it if need be).
 
-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.
+Currently installing a collection in user mode installs all dependent
+packages, but in contrast to normal mode, does I<not> install dependent
+collections.  For example, in normal mode C<tlmgr install
+collection-context> would install C<collection-basic> and other
+collections, while in user mode, I<only> the packages mentioned in
+C<collection-context> are installed.
 
 =head2 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.
+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.
  
-=head2 option
-
-only acts upon the user's texlive.tlpdb
-
-=head2 paper
-
-changes configuration files in user tree
-
-=head2 generate
+=head2 generate, option, paper
 
+In user mode, these actions operate only on the user tree's
+configuration files and/or C<texlive.tlpdb>.
 creates configuration files in user tree
 
-B<WARNING WARNING WARNING> Be again warned that this is very experimental!
-
+B<WARNING> repeated: this is still has to be considered experimental!
+Please report bugs to C<tex-live@tug.org> as usual
 
 
 =head1 TLMGR CONFIGURATION FILE
@@ -7210,21 +7208,21 @@ options:
 
 =over 4
 
-=item B<--keyword>
+=item C<--keyword>
 
 The keywords, as specified at L<http://az.ctan.org/keyword>.
 
-=item B<--functionality>
+=item C<--functionality>
 
 The ``by-topic'' categorization created by J\"urgen Fenn, as specified
 at L<http://az.ctan.org/characterization/by-function>.
 
-=item B<--characterization>
+=item C<--characterization>
 
 Both the primary and secondary functionalities, as specified at
 L<http://az.ctan.org/characterization/choose_dimen>.
 
-=item B<--taxonomy>
+=item C<--taxonomy>
 
 Operate on all the taxonomies.
 
@@ -7489,14 +7487,14 @@ The following entries can be found in the menu bar:
 
 =over 4
 
-=item B<tlmgr> menu
+=item C<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 C<quit> operation.
 
-=item B<Options menu>
+=item C<Options menu>
 
 Provides access to several groups of options: C<Paper> (configuration of
 default paper sizes), C<Platforms> (only on Unix, configuration of the
@@ -7515,7 +7513,7 @@ automatic removal of packages deleted from the server.  Playing with the
 choices of what is or isn't installed may lead to an inconsistent TeX Live
 installation; e.g., when a package is renamed.
 
-=item B<Actions menu>
+=item C<Actions menu>
 
 Provides access to several actions: update the filename database (aka
 C<ls-R>, C<mktexlsr>, C<texhash>), rebuild all formats (C<fmtutil-sys
@@ -7526,7 +7524,7 @@ Windows).
 The final action is to remove the entire TeX Live installation (also not
 on Windows).
 
-=item B<Help menu>
+=item C<Help menu>
 
 Provides access to the TeX Live manual (also on the web at
 L<http://tug.org/texlive/doc.html>) and the usual ``About'' box.
@@ -7545,10 +7543,10 @@ information it needs by reading stdout.
 Currently this option only applies to the 
 L<update|/"update [I<option>]... [I<pkg>]...">, the
 L<install|"install [I<option>]... I<pkg>...">, and the
-L<option|"option"> actions.  
+L</option> actions.  
 
 
-=head2 update and install actions
+=head3 update, install
 
 The output format is as follows:
 
@@ -7670,7 +7668,7 @@ The estimated total time.
 
 =back
 
-=head2 option action
+=head3 option
 
 The output format is as follows: