summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/scripts
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2013-04-14 18:42:14 +0000
committerKarl Berry <karl@freefriends.org>2013-04-14 18:42:14 +0000
commit706e437fe3277b510cd1a935f155e88b26fb5233 (patch)
treee5ac54e8e0fc962146386815b1d7df5f03f2c63a /Master/texmf-dist/scripts
parent5f49a6080d03cfc1a1701853ab61eb8ce0cc3568 (diff)
doc changes for user mode, etc.
git-svn-id: svn://tug.org/texlive/trunk@29915 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/scripts')
-rwxr-xr-xMaster/texmf-dist/scripts/texlive/tlmgr.pl236
1 files changed, 117 insertions, 119 deletions
diff --git a/Master/texmf-dist/scripts/texlive/tlmgr.pl b/Master/texmf-dist/scripts/texlive/tlmgr.pl
index 05017552c36..36937fd12fd 100755
--- a/Master/texmf-dist/scripts/texlive/tlmgr.pl
+++ b/Master/texmf-dist/scripts/texlive/tlmgr.pl
@@ -126,16 +126,16 @@ sub main {
"gui" => 1,
"gui-lang" => "=s",
"debug-translation" => 1,
- "location|repository|repo" => "=s",
+ "repository|repo|location" => "=s",
"machine-readable" => 1,
+ "no-execute-actions" => 1,
"package-logfile" => "=s",
"persistent-downloads" => "!",
- "no-execute-actions" => 1,
- "pin-file" => "=s",
"pause" => 1,
- "usermode" => 1,
- "usertree" => "=s",
+ "pin-file" => "=s",
"print-platform|print-arch" => 1,
+ "usermode|user-mode" => 1,
+ "usertree|user-tree" => "=s",
"version" => 1,
"help" => 1,
"h|?" => 1);
@@ -481,7 +481,7 @@ sub give_version {
#
# add the list of revisions
if ($::opt_verbosity > 0) {
- $::version_string .= "Revision of modules:";
+ $::version_string .= "Revisions of TeXLive:: modules:";
$::version_string .= "\nTLConfig: " . TeXLive::TLConfig->module_revision();
$::version_string .= "\nTLUtils: " . TeXLive::TLUtils->module_revision();
$::version_string .= "\nTLPOBJ: " . TeXLive::TLPOBJ->module_revision();
@@ -613,7 +613,7 @@ sub execute_action {
# close the special log file
if ($packagelogfile && !$::gui_mode) {
- info("tlmgr: package log updated at $packagelogfile\n") if $packagelogged;
+ info("$prg: package log updated: $packagelogfile\n") if $packagelogged;
close(PACKAGELOG);
}
@@ -5933,7 +5933,7 @@ C<install-tl> has more details about this
C<--repository> changes the repository location only for the current
run; to make a permanent change, use C<option repository> (see the
-L<option> action).
+L</option> action).
For backward compatibility and convenience, C<--location> and C<--repo>
are accepted as aliases for this option.
@@ -5941,14 +5941,14 @@ are accepted as aliases for this option.
=item B<--gui> [I<action>]
-C<tlmgr> has a graphical interface as well as the command-line
+C<tlmgr> has a graphical interface as well as the command line
interface. You can give this option, C<--gui>, together with an action
to be brought directly into the respective screen of the GUI. For
example, running
tlmgr --gui update
-starts you directly at the update screen. Without any action, the
+starts you directly at the update screen. If no action is given, the
GUI will be started at the main screen.
=for comment Keep language list in sync with install-tl.
@@ -5965,12 +5965,24 @@ Polish (pl), Brazilian Portuguese (pt_BR), Russian (ru), Slovak (sk),
Slovenian (sl), Serbian (sr), Vietnamese (vi), simplified Chinese
(zh_CN), and traditional Chinese (zh_TW).
+=item B<--debug-translation>
+
+In GUI mode, this switch tells C<tlmgr> to report any untranslated (or
+missing) messages to standard error. This can help translators to see
+what remains to be done.
+
=item B<--machine-readable>
Instead of the normal output intended for human consumption, write (to
standard output) a fixed format more suitable for machine parsing. See
the L</"MACHINE-READABLE OUTPUT"> section below.
+=item B<--no-execute-actions>
+
+Suppress the execution of the execute actions as defined in the tlpsrc
+files. Documented only for completeness, as this is only useful in
+debugging.
+
=item B<--package-logfile> I<file>
C<tlmgr> logs all package actions (install, remove, update, failed
@@ -5988,45 +6000,39 @@ Windows to avoid disappearing command windows.
=item B<--no-persistent-downloads>
For network-based installations, this option (on by default) makes
-C<tlmgr> try to set up a persistent connection (using the L<Net::LWP>
-Perl module). The idea is to open and reuse only one connection per
-session between your computer and the server, instead of initiating a
-new download for each package.
+C<tlmgr> try to set up a persistent connection (using the C<LWP> Perl
+module). The idea is to open and reuse only one connection per session
+between your computer and the server, instead of initiating a new
+download for each package.
If this is not possible, C<tlmgr> will fall back to using C<wget>. To
disable these persistent connections, use C<--no-persistent-downloads>.
-=item B<--no-execute-actions>
+=item B<--pin-file>
-Suppress the execution of the execute actions as defined in the tlpsrc
-files. Documented only for completeness, as this is only useful in
-debugging.
-
-=item B<--debug-translation>
-
-In GUI mode, this switch makes C<tlmgr> report any missing, or more
-likely untranslated, messages to standard error. This can help
-translators to see what remains to be done.
+Change the pinning file location from C<TEXMFLOCAL/tlpkg/pinning.txt>
+(see L</Pinning> below). Documented only for completeness, as this is
+only useful in debugging.
=item B<--usermode>
-Activates the user mode, see L<USER MODE> below.
+Activates user mode for this run of C<tlmgr>; see L<USER MODE> below.
=item B<--usertree> I<dir>
-Uses I<dir> as user tree in user mode, seel L<USER MODE> below.
-
+Uses I<dir> for the tree in user mode; see L<USER MODE> below.
=back
The standard options for TeX Live programs are also accepted:
C<--help/-h/-?>, C<--version>, C<-q> (no informational messages), C<-v>
(debugging messages, can be repeated). For the details about these, see
-the L<TeXLive::TLUtils> documentation.
+the C<TeXLive::TLUtils> documentation.
The C<--version> option shows version information about the TeX Live
-release and about the C<tlmgr> script itself. If C<-v> is given as
-well, revision number for the used TeX Live Perl modules are shown, too.
+release and about the C<tlmgr> script itself. If C<-v> is also given,
+revision number for the loaded TeX Live Perl modules are shown, too.
+
=head1 ACTIONS
@@ -6376,6 +6382,13 @@ L</"TAXONOMIES"> below for details.
=back
+=head2 init-usertree
+
+Sets up a texmf tree for so-called user mode management, either the
+default user tree (C<TEXMFHOME>), or one specified on the command line
+with C<--usertree>. See L<USER MODE> below.
+
+
=head2 install [I<option>]... I<pkg>...
Install each I<pkg> given on the command line. By default this installs
@@ -6564,7 +6577,7 @@ those extra settings at present.
On Unix, merely adds or removes symlinks for binaries, man pages, and
info pages in the system directories specified by the respective options
-(see the L<option> description above). Does not change any
+(see the L</option> description above). Does not change any
initialization files, either system or personal.
On Windows, the registry part where the binary directory is added or
@@ -6590,7 +6603,7 @@ is issued that the caller does not have enough privileges.
=head2 pinning
-The C<pinning> action manages the pinning file, see L<Pinning> below.
+The C<pinning> action manages the pinning file, see L</Pinning> below.
=over 4
@@ -7070,107 +7083,92 @@ downgrade. Also, packages for uninstalled platforms are not installed.
-=head2 init-usertree
-
-sets up the default user tree (C<TEXMFHOME>) or the one specified
-on the command line using C<--usertree> for user mode management.
-See L<USER MODE> below.
-
-
=head1 USER MODE
-B<WARNING> B<WARNING> B<WARNING>
-This is very much work in progress
-and experimental. Expect breakage, and the need to reinstall your
-user tree a new.
+B<WARNING:> This is new work in TL 2013. Expect breakage, and the need
+to reinstall your user tree.
-C<tlmgr> provides a restricted way to manage arbitrary texmf trees
-in the same way as the installation. This allows a user without write
-permissions to the installation location to update/install packages
-into a user tree.
+C<tlmgr> provides a restricted way, called ``user mode'', to manage
+arbitrary texmf trees in the same way as the main installation. For
+example, this allows people without write permissions on the
+installation location to update/install packages into a tree of their
+own.
-C<tlmgr> is set into user mode by giving the command line option
-C<--usermode>. It will not switch automatically, nor does it support
-a config file by now. Thus, this option has to be given every time.
+C<tlmgr> is switched into user mode with the command line option
+C<--usermode>. It does not switch automatically, nor is there any
+configuration file setting for it. Thus, this option has to be
+explicitly given every time user mode is to be activated.
-This mode of C<tlmgr> works on a user tree, which by default will be
-the value of C<TEXMFHOME>, but can be overridden with the command line
-option C<--usertree>. In the following when we speak of the user tree
+This mode of C<tlmgr> works on a user tree, by default the value of the
+C<TEXMFHOME> variable. This can be overridden with the command line
+option C<--usertree>. In the following when we speak of the user tree
we mean either C<TEXMFHOME> or the one given on the command line.
-Not all actions are allowed in user mode, C<tlmgr> will warn you and
-not carry out this action. The actions of C<tlmgr> can be classified into
-those that don't need write permissions and thus are working the same
-in user mode or normal mode. Currently these are
-B<help>, B<version>, B<search>, B<show>, B<list>, B<check>, B<print-arch>.
-
-Most of the actions dealing with package management on the other hand
-need write permissions, and behave differently:
-B<install>, B<update>, B<remove>, B<option>, B<paper>, B<generate>,
-B<backup>, B<restore>, B<uninstall>, B<symlinks>.
+Not all actions are allowed in user mode; C<tlmgr> will warn you and not
+carry out any problematic actions. Currently not supported (and
+probably will never be) is the C<platform> action. The C<gui> action is
+currently not supported, but may be in a future release.
-Currently not supported (and probably will never be) is the B<arch>
-action.
+Some C<tlmgr> actions don't need any write permissions and thus work the
+same in user mode and normal mode. Currently these are: C<check>,
+C<help>, C<list>, C<print-platform>, C<search>, C<show>, C<version>.
-As for the B<gui> action it is currently not supported, but might be
-in future.
+On the other hand, most of the actions dealing with package management
+do need write permissions, and thus behave differently in user mode, as
+described below: C<install>, C<update>, C<remove>, C<option>, C<paper>,
+C<generate>, C<backup>, C<restore>, C<uninstall>, C<symlinks>.
Before using C<tlmgr> in user mode, you have to set up the user tree
-with the B<init-usertree> action. This will create C<USERTREE/web2c>,
-C<USERTREE/tlpkg/tlpobj> and set up a minimal C<USERTREE/tlpkg/texlive.tlpdb>.
-From then on you can use the supported actions as normal by adding
-the C<--usermode> command line switch.
-
-In user mode the file C<USERTREE/tlpkg/texlive.tlpdb> contains only the
-packages that have been installed into the user tree C<USERTREE> using
-C<tlmgr>, plus additional options in the virtual package
-00texlive.installation (like with the main installation's texlive.tlpdb).
+with the C<init-usertree> action. This creates I<usertree>C</web2c> and
+I<usertree>C</tlpkg/tlpobj>, and a minimal
+I<usertree>C</tlpkg/texlive.tlpdb>. At that point, you can tell
+C<tlmgr> to do the (supported) actions by adding the C<--usermode>
+command line option.
+
+In user mode the file I<usertree>C</tlpkg/texlive.tlpdb> contains only
+the packages that have been installed into the user tree using C<tlmgr>,
+plus additional options from the ``virtual'' package
+C<00texlive.installation> (similar to the main installation's
+C<texlive.tlpdb>).
All actions on packages in user mode can only be carried out on packages
-that are marked as B<relocatable>. Basically that means that the contained
-files all reside in the C<texmd-dist> tree. B<NOTE> That already excludes
-all binary packages! Of the currently about 1900 packages the majority,
-currently about 1750, are relocatable, i.e., they can be installed into
-a user tree.
+that are known as C<relocatable>. This excludes all packages containing
+executables and a few other core packages. Of the 2500 or so packages
+currently in TeX Live the vast majority are relocatable and can be
+installed into a user tree.
Description of changes of actions in user mode:
-=head2 install
+=head3 install
-in usermode the tlmgr action install will check that the package
-and all depending packages are either all relocated, or those that
-are not relocated are already installed in the system installation.
-If this is true it will unpack all containers to be installed into
-the user tree (TEXMFHOME or the value of --user-tree) and add the
-respective packages to the user texlive.tlpdb (creating it if there
-has non be created till now).
+In user mode, the C<install> action checks that the package and all
+dependencies are all either relocated or already installed in the system
+installation. If this is the case, it unpacks all containers to be
+installed into the user tree (to repeat, that's either C<TEXMFHOME> or
+the value of C<--usertree>) and add the respective packages to the user
+tree's C<texlive.tlpdb> (creating it if need be).
-Currently installing a collection installs all depending packages,
-but in contrast to normal mode does not install depending collections.
-So in *normal* mode tlmgr install collection-context would install
-collection-metapost, c-basic, c-documentation-base, too. In *usermode*
-only the packages mentioned in collection-context are installed.
+Currently installing a collection in user mode installs all dependent
+packages, but in contrast to normal mode, does I<not> install dependent
+collections. For example, in normal mode C<tlmgr install
+collection-context> would install C<collection-basic> and other
+collections, while in user mode, I<only> the packages mentioned in
+C<collection-context> are installed.
=head2 backup, restore, remove, update
-in usermode the tlmgr action update will check that all packages
-to be updated are installed in the user tree, otherwise it behaves
-exactely like the system tlmgr.
+In user mode, these actions check that all packages to be acted on are
+installed in the user tree before proceeding; otherwise, they behave
+just as in normal mode.
-=head2 option
-
-only acts upon the user's texlive.tlpdb
-
-=head2 paper
-
-changes configuration files in user tree
-
-=head2 generate
+=head2 generate, option, paper
+In user mode, these actions operate only on the user tree's
+configuration files and/or C<texlive.tlpdb>.
creates configuration files in user tree
-B<WARNING WARNING WARNING> Be again warned that this is very experimental!
-
+B<WARNING> repeated: this is still has to be considered experimental!
+Please report bugs to C<tex-live@tug.org> as usual
=head1 TLMGR CONFIGURATION FILE
@@ -7210,21 +7208,21 @@ options:
=over 4
-=item B<--keyword>
+=item C<--keyword>
The keywords, as specified at L<http://az.ctan.org/keyword>.
-=item B<--functionality>
+=item C<--functionality>
The ``by-topic'' categorization created by J\"urgen Fenn, as specified
at L<http://az.ctan.org/characterization/by-function>.
-=item B<--characterization>
+=item C<--characterization>
Both the primary and secondary functionalities, as specified at
L<http://az.ctan.org/characterization/choose_dimen>.
-=item B<--taxonomy>
+=item C<--taxonomy>
Operate on all the taxonomies.
@@ -7489,14 +7487,14 @@ The following entries can be found in the menu bar:
=over 4
-=item B<tlmgr> menu
+=item C<tlmgr> menu
The items here load various repositories: the default as specified in
the TeX Live database, the default network repository, the repository
specified on the command line (if any), and an arbitrarily
manually-entered one. Also has the so-necessary C<quit> operation.
-=item B<Options menu>
+=item C<Options menu>
Provides access to several groups of options: C<Paper> (configuration of
default paper sizes), C<Platforms> (only on Unix, configuration of the
@@ -7515,7 +7513,7 @@ automatic removal of packages deleted from the server. Playing with the
choices of what is or isn't installed may lead to an inconsistent TeX Live
installation; e.g., when a package is renamed.
-=item B<Actions menu>
+=item C<Actions menu>
Provides access to several actions: update the filename database (aka
C<ls-R>, C<mktexlsr>, C<texhash>), rebuild all formats (C<fmtutil-sys
@@ -7526,7 +7524,7 @@ Windows).
The final action is to remove the entire TeX Live installation (also not
on Windows).
-=item B<Help menu>
+=item C<Help menu>
Provides access to the TeX Live manual (also on the web at
L<http://tug.org/texlive/doc.html>) and the usual ``About'' box.
@@ -7545,10 +7543,10 @@ information it needs by reading stdout.
Currently this option only applies to the
L<update|/"update [I<option>]... [I<pkg>]...">, the
L<install|"install [I<option>]... I<pkg>...">, and the
-L<option|"option"> actions.
+L</option> actions.
-=head2 update and install actions
+=head3 update, install
The output format is as follows:
@@ -7670,7 +7668,7 @@ The estimated total time.
=back
-=head2 option action
+=head3 option
The output format is as follows: