doc fixes

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

7 files changed, 134 insertions, 117 deletions

diff --git a/Master/texmf/scripts/texlive/tlmgr.pl b/Master/texmf/scripts/texlive/tlmgr.pl
index e9b0bcf27b1..5230453bd4d 100755
--- a/Master/texmf/scripts/texlive/tlmgr.pl
+++ b/Master/texmf/scripts/texlive/tlmgr.pl
@@ -1012,7 +1012,7 @@ sub action_update {
     my $tlp = $localtlpdb->get_package($pkg);
     if (!defined($tlp)) {
       if ($forcermpkgs{$pkg}) {
-        info("not reinstalling forcibly removed package $pkg ($forcermpkgs{$pkg})\n");
+        info("skipping forcibly removed package $pkg ($forcermpkgs{$pkg})\n");
         next;
       } elsif ($newpkgs{$pkg}) {
         # do nothing here, it will be reported below!
@@ -1151,7 +1151,7 @@ sub action_update {
     tlwarn("If you want to install from the Internet for this one time only, run\n");
     tlwarn("  tlmgr -location $TeXLiveURL\n");
     tlwarn("\nIf you want to change the default for all future updates, run\n");
-    tlwarn("   tlmgr option location $TeXLiveURL\n\n");
+    tlwarn("  tlmgr option location $TeXLiveURL\n\n");
   }
   return(\%ret);
 }
@@ -1976,10 +1976,10 @@ language code.
 =item B<-package-logfile> I<file>
 
 B<tlmgr> logs all package actions (install, remove, update, failed
-updates and failed restores) to a separate log file, by default
+updates, failed restores) to a separate log file, by default
 C<TEXMFSYSVAR/web2c/tlmgr.log>. This option allows you to select a
-different file for that.  This is different from normal
-logging; for that, see the option C<-v> below, and TeXLive::TLUtils.
+different file for that.  This is separate from normal logging; for
+that, see the option C<-v> below, and TeXLive::TLUtils.
 
 =back
 
@@ -2017,11 +2017,11 @@ all packages that the given I<pkg>s are dependent on, also.  Options:
 =item B<--reinstall>
 
 Reinstall a package (including dependencies for collections) even if it
-seems to be already installed. Can be used to recover from accidently 
-removed files of a package.
+seems to be already installed (i.e, is present in the TLPDB).  This is
+useful to recover from accidental removal of files in the hierarchy.
 
-Note that when re-installing packages not all dependencies are reinstalled,
-only dependencies on normal packages (not of category Scheme or Collection).
+When re-installing, only dependencies on normal packages are followed
+(not those of category Scheme or Collection).
 
 =item B<--no-depends>
 
diff --git a/Master/tlpkg/TeXLive/TLPSRC.pm b/Master/tlpkg/TeXLive/TLPSRC.pm
index 2240c374e96..521c75124e1 100644
--- a/Master/tlpkg/TeXLive/TLPSRC.pm
+++ b/Master/tlpkg/TeXLive/TLPSRC.pm
@@ -513,7 +513,7 @@ __END__
 
 =head1 NAME
 
-C<TeXLive::TLPSRC> -- TeX Live Package Source access module
+C<TeXLive::TLPSRC> -- TeX Live Package Source module
 
 =head1 SYNOPSIS
 
@@ -527,38 +527,43 @@ C<TeXLive::TLPSRC> -- TeX Live Package Source access module
 
 =head1 DESCRIPTION
 
-The C<TeXLive::TLPSRC> module provide access to TeX Live Package Source
-files, which contain all the information which cannot be automatically
-derived from the files in the TeX Live subversion repository.  In other
-words, these files are hand-maintained.
+The C<TeXLive::TLPSRC> module handles TeX Live Package Source
+(C<.tlpsrc>) files, which contain all (and only) the information which
+cannot be automatically derived from other sources, notably the TeX Live
+directory tree and the TeX Catalogue.  In other words, C<.tlpsrc> files
+are hand-maintained.
 
 =head1 FILE SPECIFICATION
 
-A C<tlpsrc> file has to consist of non-indented lines of the form:
+A C<tlpsrc> file consists of lines of the form:
 
-  I<key value>
+I<key> I<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>.
 
-Continuation lines are supported with a trailing backslash.  That is, if
+Continuation lines are supported via a trailing backslash.  That is, if
 the C<.tlpsrc> file contains two physical lines like this:
   
   foo\
   bar
 
 they are concatenated into C<foobar>.  The newline is removed; no other
-whitespace is added or removed, so typically the continuation line would
-start with one or more spaces.
+whitespace is added or removed, so typically the continuation line
+starts with one or more spaces.
 
-The interpretation of the respective I<values> are:
+Comment lines begin with a # and continue to the end of the line.
+
+Blank lines are ignored.
+
+The meaning of the I<key>s are:
 
 =over 4
 
 =item C<name>
 
-identifies the package, C<value> must consist only of C<[-_a-zA-Z0-9]>,
+identifies the package; C<value> must consist only of C<[-_a-zA-Z0-9]>,
 i.e., with what Perl considers a C<\w>. 
 
 There are three exceptions to this rule:
@@ -567,42 +572,42 @@ There are three exceptions to this rule:
 
 =item B<name.ARCH>
 
-where B<ARCH> 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.
+where B<ARCH> is a supported architecture-os combination.  This has two
+uses.  First, packages are split (automatically) into containers for the
+different architectures to make possible installations including only
+the necessary binaries.  Second, one can add 'one-arch-only' packages,
+often used to deal with Windows peculiarities.
 
-=item B<00texliveSOMETHING>
+=item B<00texlive>I<something>
 
-these packages are used for internal operation
-and storage containers for settings. Besides being the only packages starting
-with B<00texlive> they will never be split into separate arch-packages, and
-containers are never generated for these packages.
+These packages are used for internal operation and storage containers
+for settings.  I<00texlive> packages are never be split into separate
+arch-packages, and containers are never generated for these packages.
+Examples: C<00texlive-installation.config>, C<00texlive.config>.
 
-=item B<texliveSOME.THING>
+=item B<texlive>I<some.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 CTAN.
+(notice 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 will never clash
+with any package that can possibly appear on CTAN.  The only such
+package currently is C<texlive.infra>, which contains L<tlmgr> and other
+basic infrastructure functionality.
 
 =back
 
 =item C<category>
 
-identifies the category into which this package belongs. Possible categories
-are defined in C<TeXLive::TLConfig>, but are currently
-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.
+identifies the category into which this package belongs. This determines
+the default patterns applied.  Possible categories are defined in
+C<TeXLive::TLConfig>, currently C<Collection>, C<Scheme>, C<TLCore>,
+C<Documentation>, C<Package>.  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.
+identifies the name under which this package can be found in the TeX
+Catalogue.
 
 =item C<shortdesc>
 
@@ -612,16 +617,19 @@ 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.
+gives a long description of the package. Susequent entries are
+concatenated into 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.
+gives the list of dependencies, which are just other package names.
+All the C<depend> lines contribute to the dependencies of the package.
+Examples:
+  
+  depend cm
+  depend plain
+  depend collection-basicbin
 
 =item C<execute>
 
@@ -639,23 +647,22 @@ enables the font map file I<font>C<.map> in the C<updmap.cfg> file.
 enables the font map file I<font>C<.map> for Mixed mode in the
 C<updmap.cfg> file.
 
-=item C<execute AddHyphen name=TEXLANG file=FILE [other vars]>
+=item C<execute AddHyphen name=I<texlang> file=I<file> [I<var>...]>
 
-activates the hyphenation pattern with name TEXLANG and load the file FILE
-for that language. More variables can be given, currently: B<lefthyphenmin>,
-B<righthyphenmin> (both integers), and B<synonyms> (a list of alias names
-for that hyphenation).
+activates the hyphenation pattern with name I<texlang> and load the file
+I<file> for that language.  The additional variables I<var> are:
+C<lefthyphenmin>, C<righthyphenmin> (both integers), and C<synonyms> (a
+comma-separated list of alias names for that hyphenation).
 
-=item C<execute BuildFormat FMTCFG>
+=item C<execute BuildFormat> I<format>
 
-activates all the formats present in C<Master/texmf/fmtutil/format.FMTCFG.cnf>
-in the generated C<fmtutil.cnf> file.
+build the format I<format>, as specified in the C<fmtutil.cnf> file.
 
 =back
 
 =item C<(src|run|doc|bin)pattern> I<pattern>
 
-adds a pattern (see below) to the respective list of patterns.
+adds a pattern (next section) to the respective list of patterns.
 
 =back
 
@@ -672,28 +679,28 @@ where
   TYPE = t | f | d | r
   ARCHSPEC = <list of architectures separated by comma>
 
-Simple patterns without PREFIX and ARCHSPEC specification are explained first,
-see below for these extensions.
+Simple patterns without PREFIX and ARCHSPEC specifications are explained
+first.
 
 =over 4
 
-=item C<f >I<path>
+=item C<f> I<path>
 
-includes all files which match C<path> where B<only> the last
-component of C<path> can contain the usual glob characters C<*> and
-C<?> (but no others!).
+includes all files which match C<path> where B<only> the last component
+of C<path> can contain the usual glob characters C<*> and C<?> (but no
+others!).
 
-=item C<d >I<path>
+=item C<d> I<path>
 
 includes all the files in and below the directory specified as C<path>.
 
-=item C<t >I<word1 ... wordN worldL>
+=item C<t> I<word1 ... wordN wordL>
 
 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
+i.e., all the first words but the last form the prefix of the path, then
 there can be an arbitrary number of subdirectories, followed by C<wordL>
 as the final directory.  A real life example from C<omega.tlpsrc>:
 
@@ -719,8 +726,8 @@ includes all files matching the regexp C</^regexp$/>
 =item PREFIX
 
 If the C<PREFIX> contains the symbol C<!> the meaning of the pattern is
-reversed, i.e., file matching this pattern are removed from the list
-of included files.
+reversed, i.e., files matching this pattern are removed from the list of
+included files.
 
 The prefix C<+> means to append to the list of automatically synthesized
 patterns, instead of replacing them.
@@ -735,18 +742,17 @@ so that this subdirectory of the C<tufte-latex> package that happens to
 be named `graphics' is not mistakenly included in the C<graphics>
 package.
 
-=item Auto generated patterns
+=item Auto-generated patterns
 
 If a given pattern section is empty or B<all> the provided patterns have
 the prefix C<+> (e.g., C<+f ...>), then the following patterns, listed
-by type are I<automatically> added at expansion time (but never written
-to the textual representation):
+by type are I<automatically> added at expansion time:
 
 =over 4
 
 =item C<runpattern>
 
-for runpatterns of category C<Package>
+for category C<Package>:
 
   t texmf-dist topdir $name
 
@@ -755,50 +761,51 @@ C<makeindex>, C<metafont>, C<metapost>, C<mft>, C<omega>, C<scripts>,
 C<tex>, C<vtex>.
 
 For other categories B<no> patterns are automatically added to the 
-list of runpatterns.
+list of C<runpattern>s.
 
 =item C<docpattern>
 
-for C<docpattern> of category C<Package>
+for category C<Package>:
 
   t texmf-dist doc $name
 
-for C<docpattern> of category C<Documentation>
+for category C<Documentation>:
 
   t texmf-doc doc $name
 
 =item C<srcpattern>
 
-for C<srcpattern> of category C<Package>
+for category C<Package>:
 
   t texmf-dist source $name
 
-for C<srcpattern> of category C<Documentation>
+for category C<Documentation>:
 
   t texmf-doc source $name
 
-=back
+=item C<binpattern>
 
-binpatterns are never automatically added.
+No C<binpattern>s are ever automatically added.
 
-=item special treatment of binpatterns
+=back
+
+=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:
+ease the writing of patterns, we have the following:
 
 =over 4
 
-=item arch expansion
+=item Architecture expansion
 
 In case the string C<${>I<ARCH>} occurs in one C<binpattern> it is
 automatically expanded to the respective architecture.
 
-=item C<bat/exe/dll/texlua> for win32
+=item C<bat/exe/dll/texlua> for Windows
 
-C<binpattern>s of the form C<f bin/win32/foobar> or
-C<f bin/${ARCH}/foobar>) also match the files C<foobar.bat>,
-C<foobar.cmd>, C<foobar.dll>, C<foobar.exe>, and C<foobar.texlua>.
+C<binpattern>s that match Windows, e.g., C<f bin/win32/foobar> or C<f
+bin/${ARCH}/foobar>, also match the files C<foobar.bat>, C<foobar.cmd>,
+C<foobar.dll>, C<foobar.exe>, and C<foobar.texlua>.
 
 The above two properties allows to capture the binaries for all
 architectures in one binpattern
@@ -807,33 +814,33 @@ architectures in one binpattern
 
 and would get C<bin/win32/dvips.exe> into the runfiles for C<arch=win32>.
 
-Note that the C<bat>/C<exe> expansion B<only> works for patterns of
-the C<f> type!
+This C<bat>/C<exe>/etc. expansion I<only> works for patterns of the C<f>
+type.
 
 =item ARCHSPEC specification of a pattern
 
-Sometimes some files should be included into the list of binfiles of
-a package only for some architectures, or for all but some architectures. 
-This can be done by specifying the list of architectures for which this 
+Sometimes files should be included into the list of binfiles of a
+package only for some architectures, or for all but some architectures.
+This can be done by specifying the list of architectures for which this
 pattern should be matched after the pattern specifier using a C</>:
 
   binpattern f/win32 tlpkg/bin/perl.exe
 
 will include the file C<tlpkg/bin/perl.exe> only in the binfiles for
-the architecture win32. Another example
+the architecture C<win32>. Another example:
 
   binpattern f/arch1,arch2,arch3 path/$ARCH/foo/bar
 
-will only try to match this pattern for arch1, arch2, and arch3.
+This will only try to match this pattern for arch1, arch2, and arch3.
 
-Normally, a binpattern is matched against all possible architectures. If you
-want to exclude some architectures, instead of listing all the ones you want
-to include as above, you can prefix the list of architectures with a ! and
-these architectures will not be tested. Example:
+Normally, a binpattern is matched against all possible architectures. If
+you want to exclude some architectures, instead of listing all the ones
+you want to include as above, you can prefix the list of architectures
+with a ! and these architectures will not be tested. Example:
 
-  binpattern f/!arch1,arch2,arch3 path/$ARCH/foo/bar
+  binpattern f/!arch1,arch2 path/$ARCH/foo/bar
 
-will be matched against all architectures I<but> arch1, arch2, and arch3.
+will be matched against all architectures I<except> arch1 and arch2.
 
 =back
 
@@ -842,7 +849,7 @@ will be matched against all architectures I<but> arch1, arch2, and arch3.
 
 =head1 MEMBER ACCESS FUNCTIONS
 
-For any of the above I<keys> a function
+For any of the above I<key>s a function
 
   $tlpsrc->key
 
@@ -858,7 +865,7 @@ C<TLPSRC> object, if set (normally by C<from_file>).
 
 =head1 OTHER FUNCTIONS
 
-The following functions can be called for an C<TLPSRC> object:
+The following functions can be called for a C<TLPSRC> object:
 
 =over 4
 
@@ -868,7 +875,8 @@ The constructor C<new> 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");
+  $tlpsrc = TLPSRC->new (name => "foobar",
+                         shortdesc => "The foobar package");
 
 =item C<from_file("filename")>
 
@@ -902,6 +910,8 @@ enrich it which the actual content from C<$tltree> to a C<TLPOBJ> object.
 The modules L<TeXLive::TLConfig>, L<TeXLive::TLUtils>, L<TeXLive::TLPOBJ>, 
 L<TeXLive::TLPDB>, L<TeXLive::TLTREE>.
 
+The programs L<tlpsrc2tlpdb> and L<tlpsrc2tlpobj>.
+
 =head1 AUTHORS AND COPYRIGHT
 
 This script and its documentation were written for the TeX Live
diff --git a/Master/tlpkg/TeXLive/TLTREE.pm b/Master/tlpkg/TeXLive/TLTREE.pm
index ff5ae263d70..b87625c702e 100644
--- a/Master/tlpkg/TeXLive/TLTREE.pm
+++ b/Master/tlpkg/TeXLive/TLTREE.pm
@@ -29,7 +29,8 @@ sub new {
 
 sub init_from_svn {
   my $self = shift;
-  die("Undefined svn root!") if (!defined($self->{'svnroot'}));
+  die "Undefined svn root" if !defined($self->{'svnroot'});
+  ddebug("initializing from svn tree $self->{'svnroot'}\n");
   my @lines = `cd $self->{'svnroot'} && svn status -v`;
   $self->_initialize_lines(@lines);
 }
diff --git a/Master/tlpkg/bin/tl-update-tlnet b/Master/tlpkg/bin/tl-update-tlnet
index 5d9074ce4b8..1b636902944 100755
--- a/Master/tlpkg/bin/tl-update-tlnet
+++ b/Master/tlpkg/bin/tl-update-tlnet
@@ -10,10 +10,12 @@ unset CDPATH
 unset LS_COLORS
 
 chicken=false
+critical=
 yyyy=2008
 
 while test $# -gt 0; do
   case $1 in
+  --critical) critical=--all;;
   --dry-run|-n) chicken=true;;
   --master) shift; Master=$1;;
   --testlocation) shift; tlwebtrybase=$1;;
@@ -55,7 +57,7 @@ echo "$0: Updating $tlwebtry in cow-shell..."
 cd $tlwebtry
 cow-shell <<END_COW
 echo "$0: Running tl-update-containers..."
-$Master/tlpkg/bin/tl-update-containers -location $tlwebtry
+$Master/tlpkg/bin/tl-update-containers -location $tlwebtry $critical
 
 # It is scary, but I guess we should update the installer package every
 # day, partly for the sake of doc.html and partly so it actually gets
diff --git a/Master/tlpkg/bin/tlpsrc2tlpdb b/Master/tlpkg/bin/tlpsrc2tlpdb
index 75490bc1aa9..4d7960eeb1d 100755
--- a/Master/tlpkg/bin/tlpsrc2tlpdb
+++ b/Master/tlpkg/bin/tlpsrc2tlpdb
@@ -183,13 +183,14 @@ Use find instead of svn -status to create the list of files.
 
 =back
 
-The standard options C<-help> and C<-debug> are also accepted.
-See the tlpfiles documentation for details.
+The standard options B<-q>, B<-v>, and B<-logfile>=I<file> are also
+accepted; see the C<process_logging_options> function in
+L<TeXLive::TLUtils> for details.
 
 =head1 DESCRIPTION
 
 B<tlpsrc2tlpdb> converts TeX Live source package files (tlpsrc) files into a
-TeX Live package database (tlpdb)
+TeX Live package database (tlpdb).
 
 If a TeX Catalogue hierarchy is specified, additional information from
 the catalogue are merged into the database (see L<TeXLive::TLPOBJ> for
diff --git a/Master/tlpkg/bin/tlpsrc2tlpobj b/Master/tlpkg/bin/tlpsrc2tlpobj
index 565c911bcc4..3135dafd243 100755
--- a/Master/tlpkg/bin/tlpsrc2tlpobj
+++ b/Master/tlpkg/bin/tlpsrc2tlpobj
@@ -101,16 +101,16 @@ Specifies the location where tlpobj files are created; default C<./tlpobj>.
 
 =back
 
-The standard options C<-help> and The standard options B<-q>, B<-v>, and
-B<-logfile>=I<file> are also accepted; see the
-C<process_logging_options> function in L<TeXLive::TLUtils> for details.
+The standard options B<-q>, B<-v>, and B<-logfile>=I<file> are also
+accepted; see the C<process_logging_options> function in
+L<TeXLive::TLUtils> for details.
 
 =head1 DESCRIPTION
 
 B<tlpsrc2tlpobj> converts TeX Live Package Source files (tlpsrc) into 
 TeX Live Package Object files (tlpobj).  The process and the file
-formats are described in various separate documents in the C<tlpkg/doc>
-directory.
+formats are described elsewhere.  See L<TeXLive::TLPSRC> and
+L<TeXLive::TLPOBJ>.
 
 =head1 AUTHORS AND COPYRIGHT
 
diff --git a/Master/tlpkg/tlpsrc/latexmk b/Master/tlpkg/tlpsrc/latexmk
new file mode 100644
index 00000000000..74be8b1e4a5
--- /dev/null
+++ b/Master/tlpkg/tlpsrc/latexmk
@@ -0,0 +1,3 @@
+name latexmk
+category Package
+binpattern f bin/${ARCH}/latexmk