summaryrefslogtreecommitdiff
path: root/Master
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2009-01-18 01:13:24 +0000
committerKarl Berry <karl@freefriends.org>2009-01-18 01:13:24 +0000
commit8dbc7cab489e5d3114eca8598ab1fc1d1b500a28 (patch)
tree57ca5b0609a20676252430c95690c49956c4de97 /Master
parent9a5f9a8fbaf534d7f2b0afa74d07e45ea5fada89 (diff)
doc fixes
git-svn-id: svn://tug.org/texlive/trunk@11907 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master')
-rwxr-xr-xMaster/texmf/scripts/texlive/tlmgr2.pl217
-rw-r--r--Master/tlpkg/TeXLive/TLUtils.pm8
2 files changed, 167 insertions, 58 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
diff --git a/Master/tlpkg/TeXLive/TLUtils.pm b/Master/tlpkg/TeXLive/TLUtils.pm
index 6550cd5d7d0..08657a84238 100644
--- a/Master/tlpkg/TeXLive/TLUtils.pm
+++ b/Master/tlpkg/TeXLive/TLUtils.pm
@@ -1664,9 +1664,11 @@ sub _logit {
=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.
+strings. The message will be written unless C<-q> was specified. If
+the global C<$::machinereadable> is set (the C<--machine-readable>
+option to C<tlmgr>), then output is written to stderr, else to stdout.
+If the log file (see L<process_logging_options>) is defined, it also
+writes there.
It is best to use this sparingly, mainly to give feedback during lengthy
operations and for final results.