- fix __MASTER__ in tlmgr recreate-tlpdb

- rename tlmgr update options:
	--no-remove   ->  --no-auto-remove
	--no-forcibly-removed -> --reinstall-forcibly-removed
- add documentation and explanations to tlmgr for these options and the
  different states of packages


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

1 files changed, 45 insertions, 22 deletions

diff --git a/Master/texmf/scripts/texlive/tlmgr.pl b/Master/texmf/scripts/texlive/tlmgr.pl
index 17ffb660f10..315cbbc3209 100755
--- a/Master/texmf/scripts/texlive/tlmgr.pl
+++ b/Master/texmf/scripts/texlive/tlmgr.pl
@@ -145,9 +145,9 @@ sub main {
                      "all" => 1,
                      "self" => 1,
                      "list" => 1,
-                     "no-remove" => 1,
+                     "no-auto-remove" => 1,
                      "no-auto-install" => 1,
-                     "no-forcibly-removed" => 1,
+                     "reinstall-forcibly-removed" => 1,
                      "force" => 1,
                      "backupdir" => "=s",
                      "backup" => 1,
@@ -1556,7 +1556,7 @@ sub action_update {
     next if $removals{$p};
     my $tlp = $localtlpdb->get_package($p);
     if (!defined($tlp)) {
-      if ($opts{"no-forcibly-removed"}) {
+      if ($opts{"reinstall-forcibly-removed"}) {
         $newpkgs{$p} = 1;
       } else {
         $forcermpkgs{$p} = 1;
@@ -1694,7 +1694,7 @@ sub action_update {
   # remove the packages that have disappeared:
   # we add that only to the list of total packages do be worked on
   # when --all is given, because we remove packages only on --all
-  if (!$opts{"no-remove"} && $opts{"all"}) {
+  if (!$opts{"no-auto-remove"} && $opts{"all"}) {
     my @foo = keys %removals;
     $totalnr += $#foo + 1;
   }
@@ -1722,8 +1722,8 @@ sub action_update {
   for (@addlines) { print; }
 
   for my $p (keys %removals) {
-    if ($opts{"no-remove"}) {
-      info("not removing $p due to -no-remove (removed on server)\n");
+    if ($opts{"no-auto-remove"}) {
+      info("not removing $p due to -no-auto-remove (removed on server)\n");
     } else {
       &ddebug("removing package $p\n");
       my $pkg = $localtlmedia->tlpdb->get_package($p);
@@ -1744,7 +1744,7 @@ sub action_update {
         $currnr++;
       } else {
         # new we are sure that:
-        # - $opts{"no-remove"} is *not* set
+        # - $opts{"no-auto-remove"} is *not* set
         # - $opts{"list"} is *not* set
         # we have to check in addition that
         # - $opts{"dry-run"} is not set
@@ -2626,6 +2626,10 @@ sub action_recreate_tlpdb {
   $tlpdb->add_tlpobj($inst);
   # reset the options to default values
   $tlpdb->add_default_options();
+  # check for location == _MASTER_
+  if ($tlpdb->option("location") eq "__MASTER__") {
+    $tlpdb->option("location", $TeXLive::TLConfig::TeXLiveURL);
+  }
   # add the other stuff in $Master/tlpkg/tlpobj/*.tlpobj
   # we can ignore *.{source,doc}.tlpobj because they are already
   # included in the *.tlpobj parent one at install time
@@ -3560,8 +3564,11 @@ tlmgr itself, disaster recovery when it's broken, and test versions.
 
 =head1 OPTIONS
 
-The following options to C<tlmgr> have to be given I<before> you specify
-the main action to perform.  In all cases, C<-->I<option> and
+The following options to C<tlmgr> are global options not specific to
+any action. Although we present C<tlmgr> invocation in the above order,
+all options can be given at any place and in arbitrary order. The first
+non-option argument will be the main action.
+In all cases, C<-->I<option> and
 C<->I<option> are equivalent, and an C<=> is optional between an option
 name and its value.
 
@@ -3617,7 +3624,8 @@ C<--help/-h/-?>, C<--version>, C<-q> (no informational messages), C<-v>
 the TeXLive::TLUtils documentation.
 
 The C<--version> option shows version information about the TeX Live
-release as well as the C<tlmgr> script itself.
+release as well as the C<tlmgr> script itself. If paired with C<-v>,
+revision number for the used TeX Live Perl modules are shown, too.
 
 =head1 ACTIONS
 
@@ -3689,16 +3697,26 @@ must be specified.  Options:
 
 =item B<--all>
 
-Update all installed packages except for tlmgr itself. For packages 
-contained in an installed collection, also install new packages and 
-remove deleted packages in those collections. Packages not contained 
-in an installed collection are not considered for addition or removal. 
+Update all installed packages except for tlmgr itself.
+
+Besides updating the installed packages. During the update of a
+collection the containing packages are syncronized to the status
+of the new version of the collection. That means that if a package
+has been removed on the server (and thus has also been removed from 
+the respective collection), tlmgr will remove the package also on
+the local installation. This is called B<auto-remove> and is announced
+as such when using the option B<--list>. The auto-removal can be 
+suppressed using the option B<--no-auto-remove>.
 
-More precisely, if both the server and the local installation have a
-collection C, and C on the server contains a package A that is not
-present locally, A will be added.  Conversely, if the local collection C
-contains a package B, but B is no longer in the server's C, then B will
-be deleted.
+On the other hand, if a package has been added to a collection, it
+will be added to the local installation. This is called B<auto-install>
+and is announced as such when using the option B<--list>. The 
+auto-installation can be suppressed using the option B<--no-auto-install>.
+
+An exception to the auto-installation of packages are those that have been
+forcibly removed (see the action B<remove> for details). To include, or
+better reinstall, those forcibly removed package use 
+B<--reinstall-forcibly-removed>.
 
 In case that updates to tlmgr itself are present this will not work
 unless also the option B<--force> or B<--self> is given.
@@ -3729,7 +3747,7 @@ Force update of packages even if updates to tlmgr itself are present.
 Updates to tlmgr are not performed unless B<--self> option is also given.
 (C<--list> is still performed regardless of this option.)
 
-=item B<--no-remove>
+=item B<--no-auto-remove>
 
 Under normal circumstances tlmgr tries to remove packages which have
 disappeared on the server when called with C<--all>, as described
@@ -3743,7 +3761,7 @@ automatic installation. Note that after this the packages that
 would have been auto-installed will be considered as
 forcibly removed.
 
-=item B<--no-forcibly-removed>
+=item B<--reinstall-forcibly-removed>
 
 Under normal circumstances tlmgr will not install packages that
 it considers forcibly removed as described above. This option makes
@@ -3751,7 +3769,7 @@ tlmgr consider all these packages as new and re-install them. This
 can be used to syncronize an installation with the server's 
 idea of what is available by calling
 
-  tlmgr update --no-forcibly-removed --all
+  tlmgr update --reinstall-forcibly-removed --all
 
 =item B<--backup> and B<--backupdir> I<directory>
 
@@ -3891,6 +3909,11 @@ 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 B<--force> switch because
+it is still listed in an installed collection or scheme will not be
+update and 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