TLPSRC: update the code for reading the name declaration in tlpsrc files

to not accept ^0texlive. 
Add some documentation about possible names to the pod, and update the man page


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

1 files changed, 222 insertions, 126 deletions

diff --git a/Master/tlpkg/man/TeXLive-TLPSRC.1 b/Master/tlpkg/man/TeXLive-TLPSRC.1
index 32837594845..5c4761fad9f 100644
--- a/Master/tlpkg/man/TeXLive-TLPSRC.1
+++ b/Master/tlpkg/man/TeXLive-TLPSRC.1
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
+.\" Automatically generated by Pod::Man 2.16 (Pod::Simple 3.05)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
@@ -48,22 +48,25 @@
 .    ds R" ''
 'br\}
 .\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\"
 .\" If the F register is turned on, we'll generate index entries on stderr for
 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
 .\" entries marked with X<> in POD.  Of course, you'll have to process the
 .\" output yourself in some meaningful fashion.
-.if \nF \{\
+.ie \nF \{\
 .    de IX
 .    tm Index:\\$1\t\\n%\t"\\$2"
 ..
 .    nr % 0
 .    rr F
 .\}
-.\"
-.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
+.el \{\
+.    de IX
+..
+.\}
 .\"
 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
@@ -128,31 +131,34 @@
 .rm #[ #] #H #V #F C
 .\" ========================================================================
 .\"
-.IX Title "TLPSRC 3"
-.TH TLPSRC 3 "2007-06-28" "perl v5.8.8" "User Contributed Perl Documentation"
+.IX Title "TeXLive::TLPSRC 3"
+.TH TeXLive::TLPSRC 3 "2008-06-09" "perl v5.10.0" "User Contributed Perl Documentation"
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
 .SH "NAME"
-TeXLive::TLPSRC \- TeX Live Package Source access module
+\&\f(CW\*(C`TeXLive::TLPSRC\*(C'\fR \*(-- TeX Live Package Source access module
 .SH "SYNOPSIS"
 .IX Header "SYNOPSIS"
 .Vb 1
-\&        use TeXLive::TLPSRC;
-.Ve
-.PP
-.Vb 4
-\&        my $tlpsrc = TeXLive::TLPSRC\->new( name => "foobar" );
-\&        $tlpsrc\->from_file("package.tlpsrc");
-\&        $tlpsrc\->writeout;
-\&        $tlpsrc\->writeout(\e*FILEHANDLE);
+\&  use TeXLive::TLPSRC;
+\&
+\&  my $tlpsrc = TeXLive::TLPSRC\->new(name => "foobar");
+\&  $tlpsrc\->from_file("/some/tlpsrc/package.tlpsrc");
+\&  $tlpsrc\->from_file("package");
+\&  $tlpsrc\->writeout;
+\&  $tlpsrc\->writeout(\e*FILEHANDLE);
 .Ve
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
-The TeXLive::TLPSRC module provide access to TeX Live Package Source
+The \f(CW\*(C`TeXLive::TLPSRC\*(C'\fR 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.
 .SH "FILE SPECIFICATION"
 .IX Header "FILE SPECIFICATION"
-A tlpsrc file has to consist of non-empty lines (initial and final
-empty lines are ignored) of the form
+A \f(CW\*(C`tlpsrc\*(C'\fR file has to consist of non-empty lines (except that initial
+and final empty lines are ignored) of the form
 .PP
 \&\fIkey value\fR
 .PP
@@ -161,71 +167,101 @@ where \fIkey\fR can be \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`category\*(C'\fR, \f(CW
 \&\f(CW\*(C`execute\*(C'\fR, or \f(CW\*(C`depend\*(C'\fR.
 .PP
 The interpretation of the respective \fIvalues\fR are:
-.ie n .IP """name""" 4
-.el .IP "\f(CWname\fR" 4
+.ie n .IP """name""" 6
+.el .IP "\f(CWname\fR" 6
 .IX Item "name"
-identifies the package, \f(CW\*(C`value\*(C'\fR must consist only of [\-_a\-zA\-Z0\-9]
-.ie n .IP """category""" 4
-.el .IP "\f(CWcategory\fR" 4
+identifies the package, \f(CW\*(C`value\*(C'\fR must consist only of \f(CW\*(C`[\-_a\-zA\-Z0\-9]\*(C'\fR,
+i.e., with what Perl considers a \f(CW\*(C`\ew\*(C'\fR.
+.Sp
+There are 3 exceptions to this rule:
+.RS 6
+.IP "\fBname.ARCH\fR" 12
+.IX Item "name.ARCH"
+where \fB\s-1ARCH\s0\fR is a supported architecture-os combination.
+The use of this is two-fold: On the one hand packages are split into 
+containers for the different architectures to make installations including
+only the necessary binaries possible. On the other hand one can add
+\&'one\-arch\-only' packages, often used to deal with the peculiarities of the
+Windows family of systems.
+.IP "\fB00texliveSOMETHING\fR" 12
+.IX Item "00texliveSOMETHING"
+these packages are used for internal operation
+and storage containers for settings. Besides being the only packages starting
+with \fB00texlive\fR they will never be split into separate arch-packages, and
+containers are never generated for these packages.
+.IP "\fBtexliveSOME.THING\fR" 12
+.IX Item "texliveSOME.THING"
+(mind the dot in the package name) these packages
+are central TeX Live internal packages and are treated as usual packages
+in (more or less) all respects, but have that extra dot to be sure they
+are different from every package that can possibly appear on \s-1CTAN\s0.
+.RE
+.RS 6
+.RE
+.ie n .IP """category""" 6
+.el .IP "\f(CWcategory\fR" 6
 .IX Item "category"
 identifies the category into which this package belongs. Possible categories
-are \f(CW\*(C`Collection\*(C'\fR, \f(CW\*(C`Scheme\*(C'\fR, \f(CW\*(C`TLCore\*(C'\fR, \f(CW\*(C`Documentation\*(C'\fR, \f(CW\*(C`Package\*(C'\fR.
+are defined in \f(CW\*(C`TeXLive::TLConfig\*(C'\fR, but are currently
+\&\f(CW\*(C`Collection\*(C'\fR, \f(CW\*(C`Scheme\*(C'\fR, \f(CW\*(C`TLCore\*(C'\fR, \f(CW\*(C`Documentation\*(C'\fR, \f(CW\*(C`Package\*(C'\fR.
 Note that there is no inherent checking whether a \f(CW\*(C`tlpsrc\*(C'\fR file called
 \&\f(CW\*(C`collection\-something\*(C'\fR actually belongs to the category \f(CW\*(C`Collection\*(C'\fR.
 Most packages will fall into the \f(CW\*(C`Package\*(C'\fR category.
-.ie n .IP """catalogue""" 4
-.el .IP "\f(CWcatalogue\fR" 4
+.ie n .IP """catalogue""" 6
+.el .IP "\f(CWcatalogue\fR" 6
 .IX Item "catalogue"
 (currently not used in TeX Live) identifies the name under which this
 package can be found in the TeX Catalogue.
-.ie n .IP """shortdesc""" 4
-.el .IP "\f(CWshortdesc\fR" 4
+.ie n .IP """shortdesc""" 6
+.el .IP "\f(CWshortdesc\fR" 6
 .IX Item "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.
-.ie n .IP """longdesc""" 4
-.el .IP "\f(CWlongdesc\fR" 4
+gives a one line description of the package. Subsequent entries will
+overwrite the former ones. In TeX Live only used for collections and
+schemes.
+.ie n .IP """longdesc""" 6
+.el .IP "\f(CWlongdesc\fR" 6
 .IX Item "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.
-.ie n .IP """depend""" 4
-.el .IP "\f(CWdepend\fR" 4
+.ie n .IP """depend""" 6
+.el .IP "\f(CWdepend\fR" 6
 .IX Item "depend"
 gives the list of dependencies of the package in the form
 .Sp
 \&\fICategory\fR/\fIName\fR
 .Sp
 All the depend lines contribute to the dependencies of the package.
-.ie n .IP """execute""" 4
-.el .IP "\f(CWexecute\fR" 4
+.ie n .IP """execute""" 6
+.el .IP "\f(CWexecute\fR" 6
 .IX Item "execute"
 gives a free form entry of install time jobs to be executed. Currently
 the following possible values are understood by the installers:
-.RS 4
-.ie n .IP """execute addMap \f(CIfont.map\f(CW""" 6
-.el .IP "\f(CWexecute addMap \f(CIfont.map\f(CW\fR" 6
+.RS 6
+.ie n .IP """execute addMap""\fR \fIfont\fR\f(CW"".map""" 6
+.el .IP "\f(CWexecute addMap\fR \fIfont\fR\f(CW.map\fR" 6
 .IX Item "execute addMap font.map"
-enables the font map file \fIfont.map\fR in the \fIupdmap.cfg\fR file.
-.ie n .IP """execute addMixedMap \f(CIfont.map\f(CW""" 6
-.el .IP "\f(CWexecute addMixedMap \f(CIfont.map\f(CW\fR" 6
+enables the font map file \fIfont\fR\f(CW\*(C`.map\*(C'\fR in the \f(CW\*(C`updmap.cfg\*(C'\fR file.
+.ie n .IP """execute addMixedMap""\fR \fIfont\fR\f(CW"".map""" 6
+.el .IP "\f(CWexecute addMixedMap\fR \fIfont\fR\f(CW.map\fR" 6
 .IX Item "execute addMixedMap font.map"
-enables the font map file \fIfont.map\fR> for Mixed mode in the \fIupdmap.cfg\fR file.
+enables the font map file \fIfont\fR\f(CW\*(C`.map\*(C'\fR for Mixed mode in the
+\&\f(CW\*(C`updmap.cfg\*(C'\fR file.
 .ie n .IP """execute BuildLanguageDat NN""" 6
 .el .IP "\f(CWexecute BuildLanguageDat NN\fR" 6
 .IX Item "execute BuildLanguageDat NN"
 activates all the hyphenation patterns found in 
-\&\fIMaster/texmf/tex/generic/config/language.NN.dat\fR in the generated
-\&\fIlanguage.dat\fR file.
+\&\f(CW\*(C`Master/texmf/tex/generic/config/language.NN.dat\*(C'\fR in the generated
+\&\f(CW\*(C`language.dat\*(C'\fR file.
 .ie n .IP """execute BuildFormat FMTCFG""" 6
 .el .IP "\f(CWexecute BuildFormat FMTCFG\fR" 6
 .IX Item "execute BuildFormat FMTCFG"
-activates all the formats present in \fIMaster/texmf/fmtutil/format.FMTCFG.cnf\fR
-in the generated \fIfmtutil.cnf\fR file.
+activates all the formats present in \f(CW\*(C`Master/texmf/fmtutil/format.FMTCFG.cnf\*(C'\fR
+in the generated \f(CW\*(C`fmtutil.cnf\*(C'\fR file.
 .RE
-.RS 4
+.RS 6
 .RE
-.ie n .IP """(src|run|doc|bin)pattern \f(CIpattern\f(CW""" 4
-.el .IP "\f(CW(src|run|doc|bin)pattern \f(CIpattern\f(CW\fR" 4
+.ie n .IP """(src|run|doc|bin)pattern""\fR \fIpattern" 6
+.el .IP "\f(CW(src|run|doc|bin)pattern\fR \fIpattern\fR" 6
 .IX Item "(src|run|doc|bin)pattern pattern"
 adds a pattern (see below) to the respective list of patterns.
 .SH "PATTERNS"
@@ -234,118 +270,171 @@ Patterns specify which files are to be included into a \f(CW\*(C`tlpobj\*(C'\fR
 expansion time. Patterns are of the form
 .PP
 .Vb 1
-\&        [PREFIX]TYPE PAT
+\&  [PREFIX]TYPE[/ARCH] PAT
 .Ve
 .PP
 where
 .PP
-.Vb 2
-\&        PREFIX = + | +! | !
-\&        TYPE = t | f | d | r
+.Vb 3
+\&  PREFIX = + | +! | !
+\&  TYPE = t | f | d | r
+\&  ARCH = <some arch specificatin>
 .Ve
 .PP
-The meaning of the various pattern types is
-.ie n .IP """f path""" 4
-.el .IP "\f(CWf path\fR" 4
+Simple patterns without \s-1PREFIX\s0 and \s-1ARCH\s0 specification are explained first,
+see below for these extensions.
+.ie n .IP """f ""\fR\fIpath" 4
+.el .IP "\f(CWf \fR\fIpath\fR" 4
 .IX Item "f path"
-includes all files which match \f(CW\*(C`path\*(C'\fR where \fBonly\fR the last component
-of \f(CW\*(C`path\*(C'\fR can contain the usual glob characters * and ? (but no others!).
-.ie n .IP """d path""" 4
-.el .IP "\f(CWd path\fR" 4
+includes all files which match \f(CW\*(C`path\*(C'\fR where \fBonly\fR the last
+component of \f(CW\*(C`path\*(C'\fR can contain the usual glob characters \f(CW\*(C`*\*(C'\fR and
+\&\f(CW\*(C`?\*(C'\fR (but no others!).
+.ie n .IP """d ""\fR\fIpath" 4
+.el .IP "\f(CWd \fR\fIpath\fR" 4
 .IX Item "d path"
 includes all the files in and below the directory specified as \f(CW\*(C`path\*(C'\fR.
-.ie n .IP """t word1 ... wordN worldL""" 4
-.el .IP "\f(CWt word1 ... wordN worldL\fR" 4
+.ie n .IP """t ""\fR\fIword1 ... wordN worldL" 4
+.el .IP "\f(CWt \fR\fIword1 ... wordN worldL\fR" 4
 .IX Item "t word1 ... wordN worldL"
 includes all the files in and below all directories of the form
 .Sp
 .Vb 1
-\&        word1/word2/.../wordN/.../any/dirs/.../wordL/
+\&  word1/word2/.../wordN/.../any/dirs/.../wordL/
 .Ve
 .Sp
 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 \f(CW\*(C`wordL\*(C'\fR
-as another directory.
-.ie n .IP """r regexp""" 4
-.el .IP "\f(CWr regexp\fR" 4
+there can be an arbitrary number of subdirectories, followed by \f(CW\*(C`wordL\*(C'\fR
+as the final directory.  A real life example from \f(CW\*(C`omega.tlpsrc\*(C'\fR:
+.Sp
+.Vb 1
+\&  runpattern t texmf\-dist fonts omega
+.Ve
+.Sp
+matches \f(CW\*(C`texmf\-dist/fonts/**/omega\*(C'\fR, where \f(CW\*(C`**\*(C'\fR matches any number of
+intervening subdirectories, e.g.:
+.Sp
+.Vb 3
+\&  texmf\-dist/fonts/ofm/public/omega
+\&  texmf\-dist/fonts/tfm/public/omega
+\&  texmf\-dist/fonts/type1/public/omega
+.Ve
+.ie n .IP """r""\fR \fIregexp" 4
+.el .IP "\f(CWr\fR \fIregexp\fR" 4
 .IX Item "r regexp"
 includes all files matching the regexp \f(CW\*(C`/^regexp$/\*(C'\fR
-.PP
+.Sh "Special patterns"
+.IX Subsection "Special patterns"
+.IP "\s-1PREFIX\s0" 6
+.IX Item "PREFIX"
+If the \f(CW\*(C`PREFIX\*(C'\fR contains the symbol \f(CW\*(C`!\*(C'\fR the meaning of the pattern is
+reversed, i.e., file matching this pattern are removed from the list
+of included files.
+.Sp
+The prefix \f(CW\*(C`+\*(C'\fR deals with the autogeneration of patterns.
+.IP "Auto generated patterns" 6
+.IX Item "Auto generated patterns"
 In the case that one of the pattern sections is empty or \fBall\fR the provided
 patterns have the prefix \f(CW\*(C`+\*(C'\fR (e.g., \f(CW\*(C`+f ...\*(C'\fR), then the following patterns
 are \fBautomatically\fR added at expansion time (but never written to the
 textual representation):
-.IP "runpattern" 4
+.RS 6
+.ie n .IP """runpattern""" 6
+.el .IP "\f(CWrunpattern\fR" 6
 .IX Item "runpattern"
 for runpatterns of category \f(CW\*(C`Package\*(C'\fR
 .Sp
 .Vb 1
-\&        t texmf\-dist topdir $name
+\&  t texmf\-dist topdir $name
 .Ve
 .Sp
-where \f(CW\*(C`topdir\*(C'\fR is one of: bibtex context dvips fonts makeindex metafont
-metapost mft omega scripts tex vtex.
+where \f(CW\*(C`topdir\*(C'\fR is one of: \f(CW\*(C`bibtex\*(C'\fR, \f(CW\*(C`context\*(C'\fR, \f(CW\*(C`dvips\*(C'\fR, \f(CW\*(C`fonts\*(C'\fR,
+\&\f(CW\*(C`makeindex\*(C'\fR, \f(CW\*(C`metafont\*(C'\fR, \f(CW\*(C`metapost\*(C'\fR, \f(CW\*(C`mft\*(C'\fR, \f(CW\*(C`omega\*(C'\fR, \f(CW\*(C`scripts\*(C'\fR,
+\&\f(CW\*(C`tex\*(C'\fR, \f(CW\*(C`vtex\*(C'\fR.
 .Sp
 For other categories \fBno\fR patterns are automatically added to the 
 list of runpatterns.
-.IP "docpattern" 4
+.ie n .IP """docpattern""" 6
+.el .IP "\f(CWdocpattern\fR" 6
 .IX Item "docpattern"
-for docpattern of category \f(CW\*(C`Package\*(C'\fR
+for \f(CW\*(C`docpattern\*(C'\fR of category \f(CW\*(C`Package\*(C'\fR
 .Sp
 .Vb 1
-\&        t texmf\-dist doc $name
+\&  t texmf\-dist doc $name
 .Ve
 .Sp
-for docpattern of category \f(CW\*(C`Documentation\*(C'\fR
+for \f(CW\*(C`docpattern\*(C'\fR of category \f(CW\*(C`Documentation\*(C'\fR
 .Sp
 .Vb 1
-\&        t texmf\-doc doc $name
+\&  t texmf\-doc doc $name
 .Ve
-.IP "srcpattern" 4
+.ie n .IP """srcpattern""" 6
+.el .IP "\f(CWsrcpattern\fR" 6
 .IX Item "srcpattern"
-for srcpattern of category \f(CW\*(C`Package\*(C'\fR
+for \f(CW\*(C`srcpattern\*(C'\fR of category \f(CW\*(C`Package\*(C'\fR
 .Sp
 .Vb 1
-\&        t texmf\-dist source $name
+\&  t texmf\-dist source $name
 .Ve
 .Sp
-for srcpattern of category \f(CW\*(C`Documentation\*(C'\fR
+for \f(CW\*(C`srcpattern\*(C'\fR of category \f(CW\*(C`Documentation\*(C'\fR
 .Sp
 .Vb 1
-\&        t texmf\-doc source $name
+\&  t texmf\-doc source $name
 .Ve
-.PP
+.RE
+.RS 6
+.Sp
 binpatterns are never automatically added.
-.PP
-If the \f(CW\*(C`PREFIX\*(C'\fR contains the symbol ! the meaning of the pattern is
-reversed, i.e., file matching this pattern are removed from the list
-of included files.
-.Sh "arch expansion"
-.IX Subsection "arch expansion"
-In case the string \f(CW\*(C`${ARCH}\*(C'\fR occurs in one \f(CW\*(C`binpattern\*(C'\fR it is
+.RE
+.IP "special treatment of binpatterns" 6
+.IX Item "special treatment of binpatterns"
+The binpatterns have to deal with all the different architectures. To
+ease the writing of patterns several extensions to the above pattern
+language are allowed:
+.RS 6
+.IP "arch expansion" 6
+.IX Item "arch expansion"
+In case the string \f(CW${\fR\fI\s-1ARCH\s0\fR} occurs in one \f(CW\*(C`binpattern\*(C'\fR it is
 automatically expanded to the respective architecture.
-.Sh "bat/exe/dll for win32"
-.IX Subsection "bat/exe/dll for win32"
-For \f(CW\*(C`binpatterns\*(C'\fR of the form \f(CW\*(C`f bin/win32/foobar\*(C'\fR (i.e., also for a
-binpattern of the form \f(CW\*(C`f bin/${ARCH}/foobar\*(C'\fR) files \fIfoobar.bat\fR,
-\&\fIfoobar.dll\fR, and \fIfoobar.exe\fR are also matched.
-.PP
-The above two properties allows to capture the binaries for all architectures
-in one binpattern
-.PP
+.ie n .IP """bat/exe/dll/texlua"" for win32" 6
+.el .IP "\f(CWbat/exe/dll/texlua\fR for win32" 6
+.IX Item "bat/exe/dll/texlua for win32"
+For \f(CW\*(C`binpattern\*(C'\fRs of the form \f(CW\*(C`f bin/win32/foobar\*(C'\fR (i.e., also for a
+binpattern of the form \f(CW\*(C`f bin/${ARCH}/foobar\*(C'\fR) files \f(CW\*(C`foobar.bat\*(C'\fR,
+\&\f(CW\*(C`foobar.dll\*(C'\fR, \f(CW\*(C`foobar.exe\*(C'\fR, and \f(CW\*(C`foobar.texlua\*(C'\fR are also matched.
+.Sp
+The above two properties allows to capture the binaries for all
+architectures in one binpattern
+.Sp
 .Vb 1
-\&        binpattern f bin/${ARCH}/dvips
+\&  binpattern f bin/${ARCH}/dvips
 .Ve
-.PP
-and would get \fIbin/win32/dvips.exe\fR into the runfiles for arch=win32.
-.PP
-Note that the bat/exe expansion \fBonly\fR works for patterns of the \f(CW\*(C`f\*(C'\fR type!
+.Sp
+and would get \f(CW\*(C`bin/win32/dvips.exe\*(C'\fR into the runfiles for \f(CW\*(C`arch=win32\*(C'\fR.
+.Sp
+Note that the \f(CW\*(C`bat\*(C'\fR/\f(CW\*(C`exe\*(C'\fR expansion \fBonly\fR works for patterns of
+the \f(CW\*(C`f\*(C'\fR type!
+.IP "\s-1ARCH\s0 specification of a pattern" 6
+.IX Item "ARCH specification of a pattern"
+Sometimes some files should be included into the list of binfiles of
+a package only for one architecture. This can be done by specifying 
+the architecture after the pattern specifier using a \f(CW\*(C`/\*(C'\fR:
+.Sp
+.Vb 1
+\&  binpattern f/win32 tlpkg/bin/perl.exe
+.Ve
+.Sp
+will include the file \f(CW\*(C`tlpkg/bin/perl.exe\*(C'\fR only in the binfiles for
+the architecture win32.
+.RE
+.RS 6
+.RE
 .SH "MEMBER ACCESS FUNCTIONS"
 .IX Header "MEMBER ACCESS FUNCTIONS"
 For any of the above \fIkeys\fR a function
 .PP
 .Vb 1
-\&        $tlpsrc\->key
+\&  $tlpsrc\->key
 .Ve
 .PP
 is available, which returns the current value when called without an argument,
@@ -354,27 +443,34 @@ and sets the respective value when called with an argument.
 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 are single scalars. Arguments and return values
 for \f(CW\*(C`depends\*(C'\fR, \f(CW\*(C`executes\*(C'\fR, and the various \f(CW\*(C`patterns\*(C'\fR are lists.
+.PP
+In addition, the \f(CW\*(C`_srcfile\*(C'\fR member refers to the filename for this
+\&\f(CW\*(C`TLPSRC\*(C'\fR object, if set (normally by \f(CW\*(C`from_file\*(C'\fR).
 .SH "OTHER FUNCTIONS"
 .IX Header "OTHER FUNCTIONS"
 The following functions can be called for an \f(CW\*(C`TLPSRC\*(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
-\&        $tlpsrc = TLPSRC\->new ( name => "foobar", shortdesc => "The foobar package" );
+\&  $tlpsrc=TLPSRC\->new(name => "foobar", shortdesc => "The foobar package");
 .Ve
 .ie n .IP """from_file(""filename"")""" 4
 .el .IP "\f(CWfrom_file(``filename'')\fR" 4
 .IX Item "from_file(""filename"")"
-reads a \f(CW\*(C`tlpsrc\*(C'\fR file.
+reads a \f(CW\*(C`tlpsrc\*(C'\fR file from disk.  \f(CW\*(C`filename\*(C'\fR can either be a full path
+(if it's readable, it's used), or just a package identifier such as
+\&\f(CW\*(C`plain\*(C'\fR.  In the latter case, the directory searched is the \f(CW\*(C`tlpsrc\*(C'\fR
+sibling of the \f(CW\*(C`TeXLive\*(C'\fR package directory where \f(CW\*(C`TLPSRC.pm\*(C'\fR was found.
 .Sp
-.Vb 2
-\&        $tlpsrc = new TLPSRC;
-\&        $tlpsrc\->from_file("path/to/the/tlpsrc/file");
+.Vb 3
+\&  $tlpsrc=new TeXLive::TLPSRC;
+\&  $tlpsrc\->from_file("/path/to/the/tlpsrc/somepkg.tlpsrc");
+\&  $tlpsrc\->from_file("somepkg");
 .Ve
 .ie n .IP """writeout""" 4
 .el .IP "\f(CWwriteout\fR" 4
@@ -383,21 +479,21 @@ writes the textual representation of a \f(CW\*(C`TLPSRC\*(C'\fR object to stdout
 filehandle if given:
 .Sp
 .Vb 2
-\&        $tlpsrc\->writeout;
-\&        $tlpsrc\->writeout(\e*FILEHANDLE);
+\&  $tlpsrc\->writeout;
+\&  $tlpsrc\->writeout(\e*FILEHANDLE);
 .Ve
 .ie n .IP """make_tlpobj($tltree)""" 4
 .el .IP "\f(CWmake_tlpobj($tltree)\fR" 4
 .IX Item "make_tlpobj($tltree)"
 creates a \f(CW\*(C`TLPOBJ\*(C'\fR object from a \f(CW\*(C`TLPSRC\*(C'\fR object and a \f(CW\*(C`TLTREE\*(C'\fR object.
 This function does the necessary work to expand the manual data and
-enrich it which the actual content from <$tltree> to a \f(CW\*(C`TLPOBJ\*(C'\fR object.
-.SH "AUTHORS AND COPYRIGHT"
-.IX Header "AUTHORS AND COPYRIGHT"
-This module and its documentation was written by 
-Norbert Preining <\fIpreining@logic.at\fR> for the TeX Live distribution and both
-are licensed under the \s-1GNU\s0 General Public License Version 2 or later.
+enrich it which the actual content from \f(CW$tltree\fR to a \f(CW\*(C`TLPOBJ\*(C'\fR object.
 .SH "SEE ALSO"
 .IX Header "SEE ALSO"
-The modules TeXLive::TLUtils, TeXLive::TLPOBJ, 
+The modules TeXLive::TLConfig, TeXLive::TLUtils, TeXLive::TLPOBJ, 
 TeXLive::TLPDB, TeXLive::TLTREE.
+.SH "AUTHORS AND COPYRIGHT"
+.IX Header "AUTHORS AND COPYRIGHT"
+This script and its documentation were written for the TeX Live
+distribution (<http://tug.org/texlive>) and both are licensed under the
+\&\s-1GNU\s0 General Public License Version 2 or later.