diff options
author | Karl Berry <karl@freefriends.org> | 2008-07-10 00:57:44 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2008-07-10 00:57:44 +0000 |
commit | 612e532d2f3279cac32624b31decca25dc03f5b7 (patch) | |
tree | ba60be183d2a9862be457e26443378031627df0f /Master/tlpkg | |
parent | 0dcbd08d9eda88bf5a9bf9166c44b2a2577362df (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')
-rw-r--r-- | Master/tlpkg/TeXLive/TLUtils.pm | 102 | ||||
-rwxr-xr-x | Master/tlpkg/bin/tlpfiles | 26 |
2 files changed, 107 insertions, 21 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 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 |