some taxonomy doc

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

1 files changed, 75 insertions, 34 deletions

diff --git a/Master/texmf/scripts/texlive/tlmgr.pl b/Master/texmf/scripts/texlive/tlmgr.pl
index a3a892f0f0b..652b82f9231 100755
--- a/Master/texmf/scripts/texlive/tlmgr.pl
+++ b/Master/texmf/scripts/texlive/tlmgr.pl
@@ -1169,8 +1169,9 @@ sub action_path {
   return;
 }
 
-#  SEARCH
-#
+
+# taxonomy subroutines
+# 
 sub load_taxonomy_datafile {
   init_local_db();
   my $taxonomy;
@@ -1209,6 +1210,8 @@ sub walk_level_tree {
   }
 }
 
+#  SEARCH
+#
 sub action_search {
   my $r = shift @ARGV;
   my $ret = "";
@@ -1246,25 +1249,26 @@ sub action_search {
       || $opts{"keyword"}) {
     $taxonomy = load_taxonomy_datafile();
     if (!defined($taxonomy)) {
-      tlwarn("tlmgr: Cannot load taxonomy file, searching/listing for taxonomies not supported.\n");
+      tlwarn("tlmgr: Cannot load taxonomy file;",
+             " searching/listing for taxonomies not supported.\n");
       return;
     }
     if ($opts{"list"}) {
       if ($opts{"keyword"} || $opts{"taxonomy"}) {
-        print "Keywords:\n";
+        print "\f Keywords:\n";
         for (sort keys %{$taxonomy->{'by-taxonomy'}{'keyword'}}) {
           print "\t$_\n";
         }
         print "\n";
       }
       if ($opts{"functionality"} || $opts{"taxonomy"}) {
-        print "Functionalities:\n";
+        print "\f Functionalities:\n";
         &walk_level_tree($taxonomy->{'by-taxonomy'}{'functionality'}, "", 0);
         print "\n";
       }
       if ($opts{"characterization"} || $opts{"taxonomy"}) {
         # Assume all possible characterizations occur under the primary ones!
-        print "Characterizations:\n";
+        print "\f Characterizations:\n";
         &walk_level_tree($taxonomy->{'by-taxonomy'}{'primary'}, "", 0);
         print "\n";
       }
@@ -1290,7 +1294,7 @@ sub action_search {
       # the other searching is done together
       my $t = "";
       if ($opts{"taxonomy"}) {
-        $t = "$t" . join('\n', @{$taxonomy->{'by-package'}{'keyword'}{$pkg}})
+        $t = $t . join('\n', @{$taxonomy->{'by-package'}{'keyword'}{$pkg}})
           if (defined($taxonomy->{'by-package'}{'keyword'}{$pkg}));
         $t .= "\n";
         $t = "$t$taxonomy->{'by-package'}{'primary'}{$pkg}\n"
@@ -1299,13 +1303,13 @@ sub action_search {
         $t = "$t$taxonomy->{'by-package'}{'secondary'}{$pkg}\n"
           if (defined($taxonomy->{'by-package'}{'secondary'}{$pkg}));
         $t .= "\n";
-        $t = "$t" . join('\n', @{$taxonomy->{'by-package'}{'functionality'}{$pkg}})
+        $t = $t.join('\n', @{$taxonomy->{'by-package'}{'functionality'}{$pkg}})
           if (defined($taxonomy->{'by-package'}{'functionality'}{$pkg}));
       } elsif ($opts{"keyword"}) {
-        $t = "$t" . join('\n', @{$taxonomy->{'by-package'}{'keyword'}{$pkg}})
+        $t = $t . join('\n', @{$taxonomy->{'by-package'}{'keyword'}{$pkg}})
           if (defined($taxonomy->{'by-package'}{'keyword'}{$pkg}));
       } elsif ($opts{"functionality"}) {
-        $t = "$t" . join('\n', @{$taxonomy->{'by-package'}{'functionality'}{$pkg}})
+        $t = $t.join('\n', @{$taxonomy->{'by-package'}{'functionality'}{$pkg}})
           if (defined($taxonomy->{'by-package'}{'functionality'}{$pkg}));
       } elsif ($opts{"characterization"}) {
         $t = "$t$taxonomy->{'by-package'}{'primary'}{$pkg}\n"
@@ -1326,18 +1330,17 @@ sub action_search {
         $pat = '\W' . $r . '\W';
       }
       if ($t =~ m/$pat/i) {
-        $ret .= " $pkg - " . $shortdesc . "\n";
+        $ret .= " $pkg - $shortdesc\n";
       }
     }
   }
-  print "$ret";
+  print $ret;
   return;
 }
 
 
 #  RESTORE
 #
-
 # read the directory and check what files/package/rev are available
 # for restore
 sub get_available_backups {
@@ -5569,8 +5572,8 @@ C<--print-arch> is a synonym.
 =head2 search [I<options>] --characterization I<what>
 
 By default, search the names, short descriptions, and long descriptions
-of all locally installed packages for the argument I<what>,
-interpreted as a regular expression.
+of all locally installed packages for the argument I<what>, interpreted
+as a regular expression.
 
 Options:
 
@@ -5583,16 +5586,16 @@ local installation.
 
 =item B<--word>
 
-Restrict the search to match only full words. As an example searching
-for C<table> with this option will not output packages containing
-the the word C<tables> unless they also contain the word C<table>.
+Restrict the search to match only full words. For example, searching for
+C<table> with this option will not output packages containing the
+word C<tables> (unless they also contain the word C<table> on its own).
 
 =item B<--list>
 
-If a search for any (or all) taxonomies is done, by specifying
-B<--taxonomy>, B<--keyword>, B<--functionality>, or
-B<--characterization>, then instead of searching for packages, list the
-entire corresponding taxonomy.  See L</"TAXONOMIES"> below.
+If a search for any (or all) taxonomies is done, by specifying one of
+the taxonomy options below, then instead of searching for packages, list
+the entire corresponding taxonomy (or all of them).  See
+L</"TAXONOMIES"> below.
 
 =back
 
@@ -5612,8 +5615,8 @@ List all filenames containing I<what>.
 
 =item B<--characterization>
 
-Search in the given taxonomy instead of the package descriptions.  See
-L</"TAXONOMIES"> below.
+Search in the corresponding taxonomy (or all) instead of the package
+descriptions.  See L</"TAXONOMIES"> below.
 
 =back
 
@@ -5630,14 +5633,14 @@ information is slightly off due to timing issues.
 
 Options:
 
-=over4
+=over 4
 
 =item B<--list>
 
 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.
+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<--taxonomy>
 
@@ -5647,9 +5650,9 @@ outputs their dependencies in a similar way.
 
 =item B<--characterization>
 
-In addition to the normal data displayed, also display the various
-taxonomies. 
-See L</"TAXONOMIES"> below for details.
+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
 
@@ -5933,10 +5936,48 @@ GUI and a simplified with only the important and mostly used settings.
 
 =head1 TAXONOMIES
 
-tlmgr allows searching and listing of various taxonomies as provided
-by newer version of the TeX Catalogue.
+tlmgr allows searching and listing of various categorizations, which we
+call I<taxonomies>, as provided by an enhanced TeX Catalogue (available
+for testing at L<http://az.ctan.org>).  This is useful when, for
+example, you don't know a specific package name but have an idea of the
+functionality you need; or when you want to see all packages relating to
+a given area.
+
+There are three different taxonomies, specified by the following
+options:
+
+=over 4
+
+=item B<--keyword>
 
-MORE INFORMATION NEEDED.
+The keywords, as specified at L<http://az.ctan.org/keyword>.
+
+=item B<--functionality>
+
+The ``by-topic'' categorization created by J\"urgen Fenn, as specified
+at L<http://az.ctan.org/characterization/by-function>.
+
+=item B<--characterization>
+
+Both the primary and secondary functionalities, as specified at
+L<http://az.ctan.org/characterization/choose_dimen>.
+
+=item B<--taxonomy>
+
+Operate on all the taxonomies.
+
+=back
+
+The taxonomies are updated nightly and stored within TeX Live, so
+Internet access is not required to search them.
+
+Examples:
+  
+  tlmgr search --taxonomy exercise      # check all taxonomies for "exercise"
+  tlmgr search --taxonomy --word table  # check for "table" on its own
+  tlmgr search --list --keyword         # dump entire keyword taxonomy
+  tlmgr show --taxonomy pdftex          # show pdftex package information,
+                                        #   including all taxonomy entries
 
 
 =head1 GUI FOR TLMGR