From 38f01e22f88da63e8ae3c1d8bb03f40b5e4edb59 Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 25 Jun 2007 16:52:44 +0000 Subject: 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 --- Master/tlpkg/TeXLive/TLPSRC.pm | 259 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 259 insertions(+) (limited to 'Master/tlpkg/TeXLive/TLPSRC.pm') 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 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 file has to consist of non-empty lines (initial and final +empty lines are ignored) of the form + +I + +where I can be C, C, C, C, +C, C, C, C, C, +C, or C. + +The interpretation of the respective I are: + +=over + +=item C + +identifies the package, C must consist only of [-_a-zA-Z0-9] + +=item C + +identifies the category into which this package belongs. Possible categories +are C, C, C, C, C. +Note that there is no inherent checking whether a C file called +C actually belongs to the category C. +Most packages will fall into the C category. + +=item C + +(currently not used in TeX Live) identifies the name under which this +package can be found in the TeX Catalogue. + +=item C + +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 + +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 + +gives the list of dependencies of the package in the form + +I/I + +All the depend lines contribute to the dependencies of the package. + +=item C + +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> + +enables the font map file I in the F file. + +=item C> + +enables the font map file I> for Mixed mode in the F file. + +=item C + +activates all the hyphenation patterns found in +F in the generated +F file. + +=item C + +activates all the formats present in F +in the generated F file. + +=back + +=item C<(src|run|doc|bin)pattern I> + +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 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 + +includes all files which match C where B the last component +of C can contain the usual glob characters * and ? (but no others!). + +=item C + +includes all the files in and below the directory specified as C. + +=item C + +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 +as another directory. + +=item C + +includes all files matching the regexp C + +=back + +In the case that one of the pattern sections is empty or B the provided +patterns have the prefix C<+> (e.g., C<+f ...>), then the following patterns +are B added at expansion time (but never written to the +textual representation): + +=over + +=item runpattern + +for runpatterns of category C + + t texmf-dist topdir $name + +where C is one of: bibtex context dvips fonts makeindex metafont +metapost mft omega scripts tex vtex. + +For other categories B patterns are automatically added to the +list of runpatterns. + +=item docpattern + +for docpattern of category C + + t texmf-dist doc $name + +for docpattern of category C + + t texmf-doc doc $name + +=item srcpattern + +for srcpattern of category C + + t texmf-dist source $name + +for srcpattern of category C + + t texmf-doc source $name + +=back + +binpatterns are never automatically added. + +If the C 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 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, C, C, +C, C are single scalars. Arguments and return values +for C, C, and the various C are lists. + +=head1 OTHER FUNCTIONS + +The following functions can be called for an C object: + +=over + +=item C + +(constructor) returns a new C object. The arguments to the C +constructor can be in the usual hash representation for the different keys +above: + + $tlpsrc = TLPSRC->new ( name => "foobar", shortdesc => "The foobar package" ); + +=item C + +reads a C file. + + $tlpsrc = new TLPSRC; + $tlpsrc->from_file("path/to/the/tlpsrc/file"); + +=item C + +writes the textual representation of a C object to stdout, or the +filehandle if given: + + $tlpsrc->writeout; + $tlpsrc->writeout(\*FILEHANDLE); + +=item C + +creates a C object from a C object and a C object. +This function does the necessary work to expand the manual data and +enrich it which the actual content from <$tltree> to a C object. + +=head1 AUTHORS AND COPYRIGHT + +This module and its documentation was written by +Norbert Preining > 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, L, +L, L. + +=cut + + + ### Local Variables: ### perl-indent-level: 2 ### tab-width: 2 -- cgit v1.2.3