doc fixes

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

1 files changed, 162 insertions, 55 deletions

diff --git a/Master/texmf/scripts/texlive/tlmgr2.pl b/Master/texmf/scripts/texlive/tlmgr2.pl
index 2f1759ef9e2..2f55531f745 100755
--- a/Master/texmf/scripts/texlive/tlmgr2.pl
+++ b/Master/texmf/scripts/texlive/tlmgr2.pl
@@ -70,7 +70,7 @@ our $location;     # location from which the new packages come
 our $localtlpdb;   # local installation which we are munging
 my %options;       # TL options from local tlpdb
 
-# flags for machine readable form
+# flags for machine-readable form
 our $FLAG_REMOVE = "d";
 our $FLAG_FORCIBLE_REMOVED = "f";
 our $FLAG_UPDATE = "u";
@@ -82,13 +82,13 @@ $::gui_mode = 0;
 $::machinereadable = 0;
 
 my %globaloptions = (
-  "location" => "=s",
   "gui" => 1,
   "gui-lang" => "=s",
-  "package-logfiles" => "=s",
+  "location" => "=s",
   "machine-readable" => 1,
-  "version" => 1,
+  "package-logfiles" => "=s",
   "pause" => 1,
+  "version" => 1,
   "help|h|?" => 1);
 
 my %actionoptions = (
@@ -211,7 +211,13 @@ if ($action =~ /^(paper|xdvi|pdftex|dvips|dvipdfmx?|context)$/) {
   unshift(@ARGV, $action);
   $action = "paper";
 }
-  
+
+# --machine-readable is only supported by update.
+# 
+if ($::machinereadable && $action ne "update") {
+  tlwarn("tlmgr: --machine-readable output not supported for $action\n");
+}
+
 # check on supported arguments
 #
 my %suppargs;
@@ -396,6 +402,11 @@ sub handle_ret_hash {
   }
 
   if (exists $ret{'map'}) {
+    # We run updmap-sys instead of calling our create_updmap() function
+    # (as we do for formats and languages), because many users run
+    # updmap themselves (not using our local cfg feature), since that's
+    # been the documented way to add fonts for many years.  If we called
+    # create_updmap, such user maps would be lost.
     foreach my $m (@{$ret{'map'}}) {
       my $cmd = "updmap-sys --nomkmap --nohash --$m";
       info("running $cmd\n");
@@ -565,8 +576,6 @@ sub action_remove {
   if ($opts{"gui"}) {
     action_gui("remove");
   }
-  tlwarn("machine-readable output not supported for remove\n") 
-    if $::machinereadble;
   # we do the following:
   # - (not implemented) order collections such that those depending on
   #   other collections are first removed, and then those which only
@@ -712,8 +721,6 @@ sub action_remove {
 sub action_paper {
   my %ret = ();
   action_gui("config") if $opts{"gui"};
-  tlwarn("machine-readable output not supported for paper\n") 
-    if $::machinereadble;
 
   init_local_db();
   chomp(my $texmfsysconfig = `kpsewhich -var-value=TEXMFSYSCONFIG`);
@@ -762,8 +769,6 @@ sub action_show {
   if ($opts{"gui"}) {
     action_gui("config");
   }
-  tlwarn("machine-readable output not supported for show\n") 
-    if $::machinereadble;
   init_local_db();
   my $tlmediatlpdb;
   foreach my $pkg (@ARGV) {
@@ -845,8 +850,6 @@ sub action_show {
 #
 sub action_symlinks {
   my %ret;
-  tlwarn("machine-readable output not supported for search\n") 
-    if $::machinereadble;
   my $what = shift @ARGV;
   if (!defined($what) || ($what !~ m/^(add|remove)$/i)) {
     tlwarn("action symlinks needs one argument, either add or remove\n");
@@ -870,8 +873,6 @@ sub action_symlinks {
 #
 sub action_search {
   my %ret;
-  tlwarn("machine-readable output not supported for search\n") 
-    if $::machinereadble;
   my $r = shift @ARGV;
   my $ret = "";
   my $tlpdb;
@@ -916,8 +917,6 @@ sub action_restore {
   #   lists all revisions of pkg
   # tlmgr restore --backupdir dir pkg rev
   #   restores pkg to revision rev
-  tlwarn("machine-readable output not supported for restore\n") 
-    if $::machinereadble;
   my %ret;
   # check the backup dir argument
   if ($opts{"backupdir"}) {
@@ -1010,8 +1009,6 @@ sub action_restore {
 }
 
 sub action_backup {
-  tlwarn("machine-readable output not supported for backup\n") 
-    if $::machinereadble;
   init_local_db(1);
   # --clean argument
   # can be either -1 ... don't clean
@@ -1573,7 +1570,7 @@ sub action_update {
   print "total-bytes\t$sizes{'__TOTAL__'}\n" if $::machinereadable;
   print "end-of-header\n" if $::machinereadable;
 
-  # print out deferred machine readable lines after the header
+  # print deferred machine-readable lines after the header
   for (@addlines) { print; }
 
   #
@@ -1792,8 +1789,6 @@ sub action_install {
   if ($opts{"gui"}) {
     action_gui("install");
   }
-  tlwarn("machine-readable output not supported for install\n") 
-    if $::machinereadble;
   init_local_db(1);
   # initialize the TLMedia from $location
   $opts{"no-depends"} = 1 if $opts{"no-depends-at-all"};
@@ -1852,8 +1847,6 @@ sub action_install {
 }
 
 sub action_list {
-  tlwarn("machine-readable output not supported for list\n") 
-    if $::machinereadble;
   init_local_db();
   # make sure that the @ARGV hash is not changed in case we switch to 
   # show mode
@@ -1890,12 +1883,13 @@ sub action_list {
   return;
 }
 
+
+#  OPTION
+# 
 sub action_option {
   if ($opts{"gui"}) {
     action_gui("config");
   }
-  tlwarn("machine-readable output not supported for option\n") 
-    if $::machinereadble;
   my $what = shift @ARGV;
   $what = "show" unless defined($what);
   init_local_db();
@@ -2042,8 +2036,6 @@ sub action_arch {
   if ($opts{"gui"}) {
     action_gui("arch");
   }
-  tlwarn("machine-readable output not supported for arch\n") 
-    if $::machinereadble;
   my %ret;
   my $what = shift @ARGV;
   init_local_db(1);
@@ -2127,8 +2119,6 @@ sub action_generate {
   my $dest = defined($opts{"dest"}) ? $opts{"dest"} : "";
   my $localconf = defined($opts{"localcfg"}) ? $opts{"localcfg"} : "";
   my $what = shift @ARGV;
-  tlwarn("machine-readable output not supported for generate\n") 
-    if $::machinereadble;
   init_local_db();
 
   # we create fmtutil.cnf, language.dat, language.def in TEXMFSYSVAR
@@ -2505,8 +2495,7 @@ sub init_tlmedia {
       $location = give_ctan_mirror();
     }
     # that "location-url" line should not be changed since GUI programs
-    # depend on it. In case of $::machinereadable all the info 
-    # output is also going to STDERR.
+    # depend on it.
     print "location-url\t$location\n" if $::machinereadable;
     info("tlmgr: installation location $location\n");
 
@@ -2517,8 +2506,9 @@ sub init_tlmedia {
   }
 }
 
-# finish # evaluates only the -pause option, and then exits
-# if the global $::gui_mode is set to 1 then the not exit, but return is called
+# finish handles the -pause option (wait for input from stdin),
+# and then exits unless  the global $::gui_mode is set, in which case we
+# merely return.
 # 
 sub finish {
   my ($ret) = @_;
@@ -2749,6 +2739,12 @@ Windows via the registry, on Unix via C<LC_MESSAGES>). If that fails you
 can select a different language by giving this option a two-letter
 language code.
 
+=item B<--machine-readable>
+
+In lieu of the normal output intended for human consumption, write to
+standard output in a fixed format more suitable for machine parsing.
+See the L</"MACHINE-READABLE OUTPUT"> section below for details.
+
 =item B<--package-logfile> I<file>
 
 B<tlmgr> logs all package actions (install, remove, update, failed
@@ -3081,7 +3077,7 @@ directories specified by the respective options (see above).
 
 =item B<paper [a4|letter]>
 
-=item B<S<[xdvi|pdftex|dvips|dvipdfmx|dvipdfm|context] paper [I<papersize>|--list]>>
+=item B<S<xdvi|pdftex|dvips|dvipdfmx|dvipdfm|context paper [I<papersize>|--list]>>
 
 =back
 
@@ -3103,6 +3099,11 @@ With a program given as the first argument and C<--list> given as the
 last argument (e.g., C<tlmgr dvips paper --list>), shows all valid paper
 sizes for that program.  The first size shown is the default.
 
+Incidentally, this syntax of having a specific program name before the
+C<paper> keyword may seem strange.  It is inherited from the
+longstanding C<texconfig> script, which supports other configuration
+settings for some programs, notably C<dvips>.  C<tlmgr> does not support
+those extra settings at present.
 
 =head2 arch list|add I<arch>...
 
@@ -3204,7 +3205,7 @@ Do not ask for confirmation, remove immediately.
 =back
 
 
-=head2 generate
+=head2 generate [I<option>]... I<what>
 
 =over 4
 
@@ -3220,24 +3221,28 @@ Do not ask for confirmation, remove immediately.
 
 =back
 
-The I<generate> action overwrites any manual changes made in the
+The C<generate> action overwrites any manual changes made in the
 respective files: it recreates them from scratch.
 
-For fmtutil and the language files, this is normal, and both the TeX
+For C<fmtutil> and the language files, this is normal, and both the TeX
 Live installer and C<tlmgr> routinely call I<generate> for them.
 
-For updmap, however, neither the installer nor C<tlmgr> use I<generate>,
-because the result would be to disable all maps which have been manually
-installed via C<updmap-sys --enable>, e.g., for proprietary or local
-fonts.  Only the changes in the C<--localcfg> file mentioned below are
-incorporated by I<generate>.
-
-On the other hand, if you only use the fonts and font packages within
-TeX Live, there is nothing wrong with using I<generate updmap>.  Indeed,
-we use it to generate the C<updmap.cfg> file that is maintained in the
-live source repository.
-
-In more detail: I<generate> remakes any of the four config files
+For C<updmap>, however, neither the installer nor C<tlmgr> use
+C<generate>, because the result would be to disable all maps which have
+been manually installed via S<C<updmap-sys --enable>>, e.g., for
+proprietary or local fonts.  Only the changes in the C<--localcfg> file
+mentioned below are incorporated by I<generate>.  Furthermore, C<tlmgr>
+updates and maintains the final C<updmap.cfg> in C<TEXMFSYSCONFIG> (the
+others use C<TEXMFSYSVAR>) because that is the location that
+C<updmap-sys> (via C<tcfmgr>) uses.
+
+Notwithstanding the above, if you only use the fonts and font packages
+within TeX Live, and maintain your local fonts (if any) with the local
+config file, there is nothing wrong with using C<generate updmap>.
+Indeed, we use it ourselves to generate the C<updmap.cfg> file that is
+maintained in the live source repository.
+
+In more detail: C<generate> remakes any of the four config files
 C<language.dat>, C<language.def>, C<fmtutil.cnf>, and C<updmap.cfg> from
 the information present in the local TLPDB. If the files
 C<language-local.dat>, C<language-local.def>, C<fmtutil-local.cnf>, or
@@ -3256,7 +3261,8 @@ Options:
 =item B<--dest> I<output file>
 
 specifies the output file (defaults to the respective location in
-C<TEXMFSYSVAR>).  If B<--dest> is given to C<generate language>, its
+C<TEXMFSYSVAR> for C<language*> and C<fmtutil>, and C<TEXMFSYSCONFIG>
+for C<updmap>).  If B<--dest> is given to C<generate language>, its
 value will be used for the C<language.dat> output, and C<.def> will be
 appended to the value for the name of the C<language.def> output file.
 (This is just to avoid overwriting; if you want a specific name for each
@@ -3270,10 +3276,111 @@ location in C<TEXMFLOCAL>).
 =back
 
 The respective locations are as follows:
-  C<tex/generic/config/language.dat> (and C<language-local.dat>)
-  C<tex/generic/config/language.def> (and C<language-local.def>)
-  C<web2c/fmtutil.cnf> (and C<fmtutil-local.cnf>)
-  C<web2c/updmap.cfg> (and C<updmap-local.cfg>)
+
+  tex/generic/config/language.dat (and language-local.dat);
+  tex/generic/config/language.def (and language-local.def);
+  web2c/fmtutil.cnf (and fmtutil-local.cnf);
+  web2c/updmap.cfg (and updmap-local.cfg).
+
+
+=head1 MACHINE-READABLE OUTPUT
+
+Given the C<--machine-readable> option, C<tlmgr> writes to stdout in the
+fixed line-oriented format described here, and the usual informational
+messages for human consumption are written to stderr (normally they are
+written to stdout).  The idea is that a program can get all the
+information it needs by reading stdout.
+
+Currently this option only applies to the L<update|/"update
+[I<option>]... [I<pkg>]..."> action.  The output format is as follows:
+
+  fieldname "\t" value
+  ...
+  "end-of-header"
+  pkgname status localrev serverrev size
+  ...  
+
+Currently the header section contains two fields.  The field name and
+value are separated by a tab.  Line endings may be LF or CRLF depending
+on the current platform.
+
+=over 4
+
+=item C<location-url> I<location>
+
+The I<location> may be a url (including C<file:///foo/bar/...>), or a
+directory name (C</foo/bar>).  It is the server repository from which
+the new package information was drawn.
+
+=item C<total-bytes> I<count>
+
+The I<count> is simply a decimal number, the sum of all the packages
+given subsequently that need updating or installing.
+
+=back
+
+Then comes a line with only the literal string C<end-of-header>.
+
+Each following line until EOF reports on one package.  The fields on
+each line are separated by a tab.  Here are the fields.
+
+=over 4
+
+=item I<pkgname>
+
+The TeX Live package identifier, with a possible architecture suffix for
+executables.   For instance, C<pdftex> and C<pdftex.i386-linux> are
+given as two separate packages, one on each line.
+
+=item I<status>
+
+The status of the package update.  One character, as follows:
+
+=over 8
+
+=item C<d>
+
+The package was removed on the server.
+
+=item C<f>
+
+The package was removed on the server even though a collection depended
+on it.  (E.g., the user ran C<tlmgr remove --force>.)
+
+=item C<u>
+
+Normal update is needed.
+
+=item C<r>
+
+Reversed non-update: the locally-installed version is newer than the
+version on the server.
+
+=item C<a>
+
+Automatically-determined need for installation, the package is new on
+the server and is (most probably) part of an installed collection.
+
+=back
+
+=item I<localrev>
+
+The revision number of the installed package.
+
+=item I<serverrev>
+
+The revision number of the package on the server.
+
+=item I<size>
+
+The size in bytes of the package on the server.
+
+=back
+
+
+
+If you are developing a program that uses this output, and find that
+changes would be helpful, do not hesitate to write the mailing list.
 
 
 =head1 AUTHORS AND COPYRIGHT