summaryrefslogtreecommitdiff
path: root/Master/tlpkg/TeXLive
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2008-07-10 00:57:44 +0000
committerKarl Berry <karl@freefriends.org>2008-07-10 00:57:44 +0000
commit612e532d2f3279cac32624b31decca25dc03f5b7 (patch)
treeba60be183d2a9862be457e26443378031627df0f /Master/tlpkg/TeXLive
parent0dcbd08d9eda88bf5a9bf9166c44b2a2577362df (diff)
document info/[d]debug/tlwarn, other doc tweaks
git-svn-id: svn://tug.org/texlive/trunk@9415 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/tlpkg/TeXLive')
-rw-r--r--Master/tlpkg/TeXLive/TLUtils.pm102
1 files changed, 94 insertions, 8 deletions
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