diff options
author | Karl Berry <karl@freefriends.org> | 2019-01-19 23:20:26 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-01-19 23:20:26 +0000 |
commit | 3be79f169482d2cb984f8238cf20154d24365376 (patch) | |
tree | cd68a4dc8d0fb7d48da7ac75ce6cdafbd4f20066 /Build/source/texk/kpathsea/doc/kpathsea.texi | |
parent | 0dce13740fac0cb2fe8351763cce9d32a88a6235 (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/doc/kpathsea.texi')
-rw-r--r-- | Build/source/texk/kpathsea/doc/kpathsea.texi | 36 |
1 files changed, 22 insertions, 14 deletions
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 |