kpathsea: Auxiliary tasks
5.6.3 Auxiliary tasks
---------------------
Kpsewhich provides some features in addition to path lookup as such:
'--debug=NUM'
Set debugging options to NUM. ⇒Debugging.
'--expand-braces=STRING'
Output variable, tilde, and brace expansion of STRING, which is
assumed to be a single path element. ⇒Path expansion.
'--expand-path=STRING'
Output the complete expansion of STRING, with each element
separated by the usual path separator on the current system (';' on
Windows, ':' otherwise). This may be useful to construct a custom
search path for a format not otherwise supported. To retrieve the
search path for a format that is already supported, see
'--show-path'.
Nonexistent directories are culled from the output:
$ kpsewhich --expand-path '/tmp'
=> /tmp
$ kpsewhich --expand-path '/nonesuch'
=>
For one-shot uses of an arbitrary (not built in to Kpathsea) path,
see '--path' (⇒Path searching options).
'--expand-var=STRING'
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). ⇒Path expansion.
The specified STRING can contain anything, though, not just
variable references. This calls 'kpse_var_expand' (⇒
Programming with config files).
'--help-formats'
Output information about each supported format (⇒Supported
file formats), including the names and abbreviations, variables
looked for, and the original path.
'--safe-in-name=NAME'
'--safe-out-name=NAME'
Exit successfully if NAME is safe to open for reading or writing,
respectively, else unsuccessfully. No output is written. These
tests take account of the related Kpathsea configuration settings
(⇒Calling sequence).
'--show-path=NAME'
Show the path that would be used for file lookups of file type
NAME. Either a filename extension ('pk', '.vf', etc.) or an
integer can be used, just as with '--format', described in the
previous section.
'--var-brace-value=VARIABLE'
Like '--var-value' (next), but also expands '{...}' constructs.
(⇒Brace expansion). Thus, the value is assumed to possibly
be several path elements, and '~' is expanded at the beginning of
each. The path separator is changed to that of the current system
in the expansion.
Example: 'FOO='.;~' kpsewhich --var-brace-value=FOO' outputs (on a
Unix-ish system) '.:/home/karl', supposing the latter is the
current user's home directory. Note that the ';' in the source
value, as commonly used in 'texmf.cnf', has changed to a ':', as
the normal path separator on the current system. On a Windows-ish
system, the ';' would remain.
'--var-value=VARIABLE'
Outputs the value of VARIABLE (a simple identifier like
Variable expansion::) and '~' (⇒Tilde expansion) constructs
in the value. '~' expansion happens at the beginning of the
overall value and at the beginning of a variable expansion, but not
arbitrarily within the string. Braces are not expanded.
Example: '--var-value=texmf_casefold_search' outputs (if the
default is not changed) '1'.
Example to contrast with '--var-brace-value': 'FOO='.;~' kpsewhich
--var-value=FOO' outputs '.;~', i.e., the same as the input value,
on all systems.