pinning doc, msgs

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

1 files changed, 67 insertions, 53 deletions

diff --git a/Master/texmf/scripts/texlive/tlmgr.pl b/Master/texmf/scripts/texlive/tlmgr.pl
index 5480276ed5a..79c49b102f5 100755
--- a/Master/texmf/scripts/texlive/tlmgr.pl
+++ b/Master/texmf/scripts/texlive/tlmgr.pl
@@ -879,7 +879,8 @@ sub action_remove {
   #   user that it is still needed
   #
   # remove all .ARCH dependencies, too, unless $opts{"no-depends-at-all"}
-  @packs = $localtlpdb->expand_dependencies("-only-arch", $localtlpdb, @packs) unless $opts{"no-depends-at-all"};
+  @packs = $localtlpdb->expand_dependencies("-only-arch", $localtlpdb, @packs)
+    unless $opts{"no-depends-at-all"}; 
   # remove deps unless $opts{"no-depends"}
   @packs = $localtlpdb->expand_dependencies("-no-collections", $localtlpdb, @packs) unless $opts{"no-depends"};
   my %allpacks;
@@ -920,7 +921,7 @@ sub action_remove {
       # into %already_removed.
       if ($tlp->category eq "Collection") {
         my $foo = 0;
-        info ("remove $pkg\n");
+        info ("$prg: removing $pkg\n");
         if (!$opts{"dry-run"}) {
           $foo = $localtlpdb->remove_package($pkg);
           logpackage("remove: $pkg");
@@ -935,13 +936,13 @@ sub action_remove {
         # be removed at the second state. Note that if a package has
         # already been removed due to a removal of a collection
         # it will be marked as such in %already_removed and not tried again
-        push @more_removal, $pkg;
+        push (@more_removal, $pkg);
       }
     }
   }
   foreach my $pkg (sort @more_removal) {
     if (!defined($already_removed{$pkg})) {
-      info ("remove $pkg\n");
+      info ("$prg: removing package $pkg\n");
       if (!$opts{"dry-run"}) {
         if ($localtlpdb->remove_package($pkg)) {
           # removal was successful
@@ -958,7 +959,7 @@ sub action_remove {
     $localtlpdb->save;
     my @foo = sort keys %already_removed;
     if (@foo) {
-      info("tlmgr: actually removed these packages: @foo\n");
+      info("tlmgr: ultimately removed these packages: @foo\n");
     } else {
       info("tlmgr: no packages removed.\n");
     }
@@ -3508,8 +3509,8 @@ sub show_list_of_packages {
 # easier for people to use
 # tlmgr pinning show
 # tlmgr pinning check
-# tlmgr pinning add <repo> <pkgglob> [<pkgglob>, ...]
-# tlmgr pinning remove <repo> <pkgglob> [<pkgglob>, ...]
+# tlmgr pinning add <repo> <pkgglob> [<pkgglob> ...]
+# tlmgr pinning remove <repo> <pkgglob> [<pkgglob> ...]
 # tlmgr pinning remove <repo> --all
 sub action_pinning {
   my $what = shift @ARGV;
@@ -3517,29 +3518,33 @@ sub action_pinning {
   init_local_db();
   init_tlmedia_or_die();
   if (!$remotetlpdb->is_virtual) {
-    tlwarn("tlmgr: not a virtual database, no pinning actions supported!\n");
+    tlwarn("$prg: only one repository configured, "
+           . "pinning actions not supported.\n");
     return;
   }
   my $pinref = $remotetlpdb->virtual_pindata();
   my $pf = $remotetlpdb->virtual_pinning();
+
   if ($what =~ m/^show$/i) {
     my @pins = @$pinref;
     if (!@pins) {
-      tlwarn("No pinning data present by now.\n");
+      tlwarn("$prg: no pinning data present.\n");
       return 0;
     }
-    print "Defined pinning data:\n";
+    info("$prg: this pinning data is defined:\n");
     for my $p (@pins) {
-      print "  ", $p->{'repo'}, ":", $p->{'glob'}, "\n";
+      info("  ", $p->{'repo'}, ":", $p->{'glob'}, "\n");
     }
     return 1;
+
   } elsif ($what =~ m/^check$/i) {
-    tlwarn("Not implemented yet, sorry!\n");
+    tlwarn("$prg: not implemented yet, sorry!\n");
     return 0;
+
   } elsif ($what =~ m/^add$/i) {
     # we need at least two more arguments
-    if ($#ARGV < 1) {
-      tlwarn("missing arguments to pinning add\n");
+    if (@ARGV < 2) {
+      tlwarn("$prg: need at least two arguments to pinning add\n");
       return;
     }
     my $repo = shift @ARGV;
@@ -3548,37 +3553,40 @@ sub action_pinning {
     $pf->value($repo, @ov);
     $remotetlpdb->virtual_update_pins();
     $pf->save;
-    info("Added/Updated pinning data for $repo\n");
+    info("$prg: new pinning data for $repo: @ARGV\n");
     return 1;
+
   } elsif ($what =~ m/^remove$/i) {
     my $repo = shift @ARGV;
     if (!defined($repo)) {
-      tlwarn("missing arguments to pinning add\n");
+      tlwarn("$prg: missing repository argument to pinning remove\n");
       return 0;
     }
     if ($opts{'all'}) {
-      if ($#ARGV >= 0) {
-        tlwarn("no additional argument allowed when --all is given\n");
-        return;
+      if (@ARGV) {
+        tlwarn("$prg: additional argument(s) not allowed with --all: @ARGV\n");
+        return 0;
       }
       $pf->delete_key($repo);
       $remotetlpdb->virtual_update_pins();
       $pf->save;
+      info("$prg: all pinning data removed for repository $repo\n");
       return 1;
     }
     # complicated case, we want to remove only one setting
     my @ov = $pf->value($repo);
     my @nv;
     for my $pf (@ov) {
-      push @nv, $pf if (!member($pf, @ARGV));
+      push (@nv, $pf) if (!member($pf, @ARGV));
     }
     $pf->value($repo, @nv);
     $remotetlpdb->virtual_update_pins();
     $pf->save;
-    info("Removed pinning data for $repo\n");
+    info("$prg: removed pinning data for repository $repo: @ARGV\n");
     return 1;
+
   } else {
-    tlwarn("Unknown argument to pinning action: $what\n");
+    tlwarn("$prg: unknown argument for pinning action: $what\n");
     return 0;
   }
   # $pin{'repo'} = $repo;
@@ -3784,7 +3792,7 @@ sub action_repository {
     return;
   }
   # we are still here, unknown command to repository
-  tlwarn("$prg: unknown directive to tlmgr repository: $what\n");
+  tlwarn("$prg: unknown subaction for tlmgr repository: $what\n");
   return;
 }
 
@@ -5204,7 +5212,7 @@ sub init_local_db {
 sub init_tlmedia_or_die {
   my ($ret, $err) = init_tlmedia();
   if (!$ret) {
-    tldie("$prg: $err");
+    tldie("$prg: $err\n");
   }
 }
 
@@ -6487,7 +6495,7 @@ Shows the current pinning data.
 Pins the packages matching the I<pkgglob>(s) to the repository
 I<repo>.
 
-=item C<pinning remove I<repo> I<pgkglob>...
+=item C<pinning remove I<repo> I<pkgglob>...
 
 Any packages recorded in the pinning file matching the <pkgglob>s for
 the given repository I<repo> are removed.
@@ -7032,23 +7040,25 @@ or should not be included in TeX Live, for whatever reason.
 The simplest and most reliable method is to temporarily set the
 installation source to any repository (with the C<-repository> or
 C<option repository> command line options), and perform your operations.
+
 When you are using multiple repositories over a sustained time, however,
-this is inconvenient.  Thus, it's possible to tell C<tlmgr> about
-additional repositories you want to use.  The basic command is C<tlmgr
-repository add>.  The rest of this section explains further.
+explicitly switching between them becomes inconvenient.  Thus, it's
+possible to tell C<tlmgr> about additional repositories you want to use.
+The basic command is C<tlmgr repository add>.  The rest of this section
+explains further.
 
 When using multiple repositories, one of them has to be set as the main
-repository, which distributes most of the installed packages.  If you
+repository, which distributes most of the installed packages.  When you
 switch from a single repository installation to a multiple repository
-installation, the previously set repository will be set as the main
+installation, the previous sole repository will be set as the main
 repository.
 
 By default, even if multiple repositories are configured, packages are
-still I<only> installed from the main repository.  Thus, simply adding a
-second repository does not actually enable installation of anything from
-there.  You also have to specify which packages should be taken from a
-different repository by specifying so-called ``pinning'' rules,
-described next.
+I<still> I<only> installed from the main repository.  Thus, simply
+adding a second repository does not actually enable installation of
+anything from there.  You also have to specify which packages should be
+taken from the new repository, by specifying so-called ``pinning''
+rules, described next.
 
 =head2 Pinning
 
@@ -7056,12 +7066,9 @@ When a package C<foo> is pinned to a repository, a package C<foo> in any
 other repository, even if it has a higher revision number, will not be
 considered an installable candidate.
 
-By default, everything is pinned to the main repository, 
-as if the last line of C<pinning.txt> was
-
-  main:*
-
-=head2 Multiple repository example with tlcontrib
+As mentioned above, by default everything is pinned to the main
+repository.  Let's now go through an example of setting up a second
+repository and enabling updates of a package from it.
 
 First, check that we have support for multiple repositories, and have
 only one enabled (as is the case by default):
@@ -7070,8 +7077,9 @@ only one enabled (as is the case by default):
  List of repositories (with tags if set):
    /var/www/norbert/tlnet
 
-Let's add the C<tlcontrib> repository (L<http://tlcontrib.metatex.org>,
-maintained by Taco Hoekwater et al.), with the tag C<tlcontrib>:
+Ok.  Let's add the C<tlcontrib> repository (this is a real
+repository, hosted at L<http://tlcontrib.metatex.org>, maintained by
+Taco Hoekwater et al.), with the tag C<tlcontrib>:
 
  $ tlmgr repository add http://tlcontrib.metatex.org/2012 tlcontrib
 
@@ -7082,32 +7090,38 @@ Check the repository list again:
     http://tlcontrib.metatex.org/2012 (tlcontrib)
     /var/www/norbert/tlnet (main)
 
-Specify a pinning entry to get the package C<context> from C<tlcontrib>:
+Now we specify a pinning entry to get the package C<context> from
+C<tlcontrib>:
 
- $ tlocal=`kpsewhich -var-value TEXMFLOCAL`
- $ echo "tlcontrib:context" > $tlocal/tlpkg/pinning.txt
+ $ tlmgr pinning add tlcontrib context
 
 Check that we can find C<context>:
 
- $ tlmgr show microtype
- tlmgr: using pinning file .../tlpkg/pinning.txt
+ $ tlmgr show context
  tlmgr: package repositories:
  ...
- package:     microtype
- category:    Package
+ package:     context
+ repository:  tlcontrib/26867
  ...
 
 - install C<context>:
 
  $ tlmgr install context
- tlmgr: using pinning file .../tlpkg/pinning.txt
  tlmgr: package repositories:
  ...
- [1/1,  ??:??/??:??] install: context @tlcontrib [39k]
+ [1/1,  ??:??/??:??] install: context @tlcontrib [
 
-In the output here you can see that the C<context> package is now
+In the output here you can see that the C<context> package has been
 installed from the C<tlcontrib> repository (C<@tlcontrib>).
 
+Finally, C<tlmgr pinning> also supports removing certain or all packages
+from a given repository:
+
+  $ tlmgr pinning remove tlcontrib context  # remove just context
+  $ tlmgr pinning remove tlcontrib --all    # take nothing from tlcontrib
+
+A summary of the C<tlmgr pinning> actions is given above.
+
 
 =head1 GUI FOR TLMGR