doc

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

3 files changed, 85 insertions, 64 deletions

diff --git a/Master/tlpkg/TeXLive/TLPOBJ.pm b/Master/tlpkg/TeXLive/TLPOBJ.pm
index a4db6d4c9ce..34073b391b3 100644
--- a/Master/tlpkg/TeXLive/TLPOBJ.pm
+++ b/Master/tlpkg/TeXLive/TLPOBJ.pm
@@ -263,7 +263,7 @@ sub _recompute_size {
           $nrivblocks += int($s/$TeXLive::TLConfig::BlockSize);
           $nrivblocks++ if (($s%$TeXLive::TLConfig::BlockSize) > 0);
         } else {
-          printf STDERR "size for $f not defined, strange ...\n";
+        tlwarn("$0: (TLPOBJ::_recompute_size) size of $type $f undefined?!\n");
         }
       }
     }
@@ -458,8 +458,8 @@ sub as_json {
     my %newd;
     $newd{'file'} = $f;
     if (defined($dfd->{$f})) {
-      # TODO should we check that there are actually only "details"
-      # and "language" as key?
+      # "details" and "language" keys now, but more could be added any time.
+      # (Such new keys would have to be added in update_from_catalogue.)
       for my $k (keys %{$dfd->{$f}}) {
         $newd{$k} = $dfd->{$f}->{$k};
       }
@@ -509,7 +509,7 @@ sub replace_reloc_prefix {
   }
   $self->docfiledata(%newdata);
   # if there are bin files they have definitely NOT the
-  # texmf-dist prefix, so we cannot cancel it anyway
+  # texmf-dist prefix, so no reloc to replace
 }
 
 sub cancel_common_texmf_tree {
@@ -855,7 +855,7 @@ sub update_from_catalogue {
       $foo =~ s/^.Date: //;
       # trying to extract the interesting part of a subversion date
       # keyword expansion here, e.g.,
-      # $Date$
+      # <dollar>Date: 2007-08-15 19:43:35 +0100 (Wed, 27 Nov 2019) <dollar>
       # ->2007-08-15 19:43:35 +0100
       $foo =~ s/ \(.*\)( *\$ *)$//;  # maybe nothing after parens
       $self->cataloguedata->{'date'} = $foo;
@@ -1497,26 +1497,38 @@ files describing a self-contained package.
 
 =head1 FILE SPECIFICATION
 
-Please see L<TeXLive::TLPSRC> documentation for the specification. The
-only differences are that the various C<*pattern> keys are invalid, and
-instead there are the respective C<*files> keys described below. Furthermore
-some more I<keys> is allowed: C<revision> which specifies the maximum of
-all last changed revision of files contained in the package, anything
-starting with C<catalogue-> specifying information coming from the
-TeX Catalogue, and C<relocated> taking either 0 or 1 indicating that
-this packages has been relocated, i.e., in the containers the 
-initial C<texmf-dist> directory has been stripped off.
+See L<TeXLive::TLPSRC> documentation for the general syntax and
+specification. The differences are:
+
+=over 4
+
+=item The various C<*pattern> keys are invalid.
+
+=item Instead, there are respective C<*files> keys described below.
+All the C<*files> keys are followed by a list of files in the given
+category, one per line, each line I<indented> by one space.
 
-All these keys have in common that they are followed by a list of files
-I<indented> by one space. They differ only in the first line itself
-(described below).
+=item Several new keys beginning with C<catalogue-> specify information
+automatically taken from the TeX Catalogue.
+
+=item A new key C<revision> is defined (automatically computed),
+which specifies the maximum of all the last-changed revisions of files
+contained in the package, plus possible other changes. By default,
+Catalogue-only changes do not change the revision.
+
+=item A new key C<relocated>, either 0 or 1, which indicates that this
+packages has been relocated, i.e., in the containers the initial
+C<texmf-dist> directory has been stripped off and replaced with static
+string C<RELOC>.
+
+=back
 
 =over 4
 
 =item C<srcfiles>, C<runfiles>, C<binfiles>, C<docfiles>
-each of these items contains addition the sum of sizes of the
-single files (in number of C<TeXLive::TLConfig::BlockSize> blocks, which
-is currently 4k).
+each of these items contains addition the sum of sizes of the single
+files (in number of C<TeXLive::TLConfig::BlockSize> blocks,currently
+4k).
 
   srcfiles size=NNNNNN
   runfiles size=NNNNNN
@@ -1528,25 +1540,26 @@ above:
 
   docfiles size=NNNNNN
 
-But the lines listing the files are allowed to have additional tags:
+But the lines listing the files are allowed to have additional tags,
+which come from the TeX Catalogue.
 
   /------- excerpt from achemso.tlpobj
   |...
-  |docfiles size=1702468
-  | texmf-dist/doc/latex/aeguill/README details="Package Readme"
+  |docfiles size=220
   | texmf-dist/doc/latex/achemso/achemso.pdf details="Package documentation" language="en"
   |...
 
-Currently only the tags C<details> and C<language> are allowed. These
+Currently only the tags C<details> and C<language> are supported. These
 additional information can be accessed via the C<docfiledata> function
 returning a hash with the respective files (including path) as key.
 
 =item C<binfiles>
 
-Since C<binfiles> are different for the different architectures one
-C<tlpobj> file can contain C<binfiles> lines for different
-architectures. The architecture is specified on the C<binfiles> using
-the C<arch=>I<XXX> tag. Thus, C<binfiles> lines look like
+Since C<binfiles> can be different for different architectures, a single
+C<tlpobj> file can, and typically does, contain C<binfiles> lines for
+all available architectures. The architecture is specified on the
+C<binfiles> using the C<arch=>I<XXX> tag. Thus, C<binfiles> lines look
+like
 
   binfiles arch=XXXX size=NNNNN
 
@@ -1557,28 +1570,26 @@ with C<|> characters inserted to show the indentation:
 
   |name dvipsk
   |category TLCore
-  |revision 4427
-  |docfiles size=959434
+  |revision 52851
+  |docfiles size=285
   | texmf-dist/doc/dvips/dvips.html
   | ...
-  |runfiles size=1702468
+  |runfiles size=93
   | texmf-dist/dvips/base/color.pro
   | ...
   | texmf-dist/scripts/pkfix/pkfix.pl
-  |binfiles arch=i386-solaris size=329700
+  |binfiles arch=i386-solaris size=87
   | bin/i386-solaris/afm2tfm
   | bin/i386-solaris/dvips
-  | bin/i386-solaris/pkfix
-  |binfiles arch=win32 size=161280
+  |binfiles arch=win32 size=51
   | bin/win32/afm2tfm.exe
   | bin/win32/dvips.exe
-  | bin/win32/pkfix.exe
   |...
 
 =head1 PACKAGE VARIABLES
 
-TeXLive::TLPOBJ has one package wide variable which is C<containerdir> where
-generated container files are saved (if not otherwise specified.
+TeXLive::TLPOBJ has one package-wide variable, C<containerdir>, which is
+where generated container files are saved (if not otherwise specified).
 
   TeXLive::TLPOBJ->containerdir("path/to/container/dir");
 
@@ -1638,7 +1649,7 @@ activated for that install medium.
 
 =head1 OTHER FUNCTIONS
 
-The following functions can be called for an C<TLPOBJ> object:
+The following functions can be called for a C<TLPOBJ> object:
 
 =over 4
 
@@ -1844,10 +1855,9 @@ lines for language.dat.lua that can be generated from the tlpobj.
 
 =head1 SEE ALSO
 
-The modules L<TeXLive::TLConfig>, L<TeXLive::TLCrypto>,
-L<TeXLive::TLUtils>, L<TeXLive::TLPSRC>, L<TeXLive::TLPDB>,
-L<TeXLive::TLTREE>, L<TeXLive::TeXCatalogue>, etc., and the
-documentation in the repository: C<Master/tlpkg/doc/>.
+The other modules in C<Master/tlpkg/TeXLive/> (L<TeXLive::TLConfig> and
+the rest), and the scripts in C<Master/tlpg/bin/> (especially
+C<tl-update-tlpdb>), the documentation in C<Master/tlpkg/doc/>, etc.
 
 =head1 AUTHORS AND COPYRIGHT
 
diff --git a/Master/tlpkg/TeXLive/TLUtils.pm b/Master/tlpkg/TeXLive/TLUtils.pm
index 161259d4112..f2a5b1ce093 100644
--- a/Master/tlpkg/TeXLive/TLUtils.pm
+++ b/Master/tlpkg/TeXLive/TLUtils.pm
@@ -14,7 +14,7 @@ sub module_revision { return $_modulerevision; }
 
 =head1 NAME
 
-C<TeXLive::TLUtils> -- utilities used in TeX Live infrastructure
+C<TeXLive::TLUtils> - utilities used in TeX Live infrastructure
 
 =head1 SYNOPSIS
 
@@ -3477,6 +3477,7 @@ sub debug_hash {
   my @items = ();
   for my $key (sort keys %hash) {
     my $val = $hash{$key};
+    $val = ".undef" if ! defined $val;
     $key =~ s/\n/\\n/g;
     $val =~ s/\n/\\n/g;
     push (@items, "$key:$val");
@@ -4038,17 +4039,20 @@ sub download_to_temp_or_file {
   return;
 }
 
-# compare_tlpobjs 
-# returns a hash
-#   $ret{'revision'} = "leftRev:rightRev"     if revision differ
-#   $ret{'removed'} = \[ list of files removed from A to B ]
-#   $ret{'added'} = \[ list of files added from A to B ]
-#
+
+=item C<< compare_tlpobjs($tlpA, $tlpB) >>
+
+Compare the two passed L<TLPOBJ> objects.  Returns a hash:
+
+  $ret{'revision'}  = "revA:revB" # if revisions differ
+  $ret{'removed'}   = \[ list of files removed from A to B ]
+  $ret{'added'}     = \[ list of files added from A to B ]
+
+=cut
+
 sub compare_tlpobjs {
   my ($tlpA, $tlpB) = @_;
   my %ret;
-  my @rem;
-  my @add;
 
   my $rA = $tlpA->revision;
   my $rB = $tlpB->revision;
@@ -4068,20 +4072,27 @@ sub compare_tlpobjs {
   for my $f (@fA) { $removed{$f} = 1; }
   for my $f (@fB) { delete($removed{$f}); $added{$f} = 1; }
   for my $f (@fA) { delete($added{$f}); }
-  @rem = sort keys %removed;
-  @add = sort keys %added;
+  my @rem = sort keys %removed;
+  my @add = sort keys %added;
   $ret{'removed'} = \@rem if @rem;
   $ret{'added'} = \@add if @add;
+
   return %ret;
 }
 
-#
-# compare_tlpdbs
-# return several hashes
-# @{$ret{'removed_packages'}} = list of removed packages from A to B
-# @{$ret{'added_packages'}} = list of added packages from A to B
-# $ret{'different_packages'}->{$package} = output of compare_tlpobjs
-#
+
+=item C<< compare_tlpdbs($tlpdbA, $tlpdbB, @more_ignored_pkgs) >>
+
+Compare the two passed L<TLPDB> objects, ignoring the packages
+C<00texlive.installer>, C<00texlive.image>, and any passed
+C<@more_ignore_pkgs>. Returns a hash:
+
+  $ret{'removed_packages'} = \[ list of removed packages from A to B ]
+  $ret{'added_packages'}   = \[ list of added packages from A to B ]
+  $ret{'different_packages'}->{$package} = output of compare_tlpobjs
+
+=cut
+
 sub compare_tlpdbs {
   my ($tlpdbA, $tlpdbB, @add_ignored_packs) = @_;
   my @ignored_packs = qw/00texlive.installer 00texlive.image/;
@@ -4658,9 +4669,9 @@ __END__
 
 =head1 SEE ALSO
 
-The modules L<TeXLive::TLConfig>, L<TeXLive::TLCrypto>,
-L<TeXLive::TLDownload>, L<TeXLive::TLWinGoo>, etc., and the
-documentation in the repository: C<Master/tlpkg/doc/>.
+The other modules in C<Master/tlpkg/TeXLive/> (L<TeXLive::TLConfig> and
+the rest), and the scripts in C<Master/tlpg/bin/> (especially
+C<tl-update-tlpdb>), the documentation in C<Master/tlpkg/doc/>, etc.
 
 =head1 AUTHORS AND COPYRIGHT
 
diff --git a/Master/tlpkg/bin/tl-update-containers b/Master/tlpkg/bin/tl-update-containers
index 4cb41812038..f1d22b1eb39 100755
--- a/Master/tlpkg/bin/tl-update-containers
+++ b/Master/tlpkg/bin/tl-update-containers
@@ -66,7 +66,7 @@ sub main {
   # check that we have a target db.
   if (! $opt_recreate && ! -r "$opt_location/tlpkg/texlive.tlpdb") {
     die "$0: Cannot load tlpdb from output directory $opt_location;\n"
-        . "  specify --recreate if you want to populate anew.\n";
+        . "  specify --recreate if you need to populate anew.\n";
   }
 
   # get source db, same hierarchy from which we are being run.