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

4 files changed, 118 insertions, 91 deletions

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  <karl@freefriends.org>
+
+	* 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  <karl@tug.org>
 
 	* 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)