texlive[44018] Master: install-tl doc (and ignore leading whitespace

[commits+karl at tug.org]

Revision: 44018
          http://tug.org/svn/texlive?view=revision&revision=44018
Author:   karl
Date:     2017-04-24 19:51:06 +0200 (Mon, 24 Apr 2017)
Log Message:
-----------
install-tl doc (and ignore leading whitespace in profiles)

Modified Paths:
--------------
    trunk/Master/install-tl
    trunk/Master/tlpkg/TeXLive/TLConfig.pm

Modified: trunk/Master/install-tl
===================================================================
--- trunk/Master/install-tl	2017-04-24 16:48:33 UTC (rev 44017)
+++ trunk/Master/install-tl	2017-04-24 17:51:06 UTC (rev 44018)
@@ -1835,6 +1835,7 @@
     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,23 +2436,25 @@
 =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>, to install everything, and this is highly
-recommended.
+The default is C<scheme-full>, which installs everything, and this is
+highly recommended.
 
+
 =head1 REFERENCES
 
 Post-installation configuration, package updates, and much more, are
@@ -2458,12 +2461,13 @@
 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 @@
 
 =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 @@
 
 =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 @@
 
 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 @@
 
   -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 @@
 =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,9 +2590,13 @@
 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>
 
 In GUI mode, this switch makes C<tlmgr> report any missing, or more
@@ -2603,7 +2611,7 @@
 
 =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 @@
 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 @@
 
 =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,115 +2686,174 @@
 (hardware/operating system) combination to standard output, and exit.
 C<-print-arch> is a synonym.
 
-=item B<-profile> I<profile>
+=item B<-profile> I<profile_file>
 
-Load the file I<profile> and do the installation with no user
-interaction, that is, a batch (unattended) install.
+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>
+
+Omit normal informational messages.
+
+=item B<-scheme> I<scheme>
+
+Schemes are the highest level of package grouping in TeX Live; the
+default is to use the C<full> scheme, which includes everything.  This
+option overrides that default.  You can change the scheme again before
+the actual installation with the usual menu.  The I<scheme> argument may
+optionally have a prefix C<scheme->.  The list of supported scheme names
+depends on what your package repository provides; see the interactive
+menu list.
+
+=item B<-v>
+
+Include verbose debugging messages; repeat for maximum debugging: C<-v
+-v>.  (Further repeats are accepted but ignored.)
+
+=item B<-version>, B<--version>
+
+Output version information and exit.  If C<-v> has also been given the
+revisions of the used modules are reported, too.
+
+=back
+
+
+=head1 PROFILES
+
 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.
+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.
 
-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.
+Within a profile file, each line consists of
 
-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.
+I<variable> [I<value>]
 
-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.
+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.
 
-=over 8
+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.
 
-=item B<installer options> (those with prefix C<instopt_>)
+For example, a line 
 
-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).
+  selected_scheme scheme-small
 
-=item B<tlpdb options> (those with prefix C<tlpdbopt_>)
+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.
 
-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:
+Besides C<selected_scheme>, here is the list of variable names supported
+in a profile:
 
-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<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>
 
-C<TEXDIR>, C<TEXMFHOME>, C<TEXMFCONFIG>, C<TEXMFSYSCONFIG>,
-C<TEXMFVAR>, C<TEXMFSYSVAR>, C<TEXMFLOCAL>
+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.
 
-=item B<architecture selection options> (those starting with C<binary_>)
+  TEXDIR
+  TEXMFCONFIG
+  TEXMFVAR
+  TEXMFHOME
+  TEXMFLOCAL
+  TEXMFSYSCONFIG
+  TEXMFSYSVAR
 
-For every supported architecture of TeX Live (directories under
-C<bin/>), the key C<binary_ARCH> can be set. 
+=item B<installer options> (prefix C<instopt_>)
 
-Example: C<binary_x86_64-linux>
+=over 4
 
-=back
+=item C<instopt_adjustpath> (default 0 on Unix, 1 on Windows)
 
-=item B<-init-from-profile> I<profile>
+Adjust C<PATH> environment variable.
 
-Similar to B<-profile>, but merely initializes the installation
-configuration from I<profile> and then starts the interactive session.
+=item C<instopt_adjustrepo> (default 1)
 
-=item B<-q>
+Set remote repository to a multiplexed CTAN mirror after installation;
+see C<-repository> above.
 
-Omit normal informational messages.
+=item C<instopt_letter> (default 0)
 
-=item B<-scheme> I<scheme>
+Set letter size paper as the default, instead of a4.
 
-Schemes are the highest level of package grouping in TeX Live; the
-default is to use the C<full> scheme, which includes everything.  This
-option overrides that default.  You can change the scheme again before
-the actual installation with the usual menu.  The I<scheme> argument may
-optionally have a prefix C<scheme->.  The list of supported scheme names
-depends on what your package repository provides; see the interactive
-menu list.
+=item C<instopt_portable> (default 0)
 
-=item B<-v>
+Install for portable use, e.g., on a USB stick.
 
-Include verbose debugging messages; repeat for maximum debugging, as in
-C<-v -v>.  (Further repeats are accepted but ignored.)
+=item C<instopt_write18_restricted> (default 1)
 
-=item B<-version>, B<--version>
+Enable C<\write18> for a restricted set of programs.
 
-Output version information and exit.  If C<-v> has also been given the
-revisions of the used modules are reported, too.
+=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 @@
 
 =item C<TEXLIVE_INSTALL_TEXMFCONFIG>
 
+=item C<TEXLIVE_INSTALL_TEXMFVAR>
+
 =item C<TEXLIVE_INSTALL_TEXMFHOME>
 
 =item C<TEXLIVE_INSTALL_TEXMFLOCAL>
@@ -2814,12 +2889,10 @@
 
 =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 @@
 distribution (L<http://tug.org/texlive>) and both are licensed under the
 GNU General Public License Version 2 or later.
 
+$Id$
+
 =cut
 
 ### Local Variables:

Modified: trunk/Master/tlpkg/TeXLive/TLConfig.pm
===================================================================
--- trunk/Master/tlpkg/TeXLive/TLConfig.pm	2017-04-24 16:48:33 UTC (rev 44017)
+++ trunk/Master/tlpkg/TeXLive/TLConfig.pm	2017-04-24 17:51:06 UTC (rev 44018)
@@ -149,6 +149,9 @@
   "file_assocs" =>
     [ "n:0..2", 1, "fileassocs",
       "Change file associations (w32)" ],
+  "generate_updmap" =>
+    [ "b", 0, "generate_updmap",
+      "Run tlmgr generate updmap after maps have changed" ],
   "install_docfiles" =>
     [ "b", 1, "docfiles",
       "Install documentation files" ],
@@ -173,9 +176,6 @@
   "w32_multi_user" =>
     [ "b", 1, "multiuser",
       "Install for all users (w32)" ],
-  "generate_updmap" =>
-    [ "b", 0, "generate_updmap",
-      "Run tlmgr generate updmap after maps have changed" ],
 );