update documentation, update man page

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

1 files changed, 145 insertions, 115 deletions

diff --git a/Master/tlpkg/man/TeXLive-TLPOBJ.1 b/Master/tlpkg/man/TeXLive-TLPOBJ.1
index 5ce64690b55..df21ce1e566 100644
--- a/Master/tlpkg/man/TeXLive-TLPOBJ.1
+++ b/Master/tlpkg/man/TeXLive-TLPOBJ.1
@@ -129,17 +129,17 @@
 .\" ========================================================================
 .\"
 .IX Title "TLPOBJ 3"
-.TH TLPOBJ 3 "2007-07-12" "perl v5.8.8" "User Contributed Perl Documentation"
+.TH TLPOBJ 3 "2007-11-12" "perl v5.8.8" "User Contributed Perl Documentation"
 .SH "NAME"
-TeXLive::TLPOBJ \- TeX Live Package Object access module
+\&\f(CW\*(C`TeXLive::TLPOBJ\*(C'\fR \-\- TeX Live Package Object access module
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
 .Vb 1
-\&        use TeXLive::TLPOBJ;
+\&  use TeXLive::TLPOBJ;
 .Ve
 .PP
 .Vb 1
-\&        my $tlpobj = TeXLive::TLPOBJ\->new( name => "foobar" );
+\&  my $tlpobj=TeXLive::TLPOBJ\->new(name => "foobar");
 .Ve
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
@@ -155,18 +155,15 @@ all last changed revision of files contained in the package, and anything
 starting with \f(CW\*(C`catalogue\-\*(C'\fR specifying information coming from the
 TeX Catalogue.
 .PP
-All these keys have in common that the are followed by a list of files
-\&\fBintended\fR by one space. They differ only in the first line itself
+All these keys have in common that they are followed by a list of files
+\&\fIindented\fR by one space. They differ only in the first line itself
 (described below).
-.ie n .IP """srcfiles""\fR, \f(CW""runfiles""" 4
-.el .IP "\f(CWsrcfiles\fR, \f(CWrunfiles\fR" 4
-.IX Item "srcfiles, runfiles"
-each of these three items contains in addition the sum of sizes of the
-single files (currently in byte, but this may change).
-.Sp
+.ie n .IP """srcfiles""\fR, \f(CW""runfiles""\fR, \f(CW""binfiles""\fR, \f(CW""docfiles"" each of these items contains addition the sum of sizes of the single files (currently in bytes)." 4
+.el .IP "\f(CWsrcfiles\fR, \f(CWrunfiles\fR, \f(CWbinfiles\fR, \f(CWdocfiles\fR each of these items contains addition the sum of sizes of the single files (currently in bytes)." 4
+.IX Item "srcfiles, runfiles, binfiles, docfiles each of these items contains addition the sum of sizes of the single files (currently in bytes)."
 .Vb 2
-\&        srcfiles size=NNNNNN
-\&        runfiles size=NNNNNN
+\&  srcfiles size=NNNNNN
+\&  runfiles size=NNNNNN
 .Ve
 .ie n .IP """docfiles""" 4
 .el .IP "\f(CWdocfiles\fR" 4
@@ -175,51 +172,56 @@ The docfiles line itself is similar to the \f(CW\*(C`srcfiles\*(C'\fR and \f(CW\
 above:
 .Sp
 .Vb 1
-\&        docfiles size=NNNNNN
+\&  docfiles size=NNNNNN
 .Ve
 .Sp
 But the lines listing the files are allowed to have additional tags:
 .Sp
 .Vb 6
-\&        /\-\-\-\-\-\-\- excerpt from achemso.tlpobj
-\&        |...
-\&        |docfiles size=1702468
-\&        | texmf\-dist/doc/latex/aeguill/README details="Package Readme"
-\&        | texmf\-dist/doc/latex/achemso/achemso.pdf details="Package documentation" language="en"
-\&        |...
+\&  /\-\-\-\-\-\-\- excerpt from achemso.tlpobj
+\&  |...
+\&  |docfiles size=1702468
+\&  | texmf\-dist/doc/latex/aeguill/README details="Package Readme"
+\&  | texmf\-dist/doc/latex/achemso/achemso.pdf details="Package documentation" language="en"
+\&  |...
 .Ve
 .Sp
 Currently only the tags \f(CW\*(C`details\*(C'\fR and \f(CW\*(C`language\*(C'\fR are allowed.
-.ie n .IP """runfiles""" 4
-.el .IP "\f(CWrunfiles\fR" 4
-.IX Item "runfiles"
-Since \f(CW\*(C`runfiles\*(C'\fR are different for the different architectures one \f(CW\*(C`tlpobj\*(C'\fR
-file can contain \f(CW\*(C`runfiles\*(C'\fR lines for different architectures. The
-architecture is specified on the \f(CW\*(C`binfiles\*(C'\fR using the \f(CW\*(C`arch=XXX\*(C'\fR tag. Thus,
-\&\f(CW\*(C`binfiles\*(C'\fR lines look like
+.ie n .IP """binfiles""" 4
+.el .IP "\f(CWbinfiles\fR" 4
+.IX Item "binfiles"
+Since \f(CW\*(C`binfiles\*(C'\fR are different for the different architectures one
+\&\f(CW\*(C`tlpobj\*(C'\fR file can contain \f(CW\*(C`binfiles\*(C'\fR lines for different
+architectures. The architecture is specified on the \f(CW\*(C`binfiles\*(C'\fR using
+the \f(CW\*(C`arch=\*(C'\fR\fI\s-1XXX\s0\fR tag. Thus, \f(CW\*(C`binfiles\*(C'\fR lines look like
 .Sp
 .Vb 1
-\&        binfiles arch=XXXX size=NNNNN
+\&  binfiles arch=XXXX size=NNNNN
 .Ve
 .PP
-Thus a typical entry for runfiles looks like this:
+Here is an excerpt from the representation of the \f(CW\*(C`bin\-dvipsk\*(C'\fR package,
+with \f(CW\*(C`|\*(C'\fR characters inserted to show the indentation:
 .PP
-.Vb 15
-\&        /\-\-\-\-\-\-\- excerpt from bin\-dvips.tlpobj
-\&        |...
-\&        |runfiles size=1702468
-\&        | texmf/dvips/base/color.pro
-\&        | ...
-\&        | texmf/scripts/pkfix/pkfix.pl
-\&        |binfiles arch=i386\-solaris size=329700
-\&        | bin/i386\-solaris/afm2tfm
-\&        | bin/i386\-solaris/dvips
-\&        | bin/i386\-solaris/pkfix
-\&        |binfiles arch=win32 size=161280
-\&        | bin/win32/afm2tfm.exe
-\&        | bin/win32/dvips.exe
-\&        | bin/win32/pkfix.exe
-\&        |...
+.Vb 19
+\&  |name bin\-dvipsk
+\&  |category TLCore
+\&  |revision 4427
+\&  |docfiles size=959434
+\&  | texmf/doc/dvips/dvips.html
+\&  | ...
+\&  |runfiles size=1702468
+\&  | texmf/dvips/base/color.pro
+\&  | ...
+\&  | texmf/scripts/pkfix/pkfix.pl
+\&  |binfiles arch=i386\-solaris size=329700
+\&  | bin/i386\-solaris/afm2tfm
+\&  | bin/i386\-solaris/dvips
+\&  | bin/i386\-solaris/pkfix
+\&  |binfiles arch=win32 size=161280
+\&  | bin/win32/afm2tfm.exe
+\&  | bin/win32/dvips.exe
+\&  | bin/win32/pkfix.exe
+\&  |...
 .Ve
 .SH "PACKAGE VARIABLES"
 .IX Header "PACKAGE VARIABLES"
@@ -227,14 +229,14 @@ TeXLive::TLPOBJ has one package wide variable which is \f(CW\*(C`zipdir\*(C'\fR
 generated zip files are saved (if not otherwise specified.
 .PP
 .Vb 1
-\&        TeXLive::TLPOBJ\->zipdir("path/to/zip/dir");
+\&  TeXLive::TLPOBJ\->zipdir("path/to/zip/dir");
 .Ve
 .SH "MEMBER ACCESS FUNCTIONS"
 .IX Header "MEMBER ACCESS FUNCTIONS"
 For any of the \fIkeys\fR a function
 .PP
 .Vb 1
-\&        $tlpobj\->key
+\&  $tlpobj\->key
 .Ve
 .PP
 is available, which returns the current value when called without an argument,
@@ -242,24 +244,29 @@ and sets the respective value when called with an argument. For the
 TeX Catalogue Data the function
 .PP
 .Vb 1
-\&        $tlpobj\->cataloguedata
+\&  $tlpobj\->cataloguedata
 .Ve
 .PP
 returns and takes as argument a hash.
 .PP
 Arguments and return values for \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`category\*(C'\fR, \f(CW\*(C`shortdesc\*(C'\fR,
 \&\f(CW\*(C`longdesc\*(C'\fR, \f(CW\*(C`catalogue\*(C'\fR, \f(CW\*(C`revision\*(C'\fR are single scalars.
+.PP
 Arguments and return values for \f(CW\*(C`depends\*(C'\fR, \f(CW\*(C`executes\*(C'\fR are lists.
-Arguments and return values for \f(CW\*(C`binfiles\*(C'\fR is a hash with the architectures
-as keys.
 .PP
-Other functions which work quite similar are:
+Arguments and return values for \f(CW\*(C`docfiles\*(C'\fR, \f(CW\*(C`runfiles\*(C'\fR, \f(CW\*(C`srcfiles\*(C'\fR
+are lists.
+.PP
+Arguments and return values for \f(CW\*(C`binfiles\*(C'\fR is a hash with the
+architectures as keys.
+.PP
+The size values are handled with these functions:
 .PP
 .Vb 4
-\&        $tlpobj\->docsize
-\&        $tlpobj\->srcsize
-\&        $tlpobj\->runsize
-\&        $tlpobj\->binsize
+\&  $tlpobj\->docsize
+\&  $tlpobj\->runsize
+\&  $tlpobj\->srcsize
+\&  $tlpobj\->binsize("arch1", ...)
 .Ve
 .PP
 which set or get the current value of the respective sizes. Note that also
@@ -271,12 +278,12 @@ The following functions can be called for an \f(CW\*(C`TLPOBJ\*(C'\fR object:
 .ie n .IP """new""" 4
 .el .IP "\f(CWnew\fR" 4
 .IX Item "new"
-(constructor) returns a new \f(CW\*(C`TLPSRC\*(C'\fR object. The arguments to the \f(CW\*(C`new\*(C'\fR
-constructor can be in the usual hash representation for the different keys
-above:
+The constructor \f(CW\*(C`new\*(C'\fR returns a new \f(CW\*(C`TLPSRC\*(C'\fR object. The arguments
+to the \f(CW\*(C`new\*(C'\fR constructor can be in the usual hash representation for
+the different keys above:
 .Sp
 .Vb 1
-\&        $tlpobj = TLPOBJ\->new ( name => "foobar", shortdesc => "The foobar package" );
+\&  $tlpobj=TLPOBJ\->new(name => "foobar", shortdesc => "The foobar package");
 .Ve
 .ie n .IP """from_file(""filename"")""" 4
 .el .IP "\f(CWfrom_file(``filename'')\fR" 4
@@ -284,89 +291,112 @@ above:
 reads a \f(CW\*(C`tlpobj\*(C'\fR file.
 .Sp
 .Vb 2
-\&        $tlpobj = new TLPOBJ;
-\&        $tlpobj\->from_file("path/to/the/tlpobj/file");
+\&  $tlpobj = new TLPOBJ;
+\&  $tlpobj\->from_file("path/to/the/tlpobj/file");
 .Ve
-.ie n .IP """from_fh($filehandle [, $multi] )""" 4
-.el .IP "\f(CWfrom_fh($filehandle [, $multi] )\fR" 4
-.IX Item "from_fh($filehandle [, $multi] )"
-read the textual representation of a \s-1TLPOBJ\s0 from an already opened file handle.
-If \f(CW$multi\fR is undefined (ie not given) then multiple tlpobj in the
-same file are treated as errors. If \f(CW$multi\fR is defined then returns
-after reading one tlpobj.
+.ie n .IP """from_fh($filehandle[, $multi])""" 4
+.el .IP "\f(CWfrom_fh($filehandle[, $multi])\fR" 4
+.IX Item "from_fh($filehandle[, $multi])"
+read the textual representation of a \s-1TLPOBJ\s0 from an already opened
+file handle.  If \f(CW$multi\fR is undefined (ie not given) then multiple
+tlpobj in the same file are treated as errors. If \f(CW$multi\fR is defined
+then returns after reading one tlpobj.
 .Sp
-Returns 1 if it found a tlpobj, otherwise 0
+Returns \f(CW1\fR if it found a \f(CW\*(C`tlpobj\*(C'\fR, otherwise \f(CW0\fR.
 .ie n .IP """writeout""" 4
 .el .IP "\f(CWwriteout\fR" 4
 .IX Item "writeout"
-writes the textual representation of a \f(CW\*(C`TLPOBJ\*(C'\fR object to stdout, or the
-filehandle if given:
+writes the textual representation of a \f(CW\*(C`TLPOBJ\*(C'\fR object to \f(CW\*(C`stdout\*(C'\fR,
+or the filehandle if given:
 .Sp
 .Vb 2
-\&        $tlpsrc\->writeout;
-\&        $tlpsrc\->writeout(\e*FILEHANDLE);
+\&  $tlpsrc\->writeout;
+\&  $tlpsrc\->writeout(\e*FILEHANDLE);
 .Ve
 .ie n .IP """writeout_simple""" 4
 .el .IP "\f(CWwriteout_simple\fR" 4
 .IX Item "writeout_simple"
-debugging function for comparison with tpm/tlps, will go away.
-.ie n .IP """make_zip($tltree[,$destdir[,$zipname]])""" 4
-.el .IP "\f(CWmake_zip($tltree[,$destdir[,$zipname]])\fR" 4
-.IX Item "make_zip($tltree[,$destdir[,$zipname]])"
-creates a zip file of the arch \fBindependent\fR files in the \s-1TLPOBJ\s0
-in \f(CW$destdir\fR (if not defined then \s-1TLPOBJ\-\s0>zipdir is used).
-The file name of the created zipfile is \f(CW$zipname\fR (if not
-present \f(CW$tlpobj\fR\->name.zip)
+debugging function for comparison with \f(CW\*(C`tpm\*(C'\fR/\f(CW\*(C`tlps\*(C'\fR, will go away.
+.ie n .IP """make_zip($type,$instroot[, $destdir[, $zipname]])""" 4
+.el .IP "\f(CWmake_zip($type,$instroot[, $destdir[, $zipname]])\fR" 4
+.IX Item "make_zip($type,$instroot[, $destdir[, $zipname]])"
+creates a container file of the arch \fBindependent\fR files in the \f(CW\*(C`TLPOBJ\*(C'\fR
+in \f(CW$destdir\fR (if not defined then \f(CW\*(C`TLPOBJ\->zipdir\*(C'\fR is used).
+.Sp
+The \f(CW$type\fR variable specifies the type of container to be used.
+Currently only \f(CW\*(C`zip\*(C'\fR or \f(CW\*(C`lzma\*(C'\fR are allowed, and are generating
+zip files and tar.lzma files, respectively.
 .Sp
-If the package contains \*(L"binfiles\*(R"; then zip files for 
+The file name of the created container file is \f(CW\*(C`$zipname.extension\*(C'\fR,
+where extension is either \f(CW\*(C`.zip\*(C'\fR or \f(CW\*(C`.tar.lzma\*(C'\fR, depending on the
+setting of \f(CW$type\fR. If no \f(CW$zipname\fR is specified the package name
+is used.
+.Sp
+If the package contains \f(CW"binfiles"\fR, then container files for 
 all archs containing \fBonly\fR the binfiles are created, and 
-the zipfile name is \f(CW\*(C`$zipname.$arch.zip\*(C'\fR
+those container files name is \f(CW\*(C`$zipname.$arch.$extension\*(C'\fR
+.Sp
+All the arch independent zip files \fBalso\fR contain the respective
+\&\f(CW\*(C`TLPOBJ\*(C'\fR file in \f(CW\*(C`tlpkg/tlpobj/$name.tlpobj\*(C'\fR so \f(CW\*(C`$zipname.$extension\*(C'\fR does
+contain this tlpobj file, while \f(CW\*(C`$zipname.$arch.$extension\*(C'\fR does \s-1NOT\s0.
 .Sp
-All the arch independent zip files \fBalso\fR contain the 
-respective \s-1TLPOBJ\s0 file in 
-	.tlpobj/$name.tlpobj
-so \f(CW\*(C`$zipname.zip\*(C'\fR does contain this tlpobj file, while
-\&\f(CW\*(C`$zipname.$arch.zip\*(C'\fR does \s-1NOT\s0.
-.ie n .IP """recompute_sizes ($tltree)""" 4
-.el .IP "\f(CWrecompute_sizes ($tltree)\fR" 4
-.IX Item "recompute_sizes ($tltree)"
+The argument \f(CW$instroot\fR specifies the root of the installation from
+which the files should be taken.
+.ie n .IP """recompute_sizes($tltree)""" 4
+.el .IP "\f(CWrecompute_sizes($tltree)\fR" 4
+.IX Item "recompute_sizes($tltree)"
 recomputes the sizes based on the information present in \f(CW$tltree\fR.
-.ie n .IP """recompute_revision ($tltree)""" 4
-.el .IP "\f(CWrecompute_revision ($tltree)\fR" 4
-.IX Item "recompute_revision ($tltree)"
+.ie n .IP """recompute_revision($tltree [, $revtlpsrc ])""" 4
+.el .IP "\f(CWrecompute_revision($tltree [, $revtlpsrc ])\fR" 4
+.IX Item "recompute_revision($tltree [, $revtlpsrc ])"
 recomputes the revision based on the information present in \f(CW$tltree\fR.
-.ie n .IP """update_from_catalogue ($texcatalogue)""" 4
-.el .IP "\f(CWupdate_from_catalogue ($texcatalogue)\fR" 4
-.IX Item "update_from_catalogue ($texcatalogue)"
+The optional argument \f(CW$rectlpsrc\fR can be an additional revision number
+which is taken into account. \f(CW\*(C`$tlpsrc\-\*(C'\fRmake_tlpobj> adds the revision
+number of the \f(CW\*(C`tlpsrc\*(C'\fR file here so that collections (which do not
+contain files) also have revision number.
+.ie n .IP """update_from_catalogue($texcatalogue)""" 4
+.el .IP "\f(CWupdate_from_catalogue($texcatalogue)\fR" 4
+.IX Item "update_from_catalogue($texcatalogue)"
 adds information from a \f(CW\*(C`TeXCatalogue\*(C'\fR object 
 (currently license, version, url, and updates docfiles with details and
-languages tags if present in the Catalogue)
+languages tags if present in the Catalogue).
 .ie n .IP """is_arch_dependent""" 4
 .el .IP "\f(CWis_arch_dependent\fR" 4
 .IX Item "is_arch_dependent"
-returns 1 if there are \f(CW\*(C`binfiles\*(C'\fR, otherwise 0.
+returns \f(CW1\fR if there are \f(CW\*(C`binfiles\*(C'\fR, otherwise \f(CW0\fR.
 .ie n .IP """total_size""" 4
 .el .IP "\f(CWtotal_size\fR" 4
 .IX Item "total_size"
-If no argument is given returns the sum of \f(CW\*(C`srcsize\*(C'\fR, \f(CW\*(C`docsize\*(C'\fR, \f(CW\*(C`runsize\*(C'\fR
+If no argument is given returns the sum of \f(CW\*(C`srcsize\*(C'\fR, \f(CW\*(C`docsize\*(C'\fR,
+\&\f(CW\*(C`runsize\*(C'\fR.
 .Sp
-If and argumen is given it returns the sum of the above increased by the
-sum of sizes of \f(CW\*(C`binsize\*(C'\fR for the architectures given as argument.
-.ie n .IP """{add,remove}_{src,run,doc}files ( @files )""" 4
-.el .IP "\f(CW{add,remove}_{src,run,doc}files ( @files )\fR" 4
-.IX Item "{add,remove}_{src,run,doc}files ( @files )"
-adds or removes files to the respective list of files
-.ie n .IP """{add,remove}_binfiles ($arch, @files)""" 4
-.el .IP "\f(CW{add,remove}_binfiles ($arch, @files)\fR" 4
-.IX Item "{add,remove}_binfiles ($arch, @files)"
-adds or removes files from the list of \f(CW\*(C`binfiles\*(C'\fR for the given architecture
-.ie n .IP """{add,remove}_files ($type, $files)""" 4
-.el .IP "\f(CW{add,remove}_files ($type, $files)\fR" 4
-.IX Item "{add,remove}_files ($type, $files)"
+If arguments are given, they are assumed to be architecture names, and
+it returns the above plus the sum of sizes of \f(CW\*(C`binsize\*(C'\fR for those
+architectures.
+.ie n .IP """is_meta_package""" 4
+.el .IP "\f(CWis_meta_package\fR" 4
+.IX Item "is_meta_package"
+Returns true if the package is a meta package as defined in TLConfig
+(Currently Collection and Scheme).
+.ie n .IP """{add,remove}_{src,run,doc}files(@files)""" 4
+.el .IP "\f(CW{add,remove}_{src,run,doc}files(@files)\fR" 4
+.IX Item "{add,remove}_{src,run,doc}files(@files)"
+adds or removes files to the respective list of files.
+.ie n .IP """{add,remove}_binfiles($arch, @files)""" 4
+.el .IP "\f(CW{add,remove}_binfiles($arch, @files)\fR" 4
+.IX Item "{add,remove}_binfiles($arch, @files)"
+adds or removes files from the list of \f(CW\*(C`binfiles\*(C'\fR for the given architecture.
+.ie n .IP """{add,remove}_files($type, $files)""" 4
+.el .IP "\f(CW{add,remove}_files($type, $files)\fR" 4
+.IX Item "{add,remove}_files($type, $files)"
 adds or removes files for the given type (only for \f(CW\*(C`run\*(C'\fR, \f(CW\*(C`src\*(C'\fR, \f(CW\*(C`doc\*(C'\fR).
+.ie n .IP """all_files""" 4
+.el .IP "\f(CWall_files\fR" 4
+.IX Item "all_files"
+returns a list of all files of all types.
 .SH "SEE ALSO"
 .IX Header "SEE ALSO"
-The modules TeXLive::TLUtils, TeXLive::TLPSRC,
+The modules TeXLive::TLConfig, TeXLive::TLUtils, TeXLive::TLPSRC,
 TeXLive::TLPDB, TeXLive::TLTREE, TeXLive::TeXCatalogue.
 .SH "AUTHORS AND COPYRIGHT"
 .IX Header "AUTHORS AND COPYRIGHT"