install-tl doc (and ignore leading whitespace in profiles)

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

1 files changed, 183 insertions, 108 deletions

diff --git a/Master/install-tl b/Master/install-tl
index a4ba70285e5..2fbeb6e0379 100755
--- a/Master/install-tl
+++ b/Master/install-tl
@@ -1835,6 +1835,7 @@ sub read_profile {
     chomp;
     next if m/^[[:space:]]*$/; # skip empty lines
     next if m/^[[:space:]]*#/; # skip comment lines
+    s/^[[:space:]]+//;         # ignore leading (but not trailing) whitespace
     my ($k,$v) = split (" ", $_, 2); # value might have spaces
     # skip TEXDIRW, seems not used anymore, but might be around
     # in some profiles
@@ -2435,22 +2436,24 @@ install-tl-advanced.bat [I<option>]...
 =head1 DESCRIPTION
 
 This installer creates a runnable TeX Live installation from various
-media, including over the network.  The installer works across all
-platforms supported by TeX Live.  For information on initially
-downloading the TeX Live, see L<http://tug.org/texlive/acquire.html>.
+media, including over the network, from local hard disk, a DVD, etc.
+The installer works across all platforms supported by TeX Live.  For
+information on initially downloading the TeX Live, see
+L<http://tug.org/texlive/acquire.html>.
 
-The basic idea of TeX Live installation is to choose one of the
+The basic idea of TeX Live installation is for you to choose one of the
 top-level I<schemes>, each of which is defined as a different set of
 I<collections> and I<packages>, where a collection is a set of packages,
 and a package is what contains actual files.
 
 Within the installer, you can choose a scheme, and further customize the
-set of collections to install, but not the set of the packages.  To do
-that, use C<tlmgr> (reference below) after the initial installation is
-completely.
+set of collections to install, but not the set of the packages.  To work
+at the package level, use C<tlmgr> (reference just below) after the
+initial installation is complete.
+
+The default is C<scheme-full>, which installs everything, and this is
+highly recommended.
 
-The default is C<scheme-full>, to install everything, and this is highly
-recommended.
 
 =head1 REFERENCES
 
@@ -2458,12 +2461,13 @@ Post-installation configuration, package updates, and much more, are
 handled through B<tlmgr>(1), the TeX Live Manager
 (L<http://tug.org/texlive/tlmgr.html>).
 
-The most up-to-date version of this documentation is on the Internet at
-L<http://tug.org/texlive/doc/install-tl.html>.
+The most up-to-date version of this installer documentation is on the
+Internet at L<http://tug.org/texlive/doc/install-tl.html>.
 
 For the full documentation of TeX Live, see
 L<http://tug.org/texlive/doc>.
 
+
 =head1 OPTIONS
 
 As usual, all options can be specified in any order, and with either a
@@ -2474,12 +2478,12 @@ option by either a space or C<=>.
 
 =item B<-gui> [[=]I<module>]
 
-If no I<module> is given starts the C<perltk> (see below) GUI installer.
+If no I<module> is given, starts the C<perltk> (see below) GUI installer.
 
 If I<module> is given loads the given installer module. Currently the
 following modules are supported:
 
-=over 8
+=over 4
 
 =item C<text>
 
@@ -2498,12 +2502,11 @@ Can also be invoked on Windows by running C<install-tl-advanced.bat>.
 
 =back
 
-The C<perltk> and C<wizard> modules, and thus also when calling with a
-bare C<-gui> (without I<module>), requires the Perl/Tk module
+The C<perltk> and C<wizard> modules, and thus also when calling with
+bare C<-gui> (with no I<module>), require the Perl/Tk module
 (L<http://tug.org/texlive/distro.html#perltk>); if Perl/Tk is not
 available, installation continues in text mode.
 
-
 =item B<-no-gui>
 
 Use the text mode installer (default except on Windows).
@@ -2526,8 +2529,9 @@ simplified Chinese (zh_CN), and traditional Chinese (zh_TW).
 
 Specify the package repository to be used as the source of the
 installation, either a local directory via C</path/to/directory> or a
-C<file:/> url, or a network location via a C<http://> or C<ftp://> url.
-(No other protocols are supported.)
+C<file:/> url, or a network location via a C<http://>, C<https://>, or
+C<ftp://> url.  (No other protocols are supported, and C<https://> may
+not work on all platforms.)
 
 The default is to pick a mirror automatically, using
 L<http://mirror.ctan.org/systems/texlive/tlnet>; the chosen mirror is
@@ -2541,7 +2545,7 @@ you could choose a particular CTAN mirror with something like this:
 
   -repository http://ctan.example.org/its/ctan/dir/systems/texlive/tlnet
 
-Of course a real hostname and its particular top-level CTAN path
+Of course a real hostname and its particular top-level CTAN directory
 have to be specified.  The list of CTAN mirrors is available at
 L<http://ctan.org/mirrors>.
 
@@ -2573,9 +2577,9 @@ choose a good host for you.
 =item B<-all-options>
 
 Normally options not relevant to the current platform are not shown
-(i.e., when running on Unix, Windows-specific options are omitted).
-Giving this command line option allows configuring settings in the
-final C<texlive.tlpdb> that do not have any immediate effect.
+(e.g., when running on Unix, Windows-specific options are omitted).
+Giving this command line option allows configuring such "foreign"
+settings.
 
 =item B<-custom-bin> I<path>
 
@@ -2586,8 +2590,12 @@ the current system are present.  The installation will continue as
 usual, but at the end all files from I<path> are copied over to
 C<bin/custom/> under your installation directory and this C<bin/custom/>
 directory is what will be added to the path for the post-install
-actions.  (By the way, for information on building TeX Live, see
-L<http://tug.org/texlive/build.html>).
+actions.  To install multiple custom binary sets, manully rename
+C<custom> before doing each.
+
+For more information on custom binaries, see
+L<http://tug.org/texlive/custom-bin.html>.  For general information on
+building TeX Live, see L<http://tug.org/texlive/build.html>.
 
 =item B<-debug-translation>
 
@@ -2603,7 +2611,7 @@ runnable, or installation will fail.  C<-force-arch> is a synonym.
 
 =item B<-help>, B<--help>, B<-?>
 
-Display this help and exit (on the web via
+Display this help and exit.  (This help is on the web at
 L<http://tug.org/texlive/doc/install-tl.html>).  Sometimes the
 C<perldoc> and/or C<PAGER> programs on the system have problems,
 possibly resulting in control characters being literally output.  This
@@ -2620,6 +2628,12 @@ manually, and that the only realistic way to maintain this installation
 is to redo it from time to time.  This option is not available via the
 installer interfaces.  USE AT YOUR OWN RISK.
 
+=item B<-init-from-profile> I<profile_file>
+
+Similar to B<-profile> (see L</PROFILES> below), but only initializes the
+installation configuration from I<profile_file> and then starts the
+interactive session.
+
 =item B<-logfile> I<file>
 
 Write both all messages (informational, debugging, warnings) to I<file>,
@@ -2632,7 +2646,7 @@ release.
 
 =item B<-no-cls>
 
-(only for text mode installer) do not clear the screen when entering
+For the text mode installer only: do not clear the screen when entering
 a new menu (for debugging purposes).
 
 =item B<-non-admin>
@@ -2672,83 +2686,10 @@ Print the TeX Live identifier for the detected platform
 (hardware/operating system) combination to standard output, and exit.
 C<-print-arch> is a synonym.
 
-=item B<-profile> I<profile>
-
-Load the file I<profile> and do the installation with no user
-interaction, that is, a batch (unattended) install.
-
-A I<profile> file contains all the values needed to perform an
-installation.  From the text menu one can select 'P' to save the
-current setup as profile. Furthermore, after a normal installation
-has finished, a profile for that exact installation is written to the file
-DEST/tlpkg/texlive.profile.  That file can be given as the argument to
-C<-profile> to redo the exact same installation on a different system,
-for example.  Alternatively, you can use a custom profile, most easily
-created by starting from a generated one and changing values, or an
-empty file, which will take all the defaults.
-
-Normally a profile has to specify the value C<1> for each collection to
-be installed, even if the scheme is specified.  This follows from the
-logic of the installer in that you can first select a scheme and then
-change the collections being installed.  But for convenience there is an
-exception to this within profiles: If the profile contains a variable
-for C<selected_scheme> and I<no> collection variables at all are defined
-in the profile, then the collections which the specified scheme requires
-are installed.
-
-Thus, a line C<selected_scheme scheme-medium> together with the
-definitions of the installation directories (C<TEXDIR>, C<TEXMFHOME>,
-C<TEXMFLOCAL>, C<TEXMFSYSCONFIG>, C<TEXMFSYSVAR>) suffices to install
-the medium scheme with all default options.
-
-The list of allowed keys in a profile is given below. 
-For more detailed explanations on the meaning of the options
-consult the TeX Live installation manual. Values are either
-C<0>, C<1>, or strings.
-
-=over 8
-
-=item B<installer options> (those with prefix C<instopt_>)
-
-C<instopt_portable> (default 0, see C<-portable>), 
-C<instopt_letter> (default 0, selecting letter size instead of a4), 
-C<instopt_adjustrepo> (default 1, adjust remote repository to CTAN
-mirror after installation),
-C<instopt_write18_restricted> (default 1, enable write8 for a restricted
-set of programs),
-C<instopt_adjustpath> (default 0 on Unix, 1 on Windows, adjust PATH environment).
-
-=item B<tlpdb options> (those with prefix C<tlpdbopt_>)
-
-The definitive list is give in C<TeXLive::TLConfig.pm> in 
-C<%TeXLive::TLConfig::TLPDBOptions>, together with explanations.
-All items B<but> for C<tlpdbopt_location> can be specified.
-The current list is given below:
-
-C<tlpdbopt_autobackup>, C<tlpdbopt_backupdir>, C<tlpdbopt_create_formats>, 
-C<tlpdbopt_desktop_integration>, C<tlpdbopt_file_assocs>, C<tlpdbopt_install_docfiles>, 
-C<tlpdbopt_install_srcfiles>, C<tlpdbopt_post_code>, 
-C<tlpdbopt_sys_bin>, C<tlpdbopt_sys_info>, C<tlpdbopt_sys_man>, 
-C<tlpdbopt_w32_multi_user>, C<tlpdbopt_generate_updmap>
-
-=item B<path options>
-
-C<TEXDIR>, C<TEXMFHOME>, C<TEXMFCONFIG>, C<TEXMFSYSCONFIG>,
-C<TEXMFVAR>, C<TEXMFSYSVAR>, C<TEXMFLOCAL>
-
-=item B<architecture selection options> (those starting with C<binary_>)
-
-For every supported architecture of TeX Live (directories under
-C<bin/>), the key C<binary_ARCH> can be set. 
-
-Example: C<binary_x86_64-linux>
-
-=back
-
-=item B<-init-from-profile> I<profile>
+=item B<-profile> I<profile_file>
 
-Similar to B<-profile>, but merely initializes the installation
-configuration from I<profile> and then starts the interactive session.
+Load I<profile_file> and do the installation with no user interaction,
+that is, a batch (unattended) install.  See L</PROFILES> below.
 
 =item B<-q>
 
@@ -2766,8 +2707,8 @@ menu list.
 
 =item B<-v>
 
-Include verbose debugging messages; repeat for maximum debugging, as in
-C<-v -v>.  (Further repeats are accepted but ignored.)
+Include verbose debugging messages; repeat for maximum debugging: C<-v
+-v>.  (Further repeats are accepted but ignored.)
 
 =item B<-version>, B<--version>
 
@@ -2777,10 +2718,142 @@ revisions of the used modules are reported, too.
 =back
 
 
+=head1 PROFILES
+
+A I<profile> file contains all the values needed to perform an
+installation.  After a normal installation has finished, a profile for
+that exact installation is written to the file C<tlpkg/texlive.profile>.
+In addition, from the text menu one can select C<P> to save the current
+setup as a profile at any time.  Such a profile file can be given as the
+argument to C<-profile>, for example to redo the exact same installation
+on a different system.  Alternatively, you can use a custom profile,
+most easily created by starting from a generated one and changing
+values, or an empty file, which will take all the defaults.
+
+Within a profile file, each line consists of
+
+I<variable> [I<value>]
+
+except for comment lines starting with C<#>.  The possible variable
+names are listed below.  Values, when present, are either C<0> or C<1>
+for booleans, or strings (which must be specified without any quote
+characters).  Leading whitespace is ignored.
+
+If the variable C<selected_scheme> is defined and I<no> collection
+variables at all are defined, then the collections required by the
+specified scheme (which might change over time) are installed, without
+explicitly listing them.  This eases maintenance of profile files.  If
+any collections are specified in a profile, though, then all desired
+collections must be given explicitly.
+
+For example, a line 
+
+  selected_scheme scheme-small
+
+along with definitions for the installation directories (given below
+under "path options") suffices to install the "small" scheme with all
+default options.  The schemes are described in the C<S> menu in the
+text installer, or equivalent.
+
+Besides C<selected_scheme>, here is the list of variable names supported
+in a profile:
+
+=item B<collection options> (prefix C<collection->)
+
+Collections are specified with a variable name with the prefix
+C<collection-> followed by a collection name; there is no value.  For
+instance, C<collection-basic>.  The collections are described in the
+C<C> menu.
+
+Schemes and collections (and packages) are ultimately defined by the
+files in the C<tlpkg/tlpsrc/> source directory.
+
+=item B<path options>
+
+It is best to define all of these, even though they may not be used in
+the installation, so as to avoid unintentionally getting a default value
+that could cause problems later.
+
+  TEXDIR
+  TEXMFCONFIG
+  TEXMFVAR
+  TEXMFHOME
+  TEXMFLOCAL
+  TEXMFSYSCONFIG
+  TEXMFSYSVAR
+
+=item B<installer options> (prefix C<instopt_>)
+
+=over 4
+
+=item C<instopt_adjustpath> (default 0 on Unix, 1 on Windows)
+
+Adjust C<PATH> environment variable.
+
+=item C<instopt_adjustrepo> (default 1)
+
+Set remote repository to a multiplexed CTAN mirror after installation;
+see C<-repository> above.
+
+=item C<instopt_letter> (default 0)
+
+Set letter size paper as the default, instead of a4.
+
+=item C<instopt_portable> (default 0)
+
+Install for portable use, e.g., on a USB stick.
+
+=item C<instopt_write18_restricted> (default 1)
+
+Enable C<\write18> for a restricted set of programs.
+
+=back
+
+=item B<tlpdb options> (prefix C<tlpdbopt_>)
+
+The definitive list is given in C<tlpkg/TeXLive/TLConfig.pm>, in
+C<%TeXLive::TLConfig::TLPDBOptions>, together with explanations.  All
+items given there I<except> for C<tlpdbopt_location> can be specified.
+Here is the current list:
+
+  tlpdbopt_autobackup
+  tlpdbopt_backupdir
+  tlpdbopt_create_formats
+  tlpdbopt_desktop_integration
+  tlpdbopt_file_assocs
+  tlpdbopt_generate_updmap
+  tlpdbopt_install_docfiles
+  tlpdbopt_install_srcfiles
+  tlpdbopt_post_code
+  tlpdbopt_sys_bin
+  tlpdbopt_sys_info
+  tlpdbopt_sys_man
+  tlpdbopt_w32_multi_user
+
+=item B<platform options> (prefix C<binary_>)
+
+For each supported platform in TeX Live (directories under C<bin/>), the
+variable C<binary_>I<PLATFORM> can be set.  For example:
+
+  binary_x86_64-linux
+
+If no C<binary_> variable is specified, the default is whatever the
+current machine is running.
+
+=back
+
+In releases before 2017, many profile variables had different
+names (not documented here; see the C<install-tl> source).  They are
+accepted and transformed to the names given above.  When a profile is
+written, the names above are always used.
+
+For more details on all of the above options, consult the TeX Live
+installation manual, linked from L<http://tug.org/texlive/doc>.
+
 =head1 ENVIRONMENT VARIABLES
 
 For ease in scripting and debugging, C<install-tl> will look for the
-following environment variables.  They are not of interest in normal
+following environment variables.  They are not of interest for normal
 user installations.
 
 =over 4
@@ -2806,6 +2879,8 @@ for testing.
 
 =item C<TEXLIVE_INSTALL_TEXMFCONFIG>
 
+=item C<TEXLIVE_INSTALL_TEXMFVAR>
+
 =item C<TEXLIVE_INSTALL_TEXMFHOME>
 
 =item C<TEXLIVE_INSTALL_TEXMFLOCAL>
@@ -2814,12 +2889,10 @@ for testing.
 
 =item C<TEXLIVE_INSTALL_TEXMFSYSVAR>
 
-=item C<TEXLIVE_INSTALL_TEXMFVAR>
-
 Specify the respective directories.  C<TEXLIVE_INSTALL_PREFIX> defaults
 to C</usr/local/texlive>, while C<TEXLIVE_INSTALL_TEXDIR> defaults to
 the release directory within that prefix, e.g.,
-C</usr/local/texlive/2014>.  All the defaults can be seen by running the
+C</usr/local/texlive/2016>.  All the defaults can be seen by running the
 installer interactively and then typing C<D> for the directory menu.
 
 =item C<NOPERLDOC>
@@ -2835,6 +2908,8 @@ This script and its documentation were written for the TeX Live
 distribution (L<http://tug.org/texlive>) and both are licensed under the
 GNU General Public License Version 2 or later.
 
+$Id$
+
 =cut
 
 ### Local Variables: