document info/[d]debug/tlwarn, other doc tweaks

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

3 files changed, 110 insertions, 25 deletions

diff --git a/Master/install-tl b/Master/install-tl
index 411d622a99f..84147401924 100755
--- a/Master/install-tl
+++ b/Master/install-tl
@@ -714,12 +714,11 @@ sub initialize_collections {
 }
 
 sub set_install_platform {
-  my @available_platforms;
   my $detected_platform=platform;
   my $warn_nobin;
   my $warn_nobin_x86_64_linux;
   my $nowarn="";
-  my $wp='##'; # warning prefix
+  my $wp='***'; # warning prefix
 
   $warn_nobin="\n$wp WARNING!  No binaries for your platform found!  ";
   $warn_nobin_x86_64_linux="$warn_nobin" .
@@ -1327,8 +1326,8 @@ Omit normal informational messages.
 
 =item B<-v>
 
-Include debugging messages; repeat for maximum debugging, as in C<-vv>.
-(Further repeats are accepted and ignored.)
+Include debugging messages; repeat for maximum debugging, as in C<-v
+-v>.  (Further repeats are accepted but ignored.)
 
 =item B<--help>, B<-help>, B<-?>
 
diff --git a/Master/tlpkg/TeXLive/TLUtils.pm b/Master/tlpkg/TeXLive/TLUtils.pm
index e337fe845d3..8a776159ca2 100644
--- a/Master/tlpkg/TeXLive/TLUtils.pm
+++ b/Master/tlpkg/TeXLive/TLUtils.pm
@@ -1387,14 +1387,53 @@ sub _logit {
   }
 }
 
+=pod
+
+=item C<info ($str1, $str2, ...)>
+
+Write a normal informational message, the concatenation of the argument
+strings.  The message will be included unless C<-q> was specified.  If
+the log file (see L<process_logging_options) is defined, it also writes
+there.
+
+We try to use this sparingly, mainly to give feedback during lengthy
+operations.
+
+=cut
+
 sub info {
   logit(\*STDOUT, 0, @_);
 }
 
+=pod
+
+=item C<debug ($str1, $str2, ...)>
+
+Write a debugging message, the concatenation of the argument strings.
+The message will be omitted unless C<-v> was specified.  If the log
+file (see L<process_logging_options) is defined, it also writes there.
+
+=cut
+
 sub debug {
   logit(\*STDOUT, 1, "D:", @_);
 }
 
+=pod
+
+=item C<ddebug ($str1, $str2, ...)>
+
+Write a deep debugging message, the concatenation of the argument
+strings.  The message will be omitted unless C<-v -v> was specified.  If
+the log file (see L<process_logging_options) is defined, it also writes
+there.
+
+This output is extremely voluminous; for example, every line of input
+when reading the TeX Live Database is reported.  It includes everything
+we ever found useful when debugging.
+
+=cut
+
 sub ddebug {
   logit(\*STDOUT, 2, "DD:", @_);
 }
@@ -1408,15 +1447,61 @@ sub log {
   $::opt_quiet = $savequiet;
 }
 
+=pod
+
+=item C<tlwarn ($str1, $str2, ...)>
+
+Write a warning message, the concatenation of the argument strings.
+This always and unconditionally writes the message to standard error; if
+the log file (see L<process_logging_options) is defined, it also writes
+there.
+
+=cut
+
 sub tlwarn {
-  # warning should always done to stderr and the log file,
-  # independently from the verbosity level
   my $savequiet = $::opt_quiet;
   $::opt_quiet = 0;
-  logit(\*STDERR, -100, @_);
+  logit (\*STDERR, -100, @_);
   $::opt_quiet = $savequiet;
 }
 
+=pod
+
+=item C<process_logging_options ($texdir)>
+
+This function handles the common logging options for TeX Live scripts.
+It should be called before C<GetOptions> for any program-specific option
+handling.  For our conventional calling sequence, see (for example) the
+L<tlpfiles> script.
+
+These are the options handled here:
+
+=over 8
+
+=item B<-q>
+
+Omit normal informational messages.
+
+=item B<-v>
+
+Include debugging messages; repeat for maximum debugging, as in C<-v
+-v>.  (C<-vv> does not work, sorry to say.)  Further repeats, as in
+C<-v -v -v>, are accepted but ignored.
+
+=item B<-logfile> I<file>
+
+Write both all messages (informational, debugging, warnings) to I<file>,
+in addition to standard output or standard error.  In TeX Live, only the
+installer sets a log file by default, none of other the standard TeX
+Live scripts use this feature. 
+
+=back
+
+See also the L<info>, L<debug>, L<ddebug>, and L<tlwarn> functions,
+which actually write the messages.
+
+=cut
+
 sub process_logging_options {
   $::opt_verbosity = 0;
   $::opt_quiet = 0;
@@ -1436,19 +1521,20 @@ sub process_logging_options {
 
 =pod
 
+
 =item C<kpsewhich($varname)>
 
-This function expands the variable name using kpsewhich. The variable
-name should not have a leading $. The kpsewhich binary has to be in
-the path.
+This function expands the variable name using C<kpsewhich
+-var-value>.  The variable name should not have a leading $.  The
+C<kpsewhich> binary has to be in the path.
 
 =cut
 
 sub kpsewhich {
   my $var = shift;
-  my $ret = `kpsewhich -var-value=$var`;
+  my $ret = `kpsewhich -var-value='$var'`;
   chomp ($ret);
-  return($ret);
+  return $ret;
 }
 
 =pod
diff --git a/Master/tlpkg/bin/tlpfiles b/Master/tlpkg/bin/tlpfiles
index 875cea63f0c..970bacd6b07 100755
--- a/Master/tlpkg/bin/tlpfiles
+++ b/Master/tlpkg/bin/tlpfiles
@@ -27,12 +27,12 @@ our $FILE;
 our %DB_BY_FILE;  # used privately below.
 
 our @opt_pkgof = ();
-my $help = 0;
+my $opt_help = 0;
 
 TeXLive::TLUtils::process_logging_options ();
-GetOptions("pkgof=s" => \@opt_pkgof,
-           "help|?" => \$help) or pod2usage(2);
-pod2usage ("-exitstatus" => 0, "-verbose" => 2) if $help;
+GetOptions ("pkgof=s" => \@opt_pkgof,
+            "help|?" => \$opt_help) or pod2usage (2);
+pod2usage ("-exitstatus" => 0, "-verbose" => 2) if $opt_help;
 
 exit (&main ());
 
@@ -130,7 +130,7 @@ tlpfiles - list files contained in a TeX Live package, or vice versa
 
 =head1 SYNOPSIS
 
-tlpfiles [I<option>]... I<tlpkg>
+  tlpfiles [I<option>]... I<tlpkg>
   or: tlpfiles [I<option>]... -pkgof I<file>...
 
 =head1 OPTIONS
@@ -138,20 +138,19 @@ tlpfiles [I<option>]... I<tlpkg>
 =over 8
 
 =item B<-pkgof> I<file>...
-Output the TeX Live package(s) in which each <file> is contained.
 
-=item B<-help>
-Print this documentation and exit.
+Output the TeX Live package(s) in which each I<file> is contained.
 
-=item B<-q>
-Omit normal informational messages.
+=item B<-help>
 
-=item B<-v>
-Include debugging messages; repeat for maximum debugging, as in C<-vv>.
-(Further repeats are accepted and ignored.)
+Print this documentation and exit.
 
 =back
 
+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
 
 In the first form, with just I<TLPKG> specified, return all the files
@@ -168,6 +167,7 @@ package in which each given I<FILE> is contained, or C<-> if no package
 can be found.  The files may be given as a single whitespace-separated
 argument, or the C<-pkgof> option may be given more than once, or both.
 Example invocation, given the list of files to search for in C</tmp/f>:
+
   tlpfiles --pkgof "`cat /tmp/f`"
 
 Any directory part of the files is stripped.  If there are multiple