add POD documentation to parse-texcatalogue-keywords

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

1 files changed, 99 insertions, 0 deletions

diff --git a/Master/tlpkg/bin/parse-texcatalogue-keywords b/Master/tlpkg/bin/parse-texcatalogue-keywords
index ab15297b196..52de2036601 100755
--- a/Master/tlpkg/bin/parse-texcatalogue-keywords
+++ b/Master/tlpkg/bin/parse-texcatalogue-keywords
@@ -21,6 +21,7 @@ use XML::XPath::XMLParser;
 use Text::Unidecode;
 use Data::Dumper;
 use Getopt::Long;
+use Pod::Usage;
 use TeXLive::TLUtils;
 
 my %taxonomy;
@@ -206,3 +207,101 @@ sub walk_cz_tree {
   }
 }
 
+__END__
+
+=head1 NAME
+
+parse-texcatalogue-keywords - parse the experimental TeX Catalogue
+
+=head1 SYNOPSIS
+
+parse-texcatalogue-keywords [--input ....] [--output ...] [--help|-h|-?]
+
+=head1 DESCRIPTION
+
+This program parses the XML data dump of the experimental new
+TeX Catalogue which includes various characterizations of packages,
+into keywords, functionalities, and classifications.
+
+It dumps this data in a textual representation of a perl hash, which
+can very easily be read back into a perl program.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-input>
+
+from where to read the XML dump of the TeX Catalogue, defaults to STDIN.
+
+=item B<-output>
+
+where to write the data dump to, defaults to STDOUT.
+
+=item B<-help>, B<-h>, B<-?>
+
+prints out this help text.
+
+=back
+
+=head1 FORMAT OF THE DATA DUMP
+
+The following Perl expression explain in which way the data is saved into
+the dumped hash:
+
+  $taxonomy{'by-package'}{'keyword'}{$package} = [ $kwi, $kwii,...];
+
+List of keywords
+
+  $taxonomy{'by-package'}{'primary'}{$package} = $primchar;
+
+Scalar containing the primary characterization.
+
+  $taxonomy{'by-package'}{'secondary'}{$package'} = $secchar;
+
+Scalar containing the secondary characterization.
+
+  $taxonomy{'by-package'}{'functionality'}{$package} = [ $bfi, $bfii, ...];
+
+List of functionalities.
+
+Both the characterizations and functionalites are themselves subdivided into
+levels by the string separator " > " (without the quotes). To make
+these information more accessible the data is presented in a reverse
+way, too:
+
+  $taxonomy{'by-taxonomy'}{'keyword'}{$keyword} = [ $pkg1, $pkg2, ...];
+
+List of packages with that keyword
+
+  $taxonomy{'by-taxonomy'}{'primary'}{$level1}{$level2}...{'_packages_'} = [ $pkg1, $pkg2, ...];
+  $taxonomy{'by-taxonomy'}{'secondary'}{$level1}{$level2}...{'_packages_'} = [ $pkg1, $pkg2, ...];
+  taxonomy{'by-taxonomy'}{'functionality'}{$level1}{$level2}...{'_packages_'} = [ $pkg1, $pkg2, ...];
+
+The B<_packages_> is literal and contains the list of packages for all the
+previous levels.
+
+The following code allows to read back the array into the hash referenced
+by C<$taxonomy> (attention, in this code this is a B<reference> to a hash!
+  my $taxonomy;
+  my $taxtext = `cat $path_to_data_dump`;
+  no strict "vars";
+  eval "$taxtext";
+  use strict "vars";
+  return $taxonomy;
+
+
+=head1 AUTHORS AND COPYRIGHT
+
+This script and its documentation were written for the TeX Live
+distribution (L<http://tug.org/texlive>) and both are licensed under the
+GNU General Public License Version 2 or later.
+
+=cut
+
+### Local Variables:
+### perl-indent-level: 2
+### tab-width: 2
+### indent-tabs-mode: nil
+### End:
+# vim:set tabstop=2 expandtab: #