doc tweaks, and don't bother mentioning switching

to the net if it's a dry run.


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

1 files changed, 60 insertions, 56 deletions

diff --git a/Master/texmf/scripts/texlive/tlmgr.pl b/Master/texmf/scripts/texlive/tlmgr.pl
index 6b755646a3f..c39062f7b23 100755
--- a/Master/texmf/scripts/texlive/tlmgr.pl
+++ b/Master/texmf/scripts/texlive/tlmgr.pl
@@ -728,7 +728,7 @@ sub action_remove {
       my @needed = $localtlpdb->needed_by($p);
       if ($opts{"force"}) {
         info("tlmgr: $p is needed by " . join(" ", @needed) . "\n");
-        info("tlmgr: still removing it due to --force\n");
+        info("tlmgr: removing it anyway, due to --force\n");
       } else {
         delete($packs{$p});
         tlwarn("tlmgr: not removing $p, needed by " .
@@ -911,7 +911,7 @@ sub action_show {
         for my $d (sort @todo) {
           my $foo = $tlpdb->get_package($d);
           if (!$foo) {
-            warn "That should not happen, no such package here!";
+            tlwarn ("\nShould not happen, no dependent package $d");
             next;
           }
           if ($d ne $pkg) {
@@ -1049,7 +1049,7 @@ sub action_path {
     }
   } else {
     # that should not happen
-    tlwarn("that should not happen, action_path what=$what\n");
+    tlwarn("\nShould not happen, action_path what=$what");
     exit 1;
   }
   return;
@@ -1881,13 +1881,13 @@ sub action_update {
         # and has already been removed
         next;
       } else {
-        tlwarn("\ntlmgr: $pkg mentioned, neither new nor forcibly removed\n");
+        tlwarn("\ntlmgr: $pkg mentioned, but neither new nor forcibly removed\n");
         next;
       }
       # install new packages
       my $mediatlp = $tlmediatlpdb->get_package($pkg);
       if (!defined($mediatlp)) {
-        tlwarn("\nShould not happen: $pkg not found in $location\n");
+        tlwarn("\nShould not happen: $pkg not found in $location");
         next;
       }
       my $mediarev = $mediatlp->revision;
@@ -2026,7 +2026,7 @@ sub action_update {
       # install new packages
       my $mediatlp = $tlmediatlpdb->get_package($pkg);
       if (!defined($mediatlp)) {
-        tlwarn("\nShould not happen: $pkg not found in $location\n");
+        tlwarn("\nShould not happen: $pkg not found in $location");
         next;
       }
       my $mediarev = $mediatlp->revision;
@@ -2331,7 +2331,7 @@ sub action_update {
     info ("Restarting tlmgr to complete update ...\n");
     debug("restarting tlmgr @::SAVEDARGV\n");
     exec("tlmgr", @::SAVEDARGV);
-    die "Cannot restart tlmgr, please retry updating.";
+    die "cannot restart tlmgr, please retry update";
   }
 
   # for --dry-run we cannot restart tlmgr (no way to fake successful infra update)
@@ -2348,7 +2348,7 @@ sub action_update {
   
   if (!(@new || @updated)) {
     info("tlmgr: no updates available\n");
-    if ($tlmediasrc->media ne "NET") {
+    if ($tlmediasrc->media ne "NET" && !$opts{"dry-run"}) {
       # for all but net updates we warn if nothing is updated
       tlwarn("\nYour installation is set up to look on the disk for updates.\n");
       tlwarn("To install from the Internet for this one time only, run\n");
@@ -4001,7 +4001,7 @@ sub check_for_critical_updates
       # that should not happen, we expanded in the localtlpdb so why
       # should it not be present, any anyway, those are so fundamental
       # so they have to be there
-      tlwarn("Fundamental package $pkg not present, that is sooo bad.\n");
+      tlwarn("\nFundamental package $pkg not present, uh oh, goodbye");
       die "Serious error, $pkg not found";
     }
     my $localrev = $tlp->revision;
@@ -4245,34 +4245,35 @@ must be specified.  Options:
 
 =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.)
+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.)
 
 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.
 
-Specifically, 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 also on 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>.
+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>.
 
-Analogously, if a package has been added to an installed collection on
-the server, 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>.
+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>.
 
 An exception to the collection dependency checks (including the
 auto-installation of packages just mentioned) are those that have been
-forcibly removed by you (see the B<remove> action, C<--force> option).
-To reinstall any such forcibly removed packages use
-C<--reinstall-forcibly-removed>.
+``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>.
 
-If you want to exclude some packages from being updated (e.g., due to a slow
-link), see the C<--exclude> option below.
+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.
 
 =item B<--self>
 
@@ -4290,13 +4291,19 @@ In short:
   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!
+
+=item B<--dry-run>
+
+Nothing is actually installed; instead, the actions to be performed are
+written to the terminal.  This is a more detailed report than C<--list>.
 
 =item B<--list> [I<pkg>]
 
 Concisely list the packages which would be updated, newly installed, or
-removed, without actually changing anything. If no package is given
-acts like C<--list --all>, otherwise lists only updates to the packages
-given as arguments (and its dependencies).
+removed, without actually changing anything.  If no package is given,
+this acts like C<--list --all>, otherwise it lists only updates to the
+packages given as arguments (and its dependencies).
 
 =item B<--exclude> I<pkg>
 
@@ -4309,38 +4316,30 @@ its related architecture-specific packages I<pkg.ARCH>.  For example,
   tlmgr update --all --exclude a2ping
 
 will not update C<a2ping>, C<a2ping.i386-linux>, or
-any other C<a2ping.>I<ARCH>package.
+any other C<a2ping.>I<ARCH> package.
 
 If this option specifies a package that would otherwise be a candidate
 for auto-installation, auto-removal, or reinstallation of a forcibly
 removed package, C<tlmgr> quits with an error message.  Excludes are not
 supported in these circumstances.
 
-=item B<--dry-run>
-
-Nothing is actually installed; instead, the actions to be performed are
-written to the terminal.  This is a more detailed report than C<--list>.
-
-=item B<--force>
-
-Force update of normal packages, without updating C<tlmgr> itself 
-(unless the C<--self> option is also given).  Not recommended.
-
-Also, C<update --list> is still performed regardless of this option.
-
-=item B<--no-auto-remove>
+=item B<--no-auto-remove> [I<pkg>]...
 
 Under normal circumstances C<tlmgr> tries to remove packages which have
-disappeared on the server when called with C<--all>, as described
-above. This prevents any such removals.
+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>
+=item B<--no-auto-install> [I<pkg>]...
 
-Under normal circumstances C<tlmgr> will install packages which are
-new on the server when called with C<--all>. This prevents any such
-automatic installation. Note that after this the packages that
-would have been auto-installed will be considered as
-forcibly removed. Actually, if `foobar' is the only new package on
+Under normal circumstances C<tlmgr> will install packages which are new
+on the server, as descrbed above under C<--all>.  This option prevents
+any such automatic installation, either for all packages (with
+C<--all>), or the given I<pkg> names.
+
+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
 
   tlmgr update --all --no-auto-install
@@ -4358,13 +4357,11 @@ been forcibly removed by the user; that is, removed with C<remove
 during an earlier update.
 
 This option makes C<tlmgr> ignore the forcible removals and re-install
-all such packages. This can be used to synchronize an installation with
-the server's idea of what is available by calling
+all such packages. This can be used to completely synchronize an
+installation with the server's idea of what is available:
 
   tlmgr update --reinstall-forcibly-removed --all
 
-This option only works in conjunction with C<--all>.
-
 =item B<--backup> and B<--backupdir> I<directory>
 
 These two options control the creation of backups of packages I<before>
@@ -4398,6 +4395,13 @@ suppresses this behavior.
 
 See above under B<install> (and beware).
 
+=item B<--force>
+
+Force update of normal packages, without updating C<tlmgr> itself 
+(unless the C<--self> option is also given).  Not recommended.
+
+Also, C<update --list> is still performed regardless of this option.
+
 =back
 
 If the package on the server is older than the package already installed