summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNorbert Preining <preining@logic.at>2010-10-24 16:53:30 +0000
committerNorbert Preining <preining@logic.at>2010-10-24 16:53:30 +0000
commitb8d6ada9e3bfbd34a27ceb918fdf23dd7d188e6f (patch)
treef169519acc3f09335c6e04c7f778ea8e43c5665d
parent80bf3d55d794628d8b084ac36b60ec3bcc3cc642 (diff)
add POD documentation to parse-texcatalogue-keywords
git-svn-id: svn://tug.org/texlive/trunk@20166 c570f23f-e606-0410-a88d-b1316a301751
-rwxr-xr-xMaster/tlpkg/bin/parse-texcatalogue-keywords99
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: #