pod documentation of TLPSRC, this includes the specification and the

Perl API!!!!


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

1 files changed, 259 insertions, 0 deletions

diff --git a/Master/tlpkg/TeXLive/TLPSRC.pm b/Master/tlpkg/TeXLive/TLPSRC.pm
index c1efda1c33b..c1e70314a86 100644
--- a/Master/tlpkg/TeXLive/TLPSRC.pm
+++ b/Master/tlpkg/TeXLive/TLPSRC.pm
@@ -5,6 +5,8 @@
 #
 # This file is licensed under the GNU General Public Licence version 2
 # or any later version
+#
+# pod documentation at the bottom
 
 package TeXLive::TLPSRC;
 
@@ -383,6 +385,263 @@ longdesc ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~
 $_tmp
 .
 
+__END__
+
+=head1 NAME
+
+TeXLive::TLPSRC - TeX Live Source Package access modules
+
+=head1 SYNOPSIS
+
+	use TeXLive::TLPSRC;
+
+	my $tlpsrc = TeXLive::TLPSRC->new( name => "foobar" );
+	$tlpsrc->from_file("package.tlpsrc");
+	$tlpsrc->writeout;
+	$tlpsrc->writeout(\*FILEHANDLE);
+
+
+=head1 DESCRIPTION
+
+The L<TeXLive::TLPSRC> module provide access to TeX Live Package Source
+files, which contains all the information which cannot be automatically
+derived from the files in the TeX Live subversion repository.
+
+=head1 FILE SPECIFICATION
+
+A L<tlpsrc> file has to consist of non-empty lines (initial and final
+empty lines are ignored) of the form
+
+I<key value>
+
+where I<key> can be C<name>, C<category>, C<shortdesc>, C<longdesc>,
+C<catalogue>, C<runpattern>, C<srcpattern>, C<docpattern>, C<binpattern>,
+C<execute>, or C<depend>.
+
+The interpretation of the respective I<values> are:
+
+=over
+
+=item C<name>
+
+identifies the package, C<value> must consist only of [-_a-zA-Z0-9]
+
+=item C<category>
+
+identifies the category into which this package belongs. Possible categories
+are C<Collection>, C<Scheme>, C<TLCore>, C<Documentation>, C<Package>.
+Note that there is no inherent checking whether a C<tlpsrc> file called
+C<collection-something> actually belongs to the category C<Collection>.
+Most packages will fall into the C<Package> category.
+
+=item C<catalogue>
+
+(currently not used in TeX Live) identifies the name under which this
+package can be found in the TeX Catalogue.
+
+=item C<shortdesc>
+
+gives a one line description of the package. Susequent entries will overwrite
+the former ones. In TeX Live only used for collections and schemes.
+
+=item C<longdesc>
+
+gives a long description of the package. Susequent entries are added up
+to a long text. In TeX Live only used for collections and schemes.
+
+=item C<depend>
+
+gives the list of dependencies of the package in the form
+
+I<Category>/I<Name>
+
+All the depend lines contribute to the dependencies of the package.
+
+=item C<execute>
+
+gives a free form entry of install time jobs to be executed. Currently
+the following possible values are understood by the installers:
+
+=over 6
+
+=item C<execute addMap I<font.map>>
+
+enables the font map file I<font.map> in the F<updmap.cfg> file.
+
+=item C<execute addMixedMap I<font.map>>
+
+enables the font map file I<font.map>> for Mixed mode in the F<updmap.cfg> file.
+
+=item C<execute BuildLanguageDat NN>
+
+activates all the hyphenation patterns found in 
+F<Master/texmf/tex/generic/config/language.NN.dat> in the generated
+F<language.dat> file.
+
+=item C<execute BuildFormat FMTCFG>
+
+activates all the formats present in F<Master/texmf/fmtutil/format.FMTCFG.cnf>
+in the generated F<fmtutil.cnf> file.
+
+=back
+
+=item C<(src|run|doc|bin)pattern I<pattern>>
+
+adds a pattern (see below) to the respective list of patterns.
+
+=back
+
+=head1 PATTERNS
+
+Patterns specify which files are to be included into a C<tlpobj> at
+expansion time. Patterns are of the form
+
+	[PREFIX]TYPE PAT
+
+where
+
+	PREFIX = + | +! | !
+	TYPE = t | f | d | r
+
+The meaning of the various pattern types is
+
+=over
+
+=item C<f path>
+
+includes all files which match C<path> where B<only> the last component
+of C<path> can contain the usual glob characters * and ? (but no others!).
+
+=item C<d path>
+
+includes all the files in and below the directory specified as C<path>.
+
+=item C<t word1 ... wordN worldL>
+
+includes all the files in and below all directories of the form
+
+	word1/word2/.../wordN/.../any/dirs/.../wordL/
+
+i.e., the first words but the last form the prefix of the path, then
+there can be an arbitrary nesting of directories, followed by C<wordL>
+as another directory.
+
+=item C<r regexp>
+
+includes all files matching the regexp C</^regexp$/>
+
+=back
+
+In the case that one of the pattern sections is empty or B<all> the provided
+patterns have the prefix C<+> (e.g., C<+f ...>), then the following patterns
+are B<automatically> added at expansion time (but never written to the
+textual representation):
+
+=over
+
+=item runpattern
+
+for runpatterns of category C<Package>
+
+	t texmf-dist topdir $name
+
+where C<topdir> is one of: bibtex context dvips fonts makeindex metafont
+metapost mft omega scripts tex vtex.
+
+For other categories B<no> patterns are automatically added to the 
+list of runpatterns.
+
+=item docpattern
+
+for docpattern of category C<Package>
+
+	t texmf-dist doc $name
+
+for docpattern of category C<Documentation>
+
+	t texmf-doc doc $name
+
+=item srcpattern
+
+for srcpattern of category C<Package>
+
+	t texmf-dist source $name
+
+for srcpattern of category C<Documentation>
+
+	t texmf-doc source $name
+
+=back
+
+binpatterns are never automatically added.
+
+If the C<PREFIX> contains the symbol ! the meaning of the pattern is
+reversed, i.e., file matching this pattern are removed from the list
+of included files.
+
+=head1 MEMBER ACCESS FUNCTIONS
+
+For any of the above I<keys> a function
+
+	$tlpsrc->key
+
+is available, which returns the current value when called without an argument,
+and sets the respective value when called with an argument.
+
+Arguments and return values for C<name>, C<category>, C<shortdesc>,
+C<longdesc>, C<catalogue> are single scalars. Arguments and return values
+for C<depends>, C<executes>, and the various C<patterns> are lists.
+
+=head1 OTHER FUNCTIONS
+
+The following functions can be called for an C<TLPSRC> object:
+
+=over 
+
+=item C<new>
+
+(constructor) returns a new C<TLPSRC> object. The arguments to the C<new>
+constructor can be in the usual hash representation for the different keys
+above:
+
+	$tlpsrc = TLPSRC->new ( name => "foobar", shortdesc => "The foobar package" );
+
+=item C<from_file("filename")>
+
+reads a C<tlpsrc> file.
+
+	$tlpsrc = new TLPSRC;
+	$tlpsrc->from_file("path/to/the/tlpsrc/file");
+
+=item C<writeout>
+
+writes the textual representation of a C<TLPSRC> object to stdout, or the
+filehandle if given:
+
+	$tlpsrc->writeout;
+	$tlpsrc->writeout(\*FILEHANDLE);
+
+=item C<make_tlpobj($tltree)>
+
+creates a C<TLPOBJ> object from a C<TLPSRC> object and a C<TLTREE> object.
+This function does the necessary work to expand the manual data and
+enrich it which the actual content from <$tltree> to a C<TLPOBJ> object.
+
+=head1 AUTHORS AND COPYRIGHT
+
+This module and its documentation was written by 
+Norbert Preining <F<preining@logic.at>> for the TeX Live distribution and both
+are licensed under the GNU General Public License Version 2 or later.
+
+=head1 SEE ALSO
+
+The modules L<TeXLive::TLUtils>, L<TeXLive::TLPOBJ>, 
+L<TeXLive::TLPDB>, L<TeXLive::TLTREE>.
+
+=cut
+
+
+
 ### Local Variables:
 ### perl-indent-level: 2
 ### tab-width: 2