From 3be79f169482d2cb984f8238cf20154d24365376 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 19 Jan 2019 23:20:26 +0000 Subject: kpse_var_expand: document $FOO->literal string vs. ${FOO}->empty string expansion; noticed by Andreas Scherer git-svn-id: svn://tug.org/texlive/trunk@49764 c570f23f-e606-0410-a88d-b1316a301751 --- Build/source/texk/kpathsea/ChangeLog | 10 ++ Build/source/texk/kpathsea/doc/kpathsea.info | 157 ++++++++++++++------------- Build/source/texk/kpathsea/doc/kpathsea.texi | 36 +++--- Build/source/texk/kpathsea/variable.h | 6 +- 4 files changed, 118 insertions(+), 91 deletions(-) (limited to 'Build/source/texk') diff --git a/Build/source/texk/kpathsea/ChangeLog b/Build/source/texk/kpathsea/ChangeLog index eb70526cc2b..52ce7a51ed9 100644 --- a/Build/source/texk/kpathsea/ChangeLog +++ b/Build/source/texk/kpathsea/ChangeLog @@ -1,3 +1,13 @@ +2019-01-19 Karl Berry + + * variable.h (kpathsea_var_expand): returns string "$FOO" if FOO + is not defined, not the empty string; whereas ${FOO} does return + the empty string. Maybe not the ideal interface, but seems + undesirable to change now. + * doc/kpathsea.texi (Programming with config files), + (Auxiliary tasks): document this. + Noted by Andreas Scherer, r49726. + 2019-01-19 Karl Berry * texmf.cnf (TEXMFLOCALEDIR): define as $TEXMFMAIN/locale, diff --git a/Build/source/texk/kpathsea/doc/kpathsea.info b/Build/source/texk/kpathsea/doc/kpathsea.info index b6438df80ad..377d74391ef 100644 --- a/Build/source/texk/kpathsea/doc/kpathsea.info +++ b/Build/source/texk/kpathsea/doc/kpathsea.info @@ -3,7 +3,7 @@ kpathsea.texi. This file documents the Kpathsea library for path searching. - Copyright (C) 1996-2018 Karl Berry & Olaf Weber. + Copyright (C) 1996-2019 Karl Berry & Olaf Weber. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -37,7 +37,7 @@ Kpathsea library **************** This manual documents the Kpathsea library for path searching. It -corresponds to version 6.3.0, released in December 2018. +corresponds to version 6.3.0, released in January 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.0 of the Kpathsea library, -released in December 2018. +released in January 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 @@ -1450,6 +1450,9 @@ Kpsewhich provides some features in addition to path lookup as such: Output the variable and tilde expansion of STRING. For example, with the usual 'texmf.cnf', 'kpsewhich --expand-var='$TEXMF'' returns the TeX system hierarchy root(s). *Note Path expansion::. + The specified STRING can contain anything, though, not just + variable references. This calls 'kpse_var_expand' (*note + Programming with config files::). '--help-formats' Output information about each supported format (*note Supported @@ -2484,18 +2487,22 @@ You can (and probably should) use the same 'texmf.cnf' configuration file that Kpathsea uses for your program. This helps installers by keeping all configuration in one place. - To retrieve a value VAR from config files, the best way is to call -'kpathsea_var_value' on the string 'VAR'. This will look first for an -environment variable VAR, then a config file value. The result will be -the value found or 'NULL'. This function is declared in + To retrieve a value for a configuration variable VAR, the best way is +to call 'kpathsea_var_value' on the string 'VAR'. This will look first +for an environment variable VAR, then a config file value. The result +will be the value found or 'NULL'. This function is declared in 'kpathsea/variable.h'. For an example, see the 'shell_escape' code in 'web2c/lib/texmfmp.c'. - The routine to do variable expansion in the context of a search path -(as opposed to simply retrieving a value) is 'kpathsea_var_expand', also -declared in 'kpathsea/variable.h'. It's generally only necessary to set + The routine to do full variable and tilde expansion of an arbitrary +string in the context of a search path (as opposed to simply retrieving +a value) is 'kpathsea_var_expand', also declared in +'kpathsea/variable.h'. However, it's generally only necessary to set the search path structure components as explained in the previous -section, rather than using this yourself. +section instead of using this directly. Because of its usage with any +input string, undefined '$FOO' constructs in the argument to +'kpathsea_var_expand' are returned literally ('"$FOO"'), while undefined +'${FOO}' constructs are expanded to the empty string. If for some reason you want to retrieve a value _only_ from a config file, not automatically looking for a corresponding environment @@ -2974,7 +2981,7 @@ Index * --format=NAME: Path searching options. (line 48) * --help: Standard options. (line 8) -* --help-formats: Auxiliary tasks. (line 39) +* --help-formats: Auxiliary tasks. (line 42) * --interactive: Path searching options. (line 130) * --mktex=FILETYPE: Path searching options. @@ -2991,13 +2998,13 @@ Index (line 151) * --progname=NAME: Path searching options. (line 159) -* --safe-in-name=NAME: Auxiliary tasks. (line 45) -* --safe-out-name=NAME: Auxiliary tasks. (line 45) -* --show-path=NAME: Auxiliary tasks. (line 51) +* --safe-in-name=NAME: Auxiliary tasks. (line 48) +* --safe-out-name=NAME: Auxiliary tasks. (line 48) +* --show-path=NAME: Auxiliary tasks. (line 54) * --subdir=STRING: Path searching options. (line 164) -* --var-brace-value=VARIABLE: Auxiliary tasks. (line 57) -* --var-value=VARIABLE: Auxiliary tasks. (line 71) +* --var-brace-value=VARIABLE: Auxiliary tasks. (line 60) +* --var-value=VARIABLE: Auxiliary tasks. (line 74) * --version: Standard options. (line 11) * --with-mktextex-default: mktex configuration. (line 12) * --without-mktexfmt-default: mktex configuration. (line 12) @@ -3204,7 +3211,7 @@ Index * cmr10.vf: Searching overview. (line 31) * cnf.c: Config files. (line 86) * cnf.h: Programming with config files. - (line 23) + (line 27) * comments, in fontmap files: Fontmap. (line 27) * comments, in texmf.cnf: Config files. (line 27) * comments, making: Introduction. (line 29) @@ -3407,7 +3414,7 @@ Index * kpathsea.h: Programming overview. (line 26) * kpathsea_cnf_get: Programming with config files. - (line 23) + (line 27) * KPATHSEA_DEBUG: Calling sequence. (line 28) * KPATHSEA_DEBUG <1>: Debugging. (line 18) * kpathsea_find_file: File lookup. (line 38) @@ -3866,61 +3873,61 @@ Index  Tag Table: Node: Top1480 -Node: Introduction2263 -Node: History4336 -Node: unixtex.ftp8932 -Node: Security10357 -Node: TeX directory structure12861 -Node: Path searching16909 -Node: Searching overview17636 -Node: Path sources21455 -Node: Config files22546 -Node: Path expansion26473 -Node: Default expansion27426 -Node: Variable expansion29496 -Node: Tilde expansion30897 -Node: Brace expansion31877 -Node: KPSE_DOT expansion32816 -Node: Subdirectory expansion33329 -Node: Casefolding search35683 -Node: Casefolding rationale36452 -Node: Casefolding examples37791 -Node: Filename database42841 -Node: ls-R43899 -Node: Filename aliases46794 -Node: Database format47972 -Node: Invoking kpsewhich48985 -Node: Path searching options49940 -Node: Specially-recognized files58459 -Node: Auxiliary tasks59814 -Node: Standard options63353 -Node: TeX support63709 -Node: Supported file formats65063 -Node: File lookup72728 -Node: Glyph lookup74477 -Node: Basic glyph lookup75601 -Node: Fontmap76481 -Node: Fallback font79010 -Node: Suppressing warnings79922 -Node: mktex scripts81049 -Node: mktex configuration82264 -Node: mktex script names88067 -Node: mktex script arguments89453 -Node: Programming90332 -Node: Programming overview90905 -Node: Calling sequence93766 -Node: Program-specific files100298 -Node: Programming with config files101321 -Node: Reporting bugs102633 -Node: Bug checklist103311 -Node: Mailing lists106783 -Node: Debugging107458 -Node: Logging112535 -Node: Common problems114402 -Node: Unable to find files114879 -Node: Slow path searching117289 -Node: Unable to generate fonts118664 -Node: TeX or Metafont failing121135 -Node: Index122337 +Node: Introduction2262 +Node: History4334 +Node: unixtex.ftp8930 +Node: Security10355 +Node: TeX directory structure12859 +Node: Path searching16907 +Node: Searching overview17634 +Node: Path sources21453 +Node: Config files22544 +Node: Path expansion26471 +Node: Default expansion27424 +Node: Variable expansion29494 +Node: Tilde expansion30895 +Node: Brace expansion31875 +Node: KPSE_DOT expansion32814 +Node: Subdirectory expansion33327 +Node: Casefolding search35681 +Node: Casefolding rationale36450 +Node: Casefolding examples37789 +Node: Filename database42839 +Node: ls-R43897 +Node: Filename aliases46792 +Node: Database format47970 +Node: Invoking kpsewhich48983 +Node: Path searching options49938 +Node: Specially-recognized files58457 +Node: Auxiliary tasks59812 +Node: Standard options63518 +Node: TeX support63874 +Node: Supported file formats65228 +Node: File lookup72893 +Node: Glyph lookup74642 +Node: Basic glyph lookup75766 +Node: Fontmap76646 +Node: Fallback font79175 +Node: Suppressing warnings80087 +Node: mktex scripts81214 +Node: mktex configuration82429 +Node: mktex script names88232 +Node: mktex script arguments89618 +Node: Programming90497 +Node: Programming overview91070 +Node: Calling sequence93931 +Node: Program-specific files100463 +Node: Programming with config files101486 +Node: Reporting bugs103073 +Node: Bug checklist103751 +Node: Mailing lists107223 +Node: Debugging107898 +Node: Logging112975 +Node: Common problems114842 +Node: Unable to find files115319 +Node: Slow path searching117729 +Node: Unable to generate fonts119104 +Node: TeX or Metafont failing121575 +Node: Index122777  End Tag Table diff --git a/Build/source/texk/kpathsea/doc/kpathsea.texi b/Build/source/texk/kpathsea/doc/kpathsea.texi index 449bd0e7489..1dd8e3f57be 100644 --- a/Build/source/texk/kpathsea/doc/kpathsea.texi +++ b/Build/source/texk/kpathsea/doc/kpathsea.texi @@ -3,12 +3,12 @@ @settitle Kpathsea: A library for path searching @set version 6.3.0 -@set month-year December 2018 +@set month-year January 2019 @copying This file documents the Kpathsea library for path searching. -Copyright @copyright{} 1996--2018 Karl Berry & Olaf Weber. +Copyright @copyright{} 1996--2019 Karl Berry & Olaf Weber. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are @@ -1795,10 +1795,12 @@ For one-shot uses of an arbitrary (not built in to Kpathsea) path, see @item --expand-var=@var{string} @opindex --expand-var=@var{string} -Output the variable and tilde expansion of @var{string}. For example, +Output the variable and tilde expansion of @var{string}. For example, with the usual @file{texmf.cnf}, @samp{kpsewhich --expand-var='$TEXMF'} returns the @TeX{} system hierarchy root(s). -@xref{Path expansion}. +@xref{Path expansion}. The specified @var{string} can contain +anything, though, not just variable references. This calls +@code{kpse_var_expand} (@pxref{Programming with config files}). @item --help-formats @opindex --help-formats @@ -3264,18 +3266,24 @@ installers by keeping all configuration in one place. @findex kpathsea_var_value @flindex variable.h @vindex shell_escape@r{, example for code} -To retrieve a value @var{var} from config files, the best way is to call -@code{kpathsea_var_value} on the string @code{@var{var}}. This will look -first for an environment variable @var{var}, then a config file value. -The result will be the value found or @samp{NULL}. This function is -declared in @file{kpathsea/variable.h}. For an example, see the +To retrieve a value for a configuration variable @var{var}, the best +way is to call @code{kpathsea_var_value} on the string +@code{@var{var}}. This will look first for an environment variable +@var{var}, then a config file value. The result will be the value +found or @samp{NULL}. This function is declared in +@file{kpathsea/variable.h}. For an example, see the @code{shell_escape} code in @file{web2c/lib/texmfmp.c}. -The routine to do variable expansion in the context of a search path (as -opposed to simply retrieving a value) is @code{kpathsea_var_expand}, also -declared in @file{kpathsea/variable.h}. It's generally only necessary -to set the search path structure components as explained in the previous -section, rather than using this yourself. +The routine to do full variable and tilde expansion of an arbitrary +string in the context of a search path (as opposed to simply +retrieving a value) is @code{kpathsea_var_expand}, also declared in +@file{kpathsea/variable.h}. However, it's generally only necessary to +set the search path structure components as explained in the previous +section instead of using this directly. Because of its usage with any +input string, undefined @code{$FOO} constructs in the argument to +@code{kpathsea_var_expand} are returned literally (@code{"$FOO"}), +while undefined @code{$@{FOO@}} constructs are expanded to the empty +string. @findex kpathsea_cnf_get @flindex cnf.h diff --git a/Build/source/texk/kpathsea/variable.h b/Build/source/texk/kpathsea/variable.h index ab4a22a6924..6bd2a62bf98 100644 --- a/Build/source/texk/kpathsea/variable.h +++ b/Build/source/texk/kpathsea/variable.h @@ -1,6 +1,6 @@ /* variable.h: declare variable expander. - Copyright 1993, 1995, 2008 Karl Berry. + Copyright 1993, 1995, 2008, 2019 Karl Berry. This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public @@ -39,7 +39,9 @@ extern KPSEDLL string kpathsea_var_value (kpathsea kpse, const_string var); In any case, ``expansion'' means calling `getenv'; if the variable is not set, look in texmf.cnf files for a definition. If not set there, either, - the expansion is the empty string (no error). */ + the expansion of a $FOO construct is its literal text ("$FOO"), while + the expansion of a ${BAR} construct is the empty string. This is so + at least some file names containing $ characters will work. */ extern KPSEDLL string kpathsea_var_expand (kpathsea kpse, const_string src); #if defined (KPSE_COMPAT_API) -- cgit v1.2.3