summaryrefslogtreecommitdiff
path: root/Build/source/texk/kpathsea
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2019-01-19 23:20:26 +0000
committerKarl Berry <karl@freefriends.org>2019-01-19 23:20:26 +0000
commit3be79f169482d2cb984f8238cf20154d24365376 (patch)
treecd68a4dc8d0fb7d48da7ac75ce6cdafbd4f20066 /Build/source/texk/kpathsea
parent0dce13740fac0cb2fe8351763cce9d32a88a6235 (diff)
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
Diffstat (limited to 'Build/source/texk/kpathsea')
-rw-r--r--Build/source/texk/kpathsea/ChangeLog10
-rw-r--r--Build/source/texk/kpathsea/doc/kpathsea.info157
-rw-r--r--Build/source/texk/kpathsea/doc/kpathsea.texi36
-rw-r--r--Build/source/texk/kpathsea/variable.h6
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)