backup doc review

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

1 files changed, 65 insertions, 71 deletions

diff --git a/Master/texmf/scripts/texlive/tlmgr.pl b/Master/texmf/scripts/texlive/tlmgr.pl
index ef523703e61..974a3eba20b 100755
--- a/Master/texmf/scripts/texlive/tlmgr.pl
+++ b/Master/texmf/scripts/texlive/tlmgr.pl
@@ -2355,7 +2355,7 @@ written to the terminal.
 =back
 
 
-=item B<update> [I<option>] [I<pkg>...]
+=item B<update> [I<option>] [I<pkg>]...
 
 Updates the packages given as arguments to the latest version available
 at the installation source.  Either C<--all> or at least one I<pkg> name
@@ -2394,24 +2394,26 @@ above. This prevents any such removals.
 
 =item B<--backup> and B<--backupdir> I<directory>
 
-These options control the creation of backups of packages before
-an update is started. If none of the two are given, no backup package
-will be saved. If B<--backupdir> is given specifying a (writable)
-directory then a back up will be made in that location. If only
-B<--backup> is given then the location for the backups has to be
-set in the tlpdb via the B<option> action (see below). If both are
-given then a backup will be made to the specified directory.
-
-By setting relevent options in the tlpdb via the B<option> action
-it is possible to automatically create backups for all packages, and
-keep only a certain number of backups. Please see the B<option>
-action for details. So if B<--backup> is not given, but the B<autobackup>
-option is set in the tlpdb, a backup will be made.
-
-I<directory> specifies a directory where the package as installed will
-be saved before updates are performed.  Then you can restore later if
-the update turns out to be problematic; see the C<restore> action for
-details.
+These two options control the creation of backups of packages before an
+update is started; that is, the backup is of the package as it's
+installed.  If neither of the two are given, no backup package will be
+saved. If B<--backupdir> is given and specifies a writable directory
+then a backup will be made in that location. If only B<--backup> is
+given, then a backup will be made to the directory previously set via
+the C<option> action (see below). If both are given then a backup will
+be made to the specified I<directory>.
+
+You can set options via the C<option> action to automatically create
+backups for all packages, and/or keep only a certain number of
+backups. Please see the C<option> action for details. 
+
+C<tlmgr> always makes a temporary backup when updating packages, in case
+of download or other failure during an update.  The purpose of this
+B<--backup> option is to allow you to save a persistent backup in case
+the actual I<content> of the update causes problems, e.g., introduces an
+incompatibility.
+
+The C<restore> action explains how to restore from a backup.
 
 =item B<--no-depends>
 
@@ -2421,12 +2423,12 @@ supresses this behaviour.
 
 =item B<--no-depends-at-all>
 
-When you update a package which ships binary files the respective binary
-package will also be updated. (So for package bin-foobar also the package
-bin-foobar.i386-linux will be updated on an i386-linux system.)
-This switch supresses this behaviour, and also implies C<--no-depends>.
-Don't use it unless you are really sure what you are doing.
-
+By default, when you update a package which ships binary files the
+respective binary package will also be updated.  That is, for an update
+of a package C<foo>, the package C<foobar.i386-linux> will also be
+updated if the i386-linux platform is installed.  This option suppresses
+this behaviour, and implies C<--no-depends>.  Don't use it unless you
+are sure of what you are doing.
 
 =back
 
@@ -2435,20 +2437,20 @@ If the package on the server is older than the package already installed
 downgrade.  Also, packages for uninstalled platforms are not installed.
 
 
-=item B<backup> [--clean[=I<N>]] [--backupdir I<dir>] [B<--all>] [I<pkg>...]
+=item B<backup> [--clean[=I<N>]] [--backupdir I<dir>] [B<--all>] [I<pkg>]...
 
-The first mode without the B<--clean> switch is to make a backup of
-the given packages, or all packages with C<--all>. These backups are
-saved to the following place: If the B<--backupdir> option if given, to 
-the directory I<dir>, which must exist and be writable. 
-If the B<--backupdir> option is not given, the option setting in the
-tlpdb is used, if present. If both are missing, no backups are made.
+If the B<--clean> option is not specified, this action makes a backup of
+the given packages, or all packages given C<--all>. These backups are
+saved to the value of B<--backupdir> option if that is an existing and
+writable directory; if B<--backupdir> is not given, the C<backupdir>
+option setting in the TLPDB is used, if present.  If both are missing,
+no backups are made.
 
-The second mode is when the B<--clean> switch is given, either with
-or without argument. If the value for the B<--clean> switch is missing, the
-option B<autobackup> from the tlpdb is used. If both are missing B<tlmgr>
-will terminate. For the meaning of the different values of that switch
-see below the B<option> action.
+If the B<--clean> option is specified, backups are cleaned (pruned)
+instead of made.  If the value for the B<--clean> switch is not given,
+the value of the B<autobackup> option from is used. If both are missing,
+an error is issued.  For the details of backup cleaning, see the
+C<option> action below.
 
 Options:
 
@@ -2464,10 +2466,9 @@ directory where backups are to be placed.
 Make a backup of all packages in the TeX Live installation.  This will
 take quite a lot of space and time.
 
-=item B<--clean>
+=item B<--clean>[=I<N>]
 
-Instead of making backups cleans up the backup directory from old
-backups.
+Instead of making backups, prune the backup directory of old backups.
 
 =item B<--dry-run>
 
@@ -2501,8 +2502,7 @@ written to the terminal.
 
 =item B<--backupdir> I<directory>
 
-This is an obligatory argument and has to specify a directory where
-backups are to be found.
+Specify the directory where the backups are to be found.
 
 =back
 
@@ -2522,11 +2522,7 @@ Do not remove dependent packages.
 
 =item B<--no-depends-at-all>
 
-When you remove a package which ships binary files the respective binary
-package will also be removed. (So for package bin-foobar also the package
-bin-foobar.i386-linux will be removed on an i386-linux system.)
-This switch supresses this behaviour, and also implies C<--no-depends>.
-Don't use it unless you are really sure what you are doing.
+See above under B<action> (and beware).
 
 =item B<--force>
 
@@ -2553,14 +2549,14 @@ In the second form, if I<value> is not given, the setting for I<key> is
 displayed.  If I<value> is present, I<key> is set to I<value>.
 
 Possible values for I<key> are:
-C<location> (default installation location),
-C<formats> (create formats at installation time),
-C<docfiles> (install documentation files),
-C<srcfiles> (install source files),
-C<autobackup> (specify the number of backups to be kept),
-C<backupdir> (specify the default location for backups).
-
-Perhaps the most common use for this is if you originally installed from
+ C<location> (default installation location),
+ C<formats> (create formats at installation time),
+ C<docfiles> (install documentation files),
+ C<srcfiles> (install source files),
+ C<autobackup> (number of backups to be kept),
+ C<backupdir> (default directory for backups).
+
+Perhaps the most common use of C<option> is if you originally installed from
 DVD, and want to permanently change the installation to get further
 updates from the Internet.  To do this, you can run
 
@@ -2568,22 +2564,20 @@ updates from the Internet.  To do this, you can run
 
 where YYYY is the TeX Live release year.
 
-The two options C<autobackup> and C<backupdir> can be used to specify 
-defaults for the B<update>, B<backup> and B<restore> actions. These
-three actions normally need a directory to write to or read from the
-backups. If nothing is specified on the command line, the default taken
-from the C<backupdir> is taken.
+The two options C<autobackup> and C<backupdir> determine defaults for
+the C<update>, C<backup> and C<restore> actions.  These three actions
+need a directory to write to or read from the backups.  If
+C<--backupdir> is not specified on the command line, the C<backupdir>
+option value is used (if set).
 
-The C<autobackup> option (de)activates the automatical generation of
-backups. This option can be an integer larger or equal then -1. If 
-C<autobackup> is -1, backups will not be removed (if you not ask for
-explicitely with B<tlmgr backup --clean=I<N> ...> specifying for I<N>
-something different then -1. If it any other integer, i.e., larger or
-equal than 0, it specifies the number of backups to be kept. That also
-includes that backups are disabled with 0 as argument.
+The C<autobackup> option (de)activates the automatic generation of
+backups. Its value is an integer.  If C<autobackup> is -1, backups will
+not be removed by default.  If C<autobackup> is 0 or positive, it
+specifies the number of backups to be kept.  Thus, backups are disabled
+with 0 as the values.
 
-In the B<--clean> mode of the B<backup> action this option also specifies
-the number to be kept.
+In the C<--clean> mode of the C<backup> action this option also
+specifies the number to be kept.
 
 =item B<paper a4>
 
@@ -2615,7 +2609,7 @@ written to the terminal.
 =back
 
 
-=item B<search [I<option>...] I<what>>
+=item B<search [I<option>]... I<what>>
 
 By default searches the names, short and long descriptions of all
 locally installed packages for the given argument (interpreted as
@@ -2650,7 +2644,7 @@ location, prefixing those already installed with "C<i>".
 With an argument lists only collections or schemes, as requested.
 
 
-=item B<check [I<option>...] [files|collections|all]>
+=item B<check [I<option>]... [files|collections|all]>
 
 Executes one (or all) check(s) on the consistency of the installation.