texlive[53213] trunk: doc: better describe config file special
commits+karl at tug.org
commits+karl at tug.org
Sun Dec 22 23:22:33 CET 2019
Revision: 53213
http://tug.org/svn/texlive?view=revision&revision=53213
Author: karl
Date: 2019-12-22 23:22:33 +0100 (Sun, 22 Dec 2019)
Log Message:
-----------
doc: better describe config file special characters; plus other typos, url fixes, mention gpg, etc., from Takuto in texlive-en.tex
Modified Paths:
--------------
trunk/Build/source/doc/ChangeLog
trunk/Build/source/doc/build-tools.txt
trunk/Build/source/doc/tlbuild.info
trunk/Build/source/texk/kpathsea/ChangeLog
trunk/Build/source/texk/kpathsea/doc/kpathsea.info
trunk/Build/source/texk/kpathsea/doc/kpathsea.texi
trunk/Master/texmf-dist/doc/texlive/texlive-en/.dict.pws
trunk/Master/texmf-dist/doc/texlive/texlive-en/Makefile
trunk/Master/texmf-dist/doc/texlive/texlive-en/tex-live.sty
trunk/Master/texmf-dist/doc/texlive/texlive-en/texlive-en.tex
trunk/Master/texmf-dist/scripts/texlive/tlmgr.pl
Modified: trunk/Build/source/doc/ChangeLog
===================================================================
--- trunk/Build/source/doc/ChangeLog 2019-12-22 22:19:32 UTC (rev 53212)
+++ trunk/Build/source/doc/ChangeLog 2019-12-22 22:22:33 UTC (rev 53213)
@@ -1,3 +1,7 @@
+2019-12-22 Karl Berry <karl at freefriends.org>
+
+ * build-tools.txt: bison 3.5.
+
2019-08-11 Karl Berry <karl at freefriends.org>
* tlbuild.texi (Build one package): rm sources to build without C++11.
Modified: trunk/Build/source/doc/build-tools.txt
===================================================================
--- trunk/Build/source/doc/build-tools.txt 2019-12-22 22:19:32 UTC (rev 53212)
+++ trunk/Build/source/doc/build-tools.txt 2019-12-22 22:22:33 UTC (rev 53213)
@@ -1,6 +1,6 @@
autoconf (GNU Autoconf) 2.69
automake (GNU automake) 1.16.1
-bison (GNU Bison) 3.4.2
+bison (GNU Bison) 3.5
flex 2.6.0
ltmain.sh (GNU libtool) 2.4.6
m4 (GNU M4) 1.4.18
Modified: trunk/Build/source/doc/tlbuild.info
===================================================================
(Binary files differ)
Modified: trunk/Build/source/texk/kpathsea/ChangeLog
===================================================================
--- trunk/Build/source/texk/kpathsea/ChangeLog 2019-12-22 22:19:32 UTC (rev 53212)
+++ trunk/Build/source/texk/kpathsea/ChangeLog 2019-12-22 22:22:33 UTC (rev 53213)
@@ -1,7 +1,13 @@
+2019-12-22 Karl Berry <karl at freefriends.org>
+
+ * doc/kpathsea.texi (Path searching): mention translations for TL.
+ (Config files): distinguish special characters at different levels.
+ (Filename database): don't mention talking about 8.3 filenames.
+
2019-12-16 Karl Berry <karl at freefriends.org>
* texmf.cnf (glob_str_size): increase from 20,000 to 200,000
- for bibtex-bigauth.test (q.v.).
+ for web2c/tests/bibtex-bigauth.test (q.v.).
(ent_str_size, max_strings.bibtex*): increase these while we're here.
2019-11-03 Karl Berry <karl at tug.org>
Modified: trunk/Build/source/texk/kpathsea/doc/kpathsea.info
===================================================================
--- trunk/Build/source/texk/kpathsea/doc/kpathsea.info 2019-12-22 22:19:32 UTC (rev 53212)
+++ trunk/Build/source/texk/kpathsea/doc/kpathsea.info 2019-12-22 22:22:33 UTC (rev 53213)
@@ -1,4 +1,4 @@
-This is kpathsea.info, produced by makeinfo version 6.6 from
+This is kpathsea.info, produced by makeinfo version 6.7 from
kpathsea.texi.
This file documents the Kpathsea library for path searching.
@@ -37,7 +37,7 @@
****************
This manual documents the Kpathsea library for path searching. It
-corresponds to version 6.3.2, released in August 2019.
+corresponds to version 6.3.2, released in December 2019.
* Menu:
@@ -62,7 +62,7 @@
**************
This manual corresponds to version 6.3.2 of the Kpathsea library,
-released in August 2019.
+released in December 2019.
The library's fundamental purpose is to return a filename from a list
of directories specified by the user, similar to what shells do when
@@ -374,6 +374,11 @@
provides. For information about searching for particular file types
(e.g., TeX fonts), see the next chapter.
+ This section, with minor differences, has been translated into
+several other languages (Chinese, Spanish, Russian, Japanese, French,
+German, ...) as part of the TeX Live guide; see
+<https://tug.org/texlive/doc.html> for links.
+
* Menu:
* Searching overview:: Basic scheme for searching.
@@ -526,7 +531,7 @@
not start a comment. Examples:
% this is a comment
- var = a%b % but the value of var will be "a%b".
+ var = a%b % but the value of var will be "a%b"
* Blank lines are ignored.
@@ -534,7 +539,7 @@
the next line is appended. Whitespace at the beginning of
continuation lines is not ignored.
- * Each remaining line must look like
+ * Each remaining line will look like:
VARIABLE [. PROGNAME] [=] VALUE
@@ -550,15 +555,21 @@
flavors of TeX to have different search paths. The PROGNAME value
is used literally, without variable or other expansions.
- * VALUE may contain any characters except '%' and '@'. (These
- restrictions are only necessary because of the processing done on
- 'texmf.cnf' at build time, so you can stick those characters in
- after installation if you have to.) The '$VAR.PROG' feature is not
- available on the right-hand side; instead, you must use an
- additional variable (see below for example). A ';' in VALUE is
- translated to ':' if running under Unix; this is useful to write a
- single 'texmf.cnf' which can be used under both Unix and Windows.
+ * Considered as strings, VALUE may contain any character. However,
+ in practice most 'texmf.cnf' values are related to path expansion,
+ and since various special characters are used in expansion, such as
+ braces and commas, they cannot be used in directory names.
+ The '$VAR.PROG' feature is not available on the right-hand side;
+ instead, you must use an additional variable (see below for
+ example).
+
+ A ';' in VALUE is translated to ':' if running under Unix, in order
+ to have a single 'texmf.cnf' that can support both Unix and Windows
+ systems. This translation happens with any value, not just search
+ paths, but fortunately in practice ';' is not needed in other
+ values.
+
* All definitions are read before anything is expanded, so you can
use variables before they are defined (like Make, unlike most other
programs).
@@ -573,12 +584,12 @@
TEXINPUTS.latex2e = $latex2e_inputs
TEXINPUTS.latex = $latex2e_inputs
- This format has obvious similarities to Bourne shell scripts--change
-the comment character to '#', disallow spaces around the '=', and get
-rid of the '.NAME' convention, and it could be run through the shell.
-However, there seemed little advantage in this, since all the
-information would have to passed back to Kpathsea and parsed there
-anyway, since the 'sh' process couldn't affect its parent's environment.
+ This format has some similarity to Bourne shell scripts--change the
+comment character to '#', disallow spaces around the '=', and get rid of
+the '.NAME' convention, and it could be run through the shell. However,
+there seemed little advantage in this, since all the information would
+have to passed back to Kpathsea and parsed there anyway, since the 'sh'
+process couldn't affect its parent's environment.
The combination of spaces being ignored before the '.' of a program
name qualifer and the optional '=' for the assignment has an unexpected
@@ -590,6 +601,15 @@
special character. The simplest way to avoid the problem is to use the
'='.
+ Exactly when a character will be considered special or act as itself
+depends on the context in which it is used. The rules are inherent in
+the multiple levels of interpretation of the configuration (parsing,
+expansion, search, ...) and so cannot be concisely stated,
+unfortunately. There is no general escape mechanism; in particular, '\'
+is not an "escape character" in 'texmf.cnf' files. When it comes
+choosing directory names for installation, it is safest to avoid them
+all.
+
The implementation of all this is in 'kpathsea/cnf.c'.
@@ -815,7 +835,7 @@
subdirectory '.../pk', even if it is a leaf, are checked. The reason
cannot be explained without reference to the implementation, so read
'kpathsea/elt-dirs.c' (search for 'may descend') if you are curious.
-And if you can find a way to _solve_ the problem, please let me know.
+And if you find a way to solve the problem, please let me know.
Subdirectory expansion is implemented in the source file
'kpathsea/elt-dirs.c'.
@@ -975,7 +995,7 @@
Kpathsea goes to some lengths to minimize disk accesses for searches
(*note Subdirectory expansion::). Nevertheless, in practice searching
-each possible directory in typical TeX installations takes an
+every possible directory in typical TeX installations takes an
excessively long time.
Therefore, Kpathsea can use an externally-built "filename database"
@@ -983,8 +1003,7 @@
to exhaustively search the disk.
A second database file 'aliases' allows you to give additional names
-to the files listed in 'ls-R'. This can be helpful to adapt to "8.3"
-filename conventions in source files.
+to the files listed in 'ls-R'.
The 'ls-R' and 'aliases' features are implemented in the source file
'kpathsea/db.c'.
@@ -3154,6 +3173,7 @@
(line 195)
* .pro: Supported file formats.
(line 169)
+* .PROGNAME qualifier in texmf.cnf: Config files. (line 50)
* .rhosts, writable by TeX: Security. (line 10)
* .ris: Supported file formats.
(line 173)
@@ -3191,6 +3211,8 @@
* 8.3 filenames, using: mktex configuration. (line 68)
* : may not be :: Searching overview. (line 13)
* :: expansion: Default expansion. (line 6)
+* ; translated to : in texmf.cnf: Config files. (line 66)
+* = omitted in texmf.cnf and misparsing: Config files. (line 93)
* \, line continuation in texmf.cnf: Config files. (line 37)
* \openin: Searching overview. (line 31)
* \special, suppressing warnings about: Suppressing warnings.
@@ -3267,7 +3289,7 @@
(line 46)
* cmr10, as fallback font: Fallback font. (line 15)
* cmr10.vf: Searching overview. (line 31)
-* cnf.c: Config files. (line 97)
+* cnf.c: Config files. (line 112)
* cnf.h: Programming with config files.
(line 27)
* comments, in fontmap files: Fontmap. (line 27)
@@ -3296,7 +3318,7 @@
* config.status: Bug checklist. (line 27)
* configuration bugs: Bug checklist. (line 27)
* configuration file, source for path: Path sources. (line 20)
-* configuration files as shell scripts.: Config files. (line 80)
+* configuration files as shell scripts.: Config files. (line 86)
* configuration of mktex scripts: mktex configuration. (line 6)
* configure options for mktex scripts: mktex configuration. (line 12)
* context diff: Bug checklist. (line 52)
@@ -3711,7 +3733,7 @@
* setgid scripts: Security. (line 40)
* SFDFONTS: Supported file formats.
(line 177)
-* shell scripts as configuration files: Config files. (line 80)
+* shell scripts as configuration files: Config files. (line 86)
* shell variables: Variable expansion. (line 17)
* shell_escape, example for code: Programming with config files.
(line 10)
@@ -3863,6 +3885,8 @@
* tolerance for glyph lookup: Basic glyph lookup. (line 15)
* trailing / in home directory: Tilde expansion. (line 19)
* trailing colons: Default expansion. (line 6)
+* translations, of path searching description: Path searching.
+ (line 10)
* TRFONTS: Supported file formats.
(line 203)
* trick for detecting leaf directories: Subdirectory expansion.
@@ -3931,61 +3955,66 @@
Tag Table:
Node: Top1480
-Node: Introduction2261
-Node: History4332
-Node: unixtex.ftp8928
-Node: Security10353
-Node: TeX directory structure12857
-Node: Path searching16905
-Node: Searching overview17632
-Node: Path sources21451
-Node: Config files22677
-Node: Path expansion27283
-Node: Default expansion28236
-Node: Variable expansion30306
-Node: Tilde expansion31707
-Node: Brace expansion32687
-Node: KPSE_DOT expansion33626
-Node: Subdirectory expansion34139
-Node: Casefolding search36493
-Node: Casefolding rationale37262
-Node: Casefolding examples38601
-Node: Filename database43651
-Node: ls-R44709
-Node: Filename aliases48385
-Node: Database format49563
-Node: Invoking kpsewhich50576
-Node: Path searching options51531
-Node: Specially-recognized files61129
-Node: Auxiliary tasks62484
-Node: Standard options66209
-Node: TeX support66565
-Node: Supported file formats67919
-Node: File lookup75584
-Node: Glyph lookup77333
-Node: Basic glyph lookup78457
-Node: Fontmap79337
-Node: Fallback font81866
-Node: Suppressing warnings82778
-Node: mktex scripts83905
-Node: mktex configuration85120
-Node: mktex script names90923
-Node: mktex script arguments92309
-Node: Programming93188
-Node: Programming overview93761
-Node: Calling sequence96622
-Node: Program-specific files103154
-Node: Programming with config files104177
-Node: Reporting bugs105764
-Node: Bug checklist106442
-Node: Mailing lists109914
-Node: Debugging110589
-Node: Logging115666
-Node: Common problems117533
-Node: Unable to find files118010
-Node: Slow path searching120420
-Node: Unable to generate fonts121795
-Node: TeX or Metafont failing124266
-Node: Index125468
+Node: Introduction2263
+Node: History4336
+Node: unixtex.ftp8932
+Node: Security10357
+Node: TeX directory structure12861
+Node: Path searching16909
+Node: Searching overview17867
+Node: Path sources21686
+Node: Config files22912
+Node: Path expansion28175
+Node: Default expansion29128
+Node: Variable expansion31198
+Node: Tilde expansion32599
+Node: Brace expansion33579
+Node: KPSE_DOT expansion34518
+Node: Subdirectory expansion35031
+Node: Casefolding search37379
+Node: Casefolding rationale38148
+Node: Casefolding examples39487
+Node: Filename database44537
+Node: ls-R45519
+Node: Filename aliases49195
+Node: Database format50373
+Node: Invoking kpsewhich51386
+Node: Path searching options52341
+Node: Specially-recognized files61939
+Node: Auxiliary tasks63294
+Node: Standard options67019
+Node: TeX support67375
+Node: Supported file formats68729
+Node: File lookup76394
+Node: Glyph lookup78143
+Node: Basic glyph lookup79267
+Node: Fontmap80147
+Node: Fallback font82676
+Node: Suppressing warnings83588
+Node: mktex scripts84715
+Node: mktex configuration85930
+Node: mktex script names91733
+Node: mktex script arguments93119
+Node: Programming93998
+Node: Programming overview94571
+Node: Calling sequence97432
+Node: Program-specific files103964
+Node: Programming with config files104987
+Node: Reporting bugs106574
+Node: Bug checklist107252
+Node: Mailing lists110724
+Node: Debugging111399
+Node: Logging116476
+Node: Common problems118343
+Node: Unable to find files118820
+Node: Slow path searching121230
+Node: Unable to generate fonts122605
+Node: TeX or Metafont failing125076
+Node: Index126278
End Tag Table
+
+
+Local Variables:
+coding: utf-8
+End:
Modified: trunk/Build/source/texk/kpathsea/doc/kpathsea.texi
===================================================================
--- trunk/Build/source/texk/kpathsea/doc/kpathsea.texi 2019-12-22 22:19:32 UTC (rev 53212)
+++ trunk/Build/source/texk/kpathsea/doc/kpathsea.texi 2019-12-22 22:22:33 UTC (rev 53213)
@@ -3,7 +3,7 @@
@settitle Kpathsea: A library for path searching
@set version 6.3.2
- at set month-year August 2019
+ at set month-year December 2019
@copying
This file documents the Kpathsea library for path searching.
@@ -445,6 +445,12 @@
provides. For information about searching for particular file types
(e.g., @TeX{} fonts), see the next chapter.
+ at cindex translations, of path searching description
+This section, with minor differences, has been translated into several
+other languages (Chinese, Spanish, Russian, Japanese, French, German,
+ at dots{}) as part of the @TeX{} Live guide; see
+ at url{https://tug.org/texlive/doc.html} for links.
+
@menu
* Searching overview:: Basic scheme for searching.
* Path sources:: Where search paths can be defined.
@@ -652,7 +658,7 @@
@example
% this is a comment
-var = a%b % but the value of var will be "a%b".
+var = a%b % but the value of var will be "a%b"
@end example
@item
@@ -668,7 +674,7 @@
the next line is appended. Whitespace at the beginning of continuation
lines is not ignored.
- at item Each remaining line must look like
+ at item Each remaining line will look like:
@example
@var{variable} @r{[}. @var{progname}@r{]} @r{[}=@r{]} @var{value}
@@ -681,6 +687,7 @@
The @var{variable} name may contain any character other than whitespace,
@samp{=}, or @samp{.}, but sticking to @samp{A-Za-z_} is safest.
+ at kindex . at var{progname} @r{qualifier in @file{texmf.cnf}}
@item If @samp{. at var{progname}} is present (preceding spaces are
ignored), the definition only applies if the program that is running
is named (i.e., the last component of @code{argv[0]} is)
@@ -691,16 +698,22 @@
@item
@cindex right-hand side of variable assignments
- at var{value} may contain any characters except @samp{%} and @samp{@@}.
-(These restrictions are only necessary because of the processing done
-on @file{texmf.cnf} at build time, so you can stick those characters
-in after installation if you have to.) The
- at samp{$@var{var}. at var{prog}} feature is not available on the
+Considered as strings, @var{value} may contain any character.
+However, in practice most @file{texmf.cnf} values are related to path
+expansion, and since various special characters are used in expansion,
+such as braces and commas, they cannot be used in directory names.
+
+The @samp{$@var{var}. at var{prog}} feature is not available on the
right-hand side; instead, you must use an additional variable (see
-below for example). A @samp{;} in @var{value} is translated to
- at samp{:} if running under Unix; this is useful to write a single
- at file{texmf.cnf} which can be used under both Unix and Windows.
+below for example).
+ at kindex ; @r{translated to @samp{:} in @file{texmf.cnf}}
+A @samp{;} in @var{value} is translated to @samp{:} if running under
+Unix, in order to have a single @file{texmf.cnf} that can support both
+Unix and Windows systems. This translation happens with any value, not
+just search paths, but fortunately in practice @samp{;} is not needed
+in other values.
+
@item All definitions are read before anything is expanded, so you can
use variables before they are defined (like Make, unlike most other
programs).
@@ -721,14 +734,15 @@
@cindex shell scripts as configuration files
@cindex configuration files as shell scripts.
-This format has obvious similarities to Bourne shell scripts---change
-the comment character to @code{#}, disallow spaces around the
- at code{=}, and get rid of the @code{. at var{name}} convention, and it
-could be run through the shell. However, there seemed little
-advantage in this, since all the information would have to passed back
-to Kpathsea and parsed there anyway, since the @code{sh} process
-couldn't affect its parent's environment.
+This format has some similarity to Bourne shell scripts---change the
+comment character to @code{#}, disallow spaces around the @code{=},
+and get rid of the @code{. at var{name}} convention, and it could be run
+through the shell. However, there seemed little advantage in this,
+since all the information would have to passed back to Kpathsea and
+parsed there anyway, since the @code{sh} process couldn't affect its
+parent's environment.
+ at kindex = @r{omitted in @file{texmf.cnf} and misparsing}
The combination of spaces being ignored before the @code{.} of a
program name qualifer and the optional @samp{=} for the assignment has
an unexpected consequence: if the value begins with a literal @samp{.}
@@ -739,6 +753,15 @@
name contains a path separator or other special character. The
simplest way to avoid the problem is to use the @code{=}.
+Exactly when a character will be considered special or act as itself
+depends on the context in which it is used. The rules are inherent in
+the multiple levels of interpretation of the configuration (parsing,
+expansion, search, @dots{}) and so cannot be concisely stated,
+unfortunately. There is no general escape mechanism; in particular,
+ at samp{\} is not an ``escape character'' in @file{texmf.cnf} files.
+When it comes choosing directory names for installation, it is safest to
+avoid them all.
+
@flindex cnf.c
The implementation of all this is in @file{kpathsea/cnf.c}.
@@ -1024,11 +1047,11 @@
Unfortunately, in some cases files in leaf directories are
@code{stat}'d: if the path specification is, say,
@samp{$TEXMF/fonts//pk//}, then files in a subdirectory
- at samp{@dots{}/pk}, even if it is a leaf, are checked. The reason cannot
-be explained without reference to the implementation, so read
+ at samp{@dots{}/pk}, even if it is a leaf, are checked. The reason
+cannot be explained without reference to the implementation, so read
@file{kpathsea/elt-dirs.c} (search for @samp{may descend}) if you are
-curious. And if you can find a way to @emph{solve} the problem, please
-let me know.
+curious. And if you find a way to solve the problem, please let me
+know.
@flindex elt-dirs.c
Subdirectory expansion is implemented in the source file
@@ -1217,7 +1240,7 @@
Kpathsea goes to some lengths to minimize disk accesses for searches
(@pxref{Subdirectory expansion}). Nevertheless, in practice searching
-each possible directory in typical @TeX{} installations takes an
+every possible directory in typical @TeX{} installations takes an
excessively long time.
Therefore, Kpathsea can use an externally-built @dfn{filename
@@ -1225,8 +1248,7 @@
avoiding the need to exhaustively search the disk.
A second database file @file{aliases} allows you to give additional
-names to the files listed in @file{ls-R}. This can be helpful to adapt
-to ``8.3'' filename conventions in source files.
+names to the files listed in @file{ls-R}.
The @file{ls-R} and @file{aliases} features are implemented in the
source file @file{kpathsea/db.c}.
Modified: trunk/Master/texmf-dist/doc/texlive/texlive-en/.dict.pws
===================================================================
--- trunk/Master/texmf-dist/doc/texlive/texlive-en/.dict.pws 2019-12-22 22:19:32 UTC (rev 53212)
+++ trunk/Master/texmf-dist/doc/texlive/texlive-en/.dict.pws 2019-12-22 22:22:33 UTC (rev 53213)
@@ -387,6 +387,7 @@
luatex
lz
lzma
+macOS
macos
makeindex
manpages
Modified: trunk/Master/texmf-dist/doc/texlive/texlive-en/Makefile
===================================================================
--- trunk/Master/texmf-dist/doc/texlive/texlive-en/Makefile 2019-12-22 22:19:32 UTC (rev 53212)
+++ trunk/Master/texmf-dist/doc/texlive/texlive-en/Makefile 2019-12-22 22:22:33 UTC (rev 53213)
@@ -41,3 +41,7 @@
cat texlive-en.tex \
| aspell list --mode=tex --add-extra-dicts=`pwd`/.dict.pws \
| sort -f -u
+
+svr:
+ svn revert texlive-??.css texlive-??.html texlive-??.pdf
+ svn status
Modified: trunk/Master/texmf-dist/doc/texlive/texlive-en/tex-live.sty
===================================================================
--- trunk/Master/texmf-dist/doc/texlive/texlive-en/tex-live.sty 2019-12-22 22:19:32 UTC (rev 53212)
+++ trunk/Master/texmf-dist/doc/texlive/texlive-en/tex-live.sty 2019-12-22 22:22:33 UTC (rev 53213)
@@ -33,13 +33,13 @@
\RequirePackage{fancyvrb}
\DefineVerbatimEnvironment{verbatim}{Verbatim}{fontsize=\normalsize}
+\DefineVerbatimEnvironment{sverbatim}{Verbatim}{fontsize=\small}
\DefineVerbatimEnvironment{fverbatim}{Verbatim}{fontsize=\footnotesize}
-\DefineVerbatimEnvironment{sverbatim}{Verbatim}{fontsize=\small}
\DefineVerbatimEnvironment{boxedverbatim}
{Verbatim}{fontsize=\footnotesize,frame=single}
\DefineVerbatimEnvironment{Verbatim}{Verbatim}{fontsize=\normalsize}
-\def\verbatiminput#1{\VerbatimInput[fontsize=\scriptsize]{#1}}
-\def\boxedverbatiminput#1{\VerbatimInput[frame=single,fontsize=\scriptsize]{#1}}
+\def\verbatiminput#1{\VerbatimInput[fontsize=\small]{#1}}
+\def\boxedverbatiminput#1{\VerbatimInput[frame=single,fontsize=\footnotesize]{#1}}
\def\listinginput#1#2{\VerbatimInput[fontsize=\scriptsize,firstnumber=#1,numbers=left]{#2}}
\MakeShortVerb\|
%
Modified: trunk/Master/texmf-dist/doc/texlive/texlive-en/texlive-en.tex
===================================================================
--- trunk/Master/texmf-dist/doc/texlive/texlive-en/texlive-en.tex 2019-12-22 22:19:32 UTC (rev 53212)
+++ trunk/Master/texmf-dist/doc/texlive/texlive-en/texlive-en.tex 2019-12-22 22:22:33 UTC (rev 53213)
@@ -17,7 +17,7 @@
\url{https://tug.org/texlive/}
}
-\date{August 2019}
+\date{December 2019}
\begin{document}
\maketitle
@@ -124,6 +124,13 @@
variety of ways. Again, processing unknown documents in a new
subdirectory is the safest bet.
+Another aspect of security is ensuring that downloaded material has not
+been changed from what was created. The \prog{tlmgr} program
+(section~\ref{sec:tlmgr}) will automatically perform cryptographic
+verification on downloads if the \prog{gpg} (GNU Privacy Guard) program
+is available. It is not distributed as part of \TL, but see
+\url{https://texlive.info/tlgpg/} for information about \prog{gpg} if
+need be.
\subsection{Getting help}
\label{sec:help}
@@ -252,10 +259,6 @@
installation, and special support for Windows.
\end{ttdescription}
-In addition to the directories above, the installation scripts and
-\filename{README} files (in various languages) are at the top level of
-the distribution.
-
For documentation, the comprehensive links in the top-level file
\OnCD{doc.html} may be helpful. The documentation for nearly everything
(packages, formats, fonts, program manuals, man pages, Info files) is in
@@ -312,10 +315,10 @@
The expansion of this variable dynamically adjusts for each user to
their own individual directory.
\item [TEXMFVAR] The (personal) tree used by \verb+texconfig+,
- \verb+updmap+ and \verb+fmtutil+ to store (cached) runtime data such
+ \verb+updmap-user+ and \verb+fmtutil-usr+ to store (cached) runtime data such
as format files and generated map files.
\item [TEXMFCONFIG] The (personal) tree used by the utilities
- \verb+texconfig+, \verb+updmap+, and \verb+fmtutil+ to store modified
+ \verb+texconfig+, \verb+updmap-sys+, and \verb+fmtutil-sys+ to store modified
configuration data.
\item [TEXMFCACHE] The tree(s) used by \ConTeXt\ MkIV and Lua\LaTeX\
to store (cached) runtime data; defaults to \code{TEXMFSYSVAR},
@@ -385,7 +388,7 @@
\prog{etex}, \prog{latex}, \prog{pdflatex}. Its web site is
\url{http://www.pdftex.org/}. See
\OnCD{texmf-dist/doc/pdftex/manual/pdftex-a.pdf} for the manual, and
-\OnCD{texmf-dist/doc/pdftex/manual/samplepdf/samplepdf.tex} for example
+\OnCD{texmf-dist/doc/pdftex/samplepdf/samplepdf.tex} for example
usage of some of its features.
\item [Lua\TeX] is the designated successor of pdf\TeX,
@@ -874,12 +877,12 @@
short) list of allowed programs is given in the \filename{texmf.cnf}.
See the 2010 news (section~\ref{sec:2010news}) for more details.
-\item[create format files:] Although unnecessary format files
+\item[create all format files:] Although unnecessary format files
take time to generate and disk space to store, it is still recommended
to leave this option checked: if you don't, then format files will be
generated in people's private \dirname{TEXMFVAR} tree as they are
needed. In that location, they will not be updated automatically if
- (say) binaries or hyphenation patterns are updated in the
+ (for example) core packages or hyphenation patterns are updated in the
installation, and thus you could end up with incompatible format files.
\item[install font/macro \ldots\ tree:] Download/install the
@@ -897,7 +900,8 @@
your system with this option, e.g., by specifying system directories.
The safest and recommended approach is to leave the option unchecked.
-\item[after installation \ldots\ \CTAN:] When installing from \DVD, this
+\item[after install, set CTAN as source for package updates:]
+ When installing from \DVD, this
option is enabled by default, since usually one wants to take any
subsequent package updates from the \CTAN\ area that is updated
throughout the year. The only likely reason to disable it is if you
@@ -1038,7 +1042,7 @@
For Bourne-compatible shells such as \prog{bash}, and using Intel x86
GNU/Linux and a default directory setup as an example, the file to edit
might be \filename{$HOME/.profile} (or another file sourced by
-\filename{.profile}, and the lines to add would look like this:
+\filename{.profile}), and the lines to add would look like this:
\begin{sverbatim}
PATH=/usr/local/texlive/2019/bin/x86_64-linux:$PATH; export PATH
@@ -1240,7 +1244,7 @@
One thing you may immediately be looking for is a front-end with which
to edit files. \TL{} installs \TeX{}works
(\url{http://tug.org/texworks}) on Windows (only), and Mac\TeX\ installs
-TeXShop (\url{http://pages.uoregon.edu/koch/texshop}. On other Unix
+TeXShop (\url{https://pages.uoregon.edu/koch/texshop)}. On other Unix
systems, it's left up to you to choose an editor. There are many
choices available, some of which are listed in the next section; see
also \url{http://tug.org/interest.html#editors}. Any plain text editor
@@ -1312,7 +1316,7 @@
Neither \cmdname{gv} nor \cmdname{xpdf} are included in \TL{}, so
you must install them separately. See
\url{http://www.gnu.org/software/gv} and
-\url{http://www.foolabs.com/xpdf}, respectively. There are plenty
+\url{http://www.xpdfreader.com}, respectively. There are plenty
of other PDF viewers, too. For Windows, we recommend trying Sumatra
PDF (\url{https://www.sumatrapdfreader.org/free-pdf-reader.html}).
@@ -1358,9 +1362,9 @@
\item[Ghostscript] \url{https://ghostscript.com/}
\item[Perl] \url{http://www.perl.org/} with
supplementary packages from CPAN, \url{http://www.cpan.org/}
-\item[ImageMagick] \url{http://www.imagemagick.com}, for graphics
+\item[ImageMagick] \url{https://imagemagick.org}, for graphics
processing and conversion
-\item[NetPBM] \url{http://netpbm.sourceforge.net/}, also for graphics.
+\item[NetPBM] \url{http://netpbm.sourceforge.net}, also for graphics.
\item[\TeX-oriented editors] There is a wide choice, and it is a matter of the
user's taste. Here is a selection in alphabetical order (a few
@@ -1551,22 +1555,21 @@
of anyone used to its interface, but we recommend using \prog{tlmgr}
nowadays.
-\subsection{Current \GUI{} interfaces for \cmdname{tlmgr}}
+\subsection{\GUI{} interfaces for \cmdname{tlmgr}}
-\TL{} contains several \GUI s for
-\prog{tlmgr}. Figure~\ref{fig:tlshell} shows \cmdname{tlshell},
-which is written in Tcl/Tk and works out of the box under Windows
-and \MacOSX. Figure~\ref{fig:tlcockpit} shows \prog{tlcockpit},
-which requires Java version~8 or higher and JavaFX. Both are
-separate packages.
+\TL{} contains several \GUI{} front-ends for \prog{tlmgr}. Two notable
+ones: (1)~Figure~\ref{fig:tlshell} shows \cmdname{tlshell}, which is
+written in Tcl/Tk and runs out of the box under Windows and \MacOSX;
+(2)~Figure~\ref{fig:tlcockpit} shows \prog{tlcockpit}, which requires
+Java version~8 or higher and JavaFX. Both are separate packages.
-\prog{tlmgr} itself can also be run in \GUI{} mode
-(figure~\ref{fig:tlmgr-gui}) with
+\prog{tlmgr} also has a native \GUI{} mode (shown in
+figure~\ref{fig:tlmgr-gui}), which is started with:
\begin{alltt}
> \Ucom{tlmgr -gui}
\end{alltt}
-This \GUI\ extension requires Perl/Tk, which module is no longer
-included in \TL's Perl distribution for Windows.
+However, this \GUI\ extension requires Perl/Tk, which module is no
+longer included in \TL's Perl distribution for Windows.
\subsection{Sample \cmdname{tlmgr} command-line invocations}
@@ -1865,10 +1868,14 @@
All programs honor these standard \GNU options:
\begin{ttdescription}
\item[-{}-help] print basic usage summary.
-\item[-{}-verbose] print detailed progress report.
\item[-{}-version] print version information, then exit.
\end{ttdescription}
+And most also honor:
+\begin{ttdescription}
+\item[-{}-verbose] print detailed progress report.
+\end{ttdescription}
+
For locating files the \Webc{} programs use the path searching library
\KPS{} (\url{http://tug.org/kpathsea}). This library uses a combination
of environment variables and configuration files to optimize searching
@@ -1984,7 +1991,8 @@
\begin{itemize*}
\item
- Comments start with \code{\%} and continue to the end of the line.
+ Comments start with \code{\%}, either at the beginning of a line or
+ preceded by whitespace, and continue to the end of the line.
\item
Blank lines are ignored.
\item
@@ -1992,10 +2000,8 @@
i.e., the next line is appended. Whitespace at the beginning of
continuation lines is not ignored.
\item
- Each remaining line has the form:
-\begin{alltt}
- \var{variable}[.\var{progname}] [=] \var{value}
-\end{alltt}%
+ Each remaining line has the form:\\
+ \hspace*{2em}\texttt{\var{variable}[.\var{progname}] [=] \var{value}}\\[1pt]
where the \samp{=} and surrounding whitespace are optional.
(But if \var{value} begins with \samp{.}, it is simplest to use the
\samp{=} to avoid the period being interpreted as the program name
@@ -2010,13 +2016,21 @@
\texttt{\var{progname}} or \texttt{\var{progname}.exe}. This allows
different flavors of \TeX{} to have different search paths, for
example.
-\item \var{value} may contain any characters except
- \code{\%} and \samp{@}. The
- \code{\$\var{var}.\var{prog}} feature is not available on the
- right-hand side; instead, you must use an additional variable. A
- \samp{;}\ in \var{value} is translated to \samp{:}\ if
- running under Unix; this is useful to be able to have a single
- \file{texmf.cnf} for Unix, MS-DOS and Windows systems.
+\item Considered as strings, \var{value} may contain any character.
+ However, in practice most \file{texmf.cnf} values are related to path
+ expansion, and since various special characters are used in expansion
+ (see section~\ref{sec:cnf-special-chars}), such as braces and commas,
+ they cannot be used in directory names.
+
+ A \samp{;} in \var{value} is translated to \samp{:} if running under
+ Unix, in order to have a single \file{texmf.cnf} that can support both
+ Unix and Windows systems. This translation happens with any value, not
+ just search paths, but fortunately in practice \samp{;} is not needed
+ in other values.
+
+ The \code{\$\var{var}.\var{prog}} feature is not available on the
+ right-hand side; instead, you must use an additional variable.
+
\item
All definitions are read before anything is expanded, so
variables can be referenced before they are defined.
@@ -2033,10 +2047,9 @@
\subsubsection{Path expansion}
\label{sec:path-expansion}
-
\KPS{} recognizes certain special characters and constructions in
search paths, similar to those available in Unix shells. As a
-general example, the complex path,
+general example, the path
\verb+~$USER/{foo,bar}//baz+, expands to all subdirectories under
directories \file{foo} and \file{bar} in \texttt{\$USER}'s home
directory that contain a directory or file \file{baz}. These
@@ -2078,12 +2091,12 @@
\verb+v{a,b}w+ expands to \verb+vaw:vbw+. Nesting is allowed.
This is used to implement multiple \TeX{} hierarchies, by
assigning a brace list to \code{\$TEXMF}.
-For example, in \file{texmf.cnf}, a definition like this
+In the distributed \file{texmf.cnf}, a definition like this
(simplified for this example) is made:
\begin{verbatim}
TEXMF = {$TEXMFVAR,$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFDIST}
\end{verbatim}
-We can then use this to define, for example, the \TeX\ input path:
+We then use this to define, for example, the \TeX\ input path:
\begin{verbatim}
TEXINPUTS = .;$TEXMF/tex//
\end{verbatim}
@@ -2090,19 +2103,14 @@
%$
which means that, after looking in the current directory, the
\code{\$TEXMFVAR/tex}, \code{\$TEXMFHOME/tex}, \code{\$TEXMFLOCAL/tex}
-and \code{\$TEXMFDIST/tex} trees \emph{only}) will be searched (the
-last two using \file{ls-R} data base files). It is a convenient
-way for running two parallel \TeX{} structures, one ``frozen'' (on a
-\CD, for instance) and the other being continuously updated with new
-versions as they become available. By using the \code{\$TEXMF}
-variable in all definitions, one is sure to always search the
-up-to-date tree first.
+and \code{\$TEXMFDIST/tex} trees will be searched (the
+last two using \file{ls-R} data base files).
\subsubsection{Subdirectory expansion}
\label{sec:subdirectory-expansion}
Two or more consecutive slashes in a path element following a directory
-\var{d} is replaced by all subdirectories of \var{d}: first those
+\var{d} is replaced by all subdirectories of \var{d\/}: first those
subdirectories directly under \var{d}, then the subsubdirectories under
those, and so on. At each level, the order in which the directories are
searched is \emph{unspecified}.
@@ -2115,43 +2123,55 @@
Multiple \samp{//} constructs in a path are possible, but
\samp{//} at the beginning of a path is ignored.
-\subsubsection{List of special characters and their meaning: a summary}
+\subsubsection{Summary of special characters in \file{texmf.cnf} files}
+\label{sec:cnf-special-chars}
-The following list summarizes the special characters in \KPS{}
-configuration files.
+The following list summarizes the special characters and constructs in
+\KPS{} configuration files.
% need a wider space for the item labels here.
\newcommand{\CODE}[1]{\makebox[3em][l]{\code{#1}}}
\begin{ttdescription}
\item[\CODE{:}] Separator in path specification; at the beginning or
- the end of a path it substitutes the default path expansion.\par
+ the end of a path, or doubled in the middle, it substitutes the
+ default path expansion.\par
\item[\CODE{;}] Separator on non-Unix systems (acts like \code{:}).
\item[\CODE{\$}] Variable expansion.
\item[\CODE{\string~}] Represents the user's home directory.
\item[\CODE{\char`\{...\char`\}}] Brace expansion.
+\item[\CODE{,}] Separates items in brace expansion.
\item[\CODE{//}] Subdirectory expansion (can occur anywhere in
a path, except at its beginning).
\item[\CODE{\%}] Start of comment.
-\item[\CODE{\bs}] Continuation character (allows multi-line entries).
+\item[\CODE{\bs}] At the end of a line, continuation character to allow
+ multi-line entries.
\item[\CODE{!!}] Search \emph{only} database to locate file, \emph{do
not} search the disk.
\end{ttdescription}
+Exactly when a character will be considered special or act as itself
+depends on the context in which it is used. The rules are inherent in
+the multiple levels of interpretation of the configuration (parsing,
+expansion, search, \ldots)\ and so cannot be concisely stated,
+unfortunately. There is no general escape mechanism; in particular,
+\samp{\bs} is not an ``escape character'' in \file{texmf.cnf} files.
+When it comes choosing directory names for installation, it is safest to
+avoid them all.
+
\subsection{Filename databases}
\label{sec:filename-database}
\KPS{} goes to some lengths to minimize disk accesses for searches.
-Nevertheless, at installations with enough directories, searching each
-possible directory for a given file can take an excessively long time
-(this is especially true if many hundreds of font directories have to
-be traversed.) Therefore, \KPS{} can use an externally-built plain text
-``database'' file named \file{ls-R} that maps files to directories,
-thus avoiding the need to exhaustively search the disk.
+Nevertheless, in the standard \TL, or at any installation with enough
+directories, searching every possible directory for a given file will
+take an excessively long time. Therefore, \KPS{} can use an
+externally-built plain text ``database'' file named \file{ls-R} that
+maps files to directories, thus avoiding the need to exhaustively search
+the disk.
A second database file \file{aliases} allows you to give additional
-names to the files listed in \file{ls-R}. This can be helpful to
-confirm to DOS 8.3 filename conventions in source files.
+names to the files listed in \file{ls-R}.
\subsubsection{The filename database}
\label{sec:ls-R}
@@ -3234,8 +3254,9 @@
The new \GUI{} front end \TeX{}works is included for Windows, and also in
Mac\TeX. For other platforms, and more information, see the \TeX{}works
-home page, \url{http://tug.org/texworks}. It is a cross-platform front
-end inspired by the \MacOSX\ TeXShop editor, aiming at ease-of-use.
+home page, \url{http://tug.org/texworks}. It is a cross-platform
+front-end inspired by the \MacOSX\ TeXShop editor, aiming at
+ease-of-use.
The graphics program Asymptote is included for several platforms. This
implements a text-based graphics description language vaguely akin to
@@ -3605,7 +3626,7 @@
Infrastructure: System-level \code{tlmgr} configuration file supported;
verify package checksums; if GPG is available, verify signature of
network updates. These checks happen with both the installer and
-\code{tlmgr}. (If GPG is not available, updates proceed as usual.)
+\code{tlmgr}. If GPG is not available, updates proceed as usual.
Platforms: \code{alpha-linux} and \code{mipsel-linux} removed.
@@ -3664,7 +3685,7 @@
Sync\TeX: the name of the temporary file now looks like
\code{foo.synctex(busy)}, instead of \code{foo.synctex.gz(busy)}
-(no~\code{.gz}). Front ends and build systems that want to remove temp
+(no~\code{.gz}). Front-ends and build systems that want to remove temp
files may need adjusting.
Other utilities: \code{texosquery-jre8} is a new cross-platform program
Modified: trunk/Master/texmf-dist/scripts/texlive/tlmgr.pl
===================================================================
--- trunk/Master/texmf-dist/scripts/texlive/tlmgr.pl 2019-12-22 22:19:32 UTC (rev 53212)
+++ trunk/Master/texmf-dist/scripts/texlive/tlmgr.pl 2019-12-22 22:22:33 UTC (rev 53213)
@@ -7738,19 +7738,24 @@
=item B<--gui> [I<action>]
-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
+Two notable GUI front-ends for C<tlmgr>, C<tlshell> and C<tlcockpit>,
+are started up as separate programs; see their own documentation.
+C<tlmgr> itself has a graphical interface as well as the command line
+interface. You can give the option to invoke it, 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. If no action is given, the
-GUI will be started at the main screen.
+GUI will be started at the main screen. See L<GUI FOR TLMGR>.
-Note that the new GUIs, tlshell and tlcockpit, are started up as
-separate programs.
+However, the native GUI requires Perl/TK, which is no longer included in
+TeX Live's Perl distribution for Windows. You may find C<tlshell> or
+C<tlcockpit> easier to work with.
+
=for comment Keep language list in sync with install-tl.
=item B<--gui-lang> I<llcode>
@@ -7758,14 +7763,15 @@
By default, the GUI tries to deduce your language from the environment
(on Windows via the registry, on Unix via C<LC_MESSAGES>). If that fails
you can select a different language by giving this option with a
-language code (based on ISO 639-1). Currently supported (but not
-necessarily completely translated) are: English (en, default), Czech
-(cs), German (de), French (fr), Italian (it), Japanese (ja), Dutch (nl),
-Polish (pl), Brazilian Portuguese (pt_BR), Russian (ru), Slovak (sk),
-Slovenian (sl), Serbian (sr), Ukrainian (uk), Vietnamese (vi),
-simplified Chinese (zh_CN), and traditional Chinese (zh_TW).
+language code (based on ISO 639-1). Currently supported (but not
+necessarily completely translated) are: S<English (en, default)>,
+S<Czech (cs)>, S<German (de)>, S<French (fr)>, S<Italian (it)>,
+S<Japanese (ja)>, S<Dutch (nl)>, S<Polish (pl)>, S<Brazilian Portuguese
+(pt_BR)>, S<Russian (ru)>, S<Slovak (sk)>, S<Slovenian (sl)>, S<Serbian
+(sr)>, S<Ukrainian (uk)>, S<Vietnamese (vi)>, S<simplified Chinese
+(zh_CN)>, and S<traditional Chinese (zh_TW)>.
-Tlshell shares its message catalog with tlmgr.
+tlshell shares its message catalog with tlmgr.
=item B<--debug-translation>
@@ -8481,7 +8487,7 @@
=item B<paper [a4|letter]>
-=item B<S<[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [I<papersize>|--list]>>
+=item B<<[xdvi|pdftex|dvips|dvipdfmx|context|psutils] paper [I<papersize>|--list]>>
=item B<paper --json>
@@ -9478,7 +9484,7 @@
$ tlmgr pinning remove tlcontrib classico # remove just classico
$ tlmgr pinning remove tlcontrib --all # take nothing from tlcontrib
-A summary of the C<tlmgr pinning> actions is given above.
+A summary of C<tlmgr pinning> actions is given above.
=head1 GUI FOR TLMGR
More information about the tex-live-commits
mailing list