summaryrefslogtreecommitdiff
path: root/Build/source/texk/kpathsea/doc
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-12-22 22:22:33 +0000
committerKarl Berry <karl@freefriends.org>2019-12-22 22:22:33 +0000
commit29ad0b23168602c8f159a884fe596b355dfd3658 (patch)
tree9703469b6fe3ce187a6885db27f6e05090910d44 /Build/source/texk/kpathsea/doc
parentbc6dd08a758dc59e855de67708aa4eab8a0e261a (diff)
doc: better describe config file special characters; plus other typos, url fixes, mention gpg, etc., from Takuto in texlive-en.tex
git-svn-id: svn://tug.org/texlive/trunk@53213 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Build/source/texk/kpathsea/doc')
-rw-r--r--Build/source/texk/kpathsea/doc/kpathsea.info193
-rw-r--r--Build/source/texk/kpathsea/doc/kpathsea.texi74
2 files changed, 159 insertions, 108 deletions
diff --git a/Build/source/texk/kpathsea/doc/kpathsea.info b/Build/source/texk/kpathsea/doc/kpathsea.info
index 959873b6e8c..17f236f6646 100644
--- a/Build/source/texk/kpathsea/doc/kpathsea.info
+++ b/Build/source/texk/kpathsea/doc/kpathsea.info
@@ -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 @@ Kpathsea library
****************
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 @@ File: kpathsea.info, Node: Introduction, Next: unixtex.ftp, Prev: Top, Up: T
**************
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 @@ This chapter describes the generic path searching mechanism Kpathsea
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 @@ mentions most features. The format of 'texmf.cnf' files follows:
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 @@ mentions most features. The format of 'texmf.cnf' files follows:
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,14 +555,20 @@ mentions most features. The format of 'texmf.cnf' files follows:
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
@@ -573,12 +584,12 @@ Here is a configuration file fragment illustrating most of these points:
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 @@ Kpathsea warns if the program name contains a path separator or other
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 @@ if the path specification is, say, '$TEXMF/fonts//pk//', then files in a
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 @@ File: kpathsea.info, Node: Filename database, Next: Invoking kpsewhich, Prev:
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 @@ file named 'ls-R' that maps files to directories, thus avoiding the need
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 @@ Index
(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 @@ Index
* 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 @@ Index
(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 @@ Index
* 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 @@ Index
* 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 @@ Index
* 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 @@ Index

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:
diff --git a/Build/source/texk/kpathsea/doc/kpathsea.texi b/Build/source/texk/kpathsea/doc/kpathsea.texi
index db619f50129..8fdb387fff1 100644
--- a/Build/source/texk/kpathsea/doc/kpathsea.texi
+++ b/Build/source/texk/kpathsea/doc/kpathsea.texi
@@ -3,7 +3,7 @@
@settitle Kpathsea: A library for path searching
@set version 6.3.2
-@set month-year August 2019
+@set month-year December 2019
@copying
This file documents the Kpathsea library for path searching.
@@ -445,6 +445,12 @@ This chapter describes the generic path searching mechanism Kpathsea
provides. For information about searching for particular file types
(e.g., @TeX{} fonts), see the next chapter.
+@cindex translations, of path searching description
+This section, with minor differences, has been translated into several
+other languages (Chinese, Spanish, Russian, Japanese, French, German,
+@dots{}) as part of the @TeX{} Live guide; see
+@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 @@ start a comment. Examples:
@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 @@ A @samp{\} at the end of a line acts as a continuation character, i.e.,
the next line is appended. Whitespace at the beginning of continuation
lines is not ignored.
-@item Each remaining line must look like
+@item Each remaining line will look like:
@example
@var{variable} @r{[}. @var{progname}@r{]} @r{[}=@r{]} @var{value}
@@ -681,6 +687,7 @@ lines is not ignored.
The @var{variable} name may contain any character other than whitespace,
@samp{=}, or @samp{.}, but sticking to @samp{A-Za-z_} is safest.
+@kindex .@var{progname} @r{qualifier in @file{texmf.cnf}}
@item If @samp{.@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,15 +698,21 @@ variable or other expansions.
@item
@cindex right-hand side of variable assignments
-@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
-@samp{$@var{var}.@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}.@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
-@samp{:} if running under Unix; this is useful to write a single
-@file{texmf.cnf} which can be used under both Unix and Windows.
+below for example).
+
+@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
@@ -721,14 +734,15 @@ TEXINPUTS.latex = $latex2e_inputs
@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
-@code{=}, and get rid of the @code{.@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{.@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.
+
+@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 @@ an empty value for @code{var} running under the program named
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,
+@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 @@ You can disable the trick by undefining @code{ST_NLINK_TRICK} in
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
-@samp{@dots{}/pk}, even if it is a leaf, are checked. The reason cannot
-be explained without reference to the implementation, so read
+@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 @@ happens with the elements of the leaf directory.
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 @@ 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 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}.