diff options
author | Karl Berry <karl@freefriends.org> | 2019-12-22 22:22:33 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-12-22 22:22:33 +0000 |
commit | 29ad0b23168602c8f159a884fe596b355dfd3658 (patch) | |
tree | 9703469b6fe3ce187a6885db27f6e05090910d44 /Build/source/texk | |
parent | bc6dd08a758dc59e855de67708aa4eab8a0e261a (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')
-rw-r--r-- | Build/source/texk/kpathsea/ChangeLog | 8 | ||||
-rw-r--r-- | Build/source/texk/kpathsea/doc/kpathsea.info | 193 | ||||
-rw-r--r-- | Build/source/texk/kpathsea/doc/kpathsea.texi | 74 |
3 files changed, 166 insertions, 109 deletions
diff --git a/Build/source/texk/kpathsea/ChangeLog b/Build/source/texk/kpathsea/ChangeLog index dab9c798ccc..81c85b1c87f 100644 --- a/Build/source/texk/kpathsea/ChangeLog +++ b/Build/source/texk/kpathsea/ChangeLog @@ -1,7 +1,13 @@ +2019-12-22 Karl Berry <karl@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@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@tug.org> 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}. |