summaryrefslogtreecommitdiff
path: root/Build/source/texk/kpathsea/doc/kpathsea.texi
diff options
context:
space:
mode:
Diffstat (limited to 'Build/source/texk/kpathsea/doc/kpathsea.texi')
-rw-r--r--Build/source/texk/kpathsea/doc/kpathsea.texi3931
1 files changed, 3931 insertions, 0 deletions
diff --git a/Build/source/texk/kpathsea/doc/kpathsea.texi b/Build/source/texk/kpathsea/doc/kpathsea.texi
new file mode 100644
index 00000000000..00ff64eefbe
--- /dev/null
+++ b/Build/source/texk/kpathsea/doc/kpathsea.texi
@@ -0,0 +1,3931 @@
+\input texinfo
+@setfilename kpathsea.info
+@settitle Kpathsea: A library for path searching
+
+@set version 6.3.3
+@set month-year February 2021
+
+@copying
+This file documents the Kpathsea library for path searching.
+
+Copyright @copyright{} 1996--2021 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
+preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries a copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+@end ignore
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided that the
+entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions,
+except that this permission notice may be stated in a translation
+approved by the @TeX{} Users Group.
+@end copying
+
+@c Define new indices for commands, filenames, and options.
+@defcodeindex cm
+@defcodeindex fl
+@defcodeindex op
+
+@c Put everything in one index (arbitrarily chosen to be the concept index).
+@syncodeindex cm cp
+@syncodeindex fl cp
+@syncodeindex fn cp
+@syncodeindex ky cp
+@syncodeindex op cp
+@syncodeindex pg cp
+@syncodeindex tp cp
+@syncodeindex vr cp
+
+@dircategory TeX
+@direntry
+* Kpathsea: (kpathsea). File lookup along search paths.
+* kpsewhich: (kpathsea)Invoking kpsewhich. TeX file searching.
+* mktexfmt: (kpathsea)mktex scripts. Format (fmt/base/mem) generation.
+* mktexlsr: (kpathsea)Filename database. Update ls-R.
+* mktexmf: (kpathsea)mktex scripts. MF source generation.
+* mktexpk: (kpathsea)mktex scripts. PK bitmap generation.
+* mktextex: (kpathsea)mktex scripts. TeX source generation.
+* mktextfm: (kpathsea)mktex scripts. TeX font metric generation.
+@end direntry
+
+
+@titlepage
+@title Kpathsea library
+@subtitle for version @value{version}
+@subtitle @value{month-year}
+@author Karl Berry
+@author Olaf Weber
+@author Taco Hoekwater
+@author @url{https://tug.org/kpathsea}
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+
+@contents
+
+
+@ifnottex
+@node Top
+@top Kpathsea library
+
+This manual documents the Kpathsea library for path searching. It
+corresponds to version @value{version}, released in
+@value{month-year}.
+
+@menu
+* Introduction:: Overview and history.
+
+* unixtex.ftp:: Obtaining @TeX{} software.
+* Security:: Who can write what files, etc.
+* TeX directory structure:: Managing the horde of @TeX{} input files.
+
+* Path searching:: How filename lookups work.
+* TeX support:: Special support for TeX-related file lookups.
+
+* Programming:: How to use Kpathsea features in your program.
+
+* Reporting bugs:: Where and how to report bugs.
+* Index:: General index.
+@end menu
+@end ifnottex
+
+
+@node Introduction
+@chapter Introduction
+
+@cindex introduction
+@cindex fundamental purpose of Kpathsea
+
+This manual corresponds to version @value{version} of the Kpathsea
+library, released in @value{month-year}.
+
+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
+looking up program names to execute.
+
+@cindex programs using the library
+The following software, all of which is maintained in parallel, uses
+this library:
+
+@itemize @bullet
+@item Dviljk (see the @samp{dvilj} man page)
+@item Dvipsk (@pxref{,,,dvips, Dvips: A DVI driver})
+@item GNU font utilities (@pxref{,,,fontu, GNU font utilities})
+@item Web2c (@pxref{,,,web2c, Web2c: A @TeX{} implementation})
+@item Xdvik (see the @samp{xdvi} man page)
+@end itemize
+
+@noindent Other software that we do not maintain also uses it.
+
+Kpathsea is now maintained as part of the @TeX{} Live distribution
+(@url{https://tug.org/texlive}), which includes several more
+Kpathsea-using programs. For information on configuration, building,
+installing, and more, @pxref{,,,tlbuild, Building @TeX{} Live}.
+
+@cindex interface, not frozen
+@cindex comments, making
+@cindex suggestions, making
+The library is still actively maintained. If you have comments or
+suggestions, please send along (@pxref{Reporting bugs}).
+
+@cindex conditions for use
+@cindex license for using the library
+@cindex GNU General Public License
+The Kpathsea library is distributed under the GNU Library General
+Public License (LGPL), version@tie{}2.1 or (at your option) any later
+version. In short, this means if you write a program using the
+library, you must (offer to) distribute the source to the library,
+along with any changes you have made, and allow anyone to modify the
+library source and distribute their modifications. It does not mean
+you have to distribute the source to your program using the library,
+although we hope you will. See accompanying files for the text of the
+GNU licenses, or @url{https://gnu.org/licenses}.
+
+@cindex @TeX{} Users Group
+If you know enough about @TeX{} to be reading this manual, then you (or
+your institution) should consider joining the @TeX{} Users Group (if
+you're already a member, thanks!). TUG produces the periodical
+@cite{TUGboat}, sponsors an annual meeting and publishes the
+proceedings, and arranges courses on @TeX{} for all levels of users
+throughout the world. See @url{https://tug.org} for information.
+
+@menu
+* History::
+@end menu
+
+
+@node History
+@section History
+
+@cindex history of Kpathsea
+
+@cindex Knuth, Donald E.
+This section is for those people who are curious about how the library
+came about. If you like to read historical accounts of software, we
+urge you to seek out the GNU Autoconf manual and the ``Errors of
+@TeX{}'' paper by Don Knuth, published in his book @cite{Digital
+Typography}, among other places.
+
+@cindex Morgan, Tim
+@cindex Rokicki, Tom
+@cindex Berry, Karl
+@cindex VAX 11/750
+@cindex Sun 2
+@pindex pxp @r{Pascal preprocessor}
+@pindex pc @r{Pascal compiler}
+[Karl writes.] My first ChangeLog entry for Web2c seems to be
+February 1990, but I may have done some work before then. In any
+case, Tim Morgan and I were jointly maintaining it for a time. (I
+should mention here that Tim had made Web2c into a real distribution
+long before I had ever used it or even heard of it, and Tom Rokicki
+did the original implementation. When I started, I was using
+@code{pxp} and @code{pc} on VAX 11/750's and the hot new Sun 2
+machines.)
+
+It must have been later in 1990 and 1991 that I started working on
+@cite{@TeX{} for the Impatient}. Dvips, Xdvi, Web2c, and the GNU
+fontutils (which I was also writing at the time) all used different
+environment variables, and, more importantly, had different bugs in
+their path searching. This became extremely painful, as I was stressing
+everything to the limit working on the book. I also desperately wanted
+to implement subdirectory searching, since I couldn't stand putting
+everything in one big directory, and also couldn't stand having to
+explicitly specify @file{cm}, @file{pandora}, @dots{} in a path.
+
+@cindex Vojta, Paul
+In the first incarnation, I just hacked separately on each
+program---that was the original subdirectory searching code in both
+Xdvi and Dvips. That is, I tried to go with the flow in each program,
+rather than changing the program's calling sequences to conform to new
+routines.
+
+Then, as bugs inevitably appeared, I found I was fixing the same thing
+three times (Web2c and fontutils were already sharing code, since I
+maintained both of those---there was no Dvipsk or Xdvik or Dviljk at
+this point). After a while, I finally started sharing source files.
+They weren't yet a library, though. I just kept things up to date
+with shell scripts. (I was developing on a 386 running ISC 2.2 at the
+time, and so didn't have symbolic links. An awful experience.)
+
+@cindex MacKenzie, David
+The ChangeLogs for Xdvik and Dvipsk record initial releases of those
+distributions in May and June 1992. I think it was because I was tired
+of the different configuration strategies of each program, not so much
+because of the path searching. Autoconf was being developed by David
+MacKenzie and others, and I was adapting it to @TeX{} and friends.
+
+@cindex zuhn, david
+I started to make a separate library that other programs could link with
+on my birthday in April 1993, according to the ChangeLog. I don't
+remember exactly why I finally took the time to make it a separate
+library; a conversation with david zuhn initiated it. Just seemed
+like it was time.
+
+@cindex Walsh, Norman
+@cindex Neumann, Gustaf
+Dviljk got started in March 1994 after I bought a Laserjet 4. (Kpathsea
+work got suspended while Norm Walsh and I, with Gustaf Neumann's help,
+implemented a way for @TeX{} to get at all those neat builtin LJ4 fonts
+@dots{} such a treat to have something to typeset in besides Palatino!)
+
+By spring of 1995, I had implemented just about all the path-searching
+features in Kpathsea that I plan to, driven beyond my initial goals by
+Thomas Esser and others. I then started to integrate Web2c with
+Kpathsea. After the release of a stable Web2c, I hope to be able to stop
+development, and turn most of my attention back to making fonts for GNU.
+(Always assuming Micros**t hasn't completely obliterated Unix by then,
+or that software patents haven't stopped software development by anybody
+smaller than a company with a million-dollar-a-year legal budget. Which
+is actually what I think is likely to happen, but that's another
+story@dots{})
+
+@cindex Weber, Olaf
+[Olaf writes.] At the end of 1997, Unix is still alive and kicking,
+individuals still develop software, and Web2c development still
+continues. Karl had been looking for some time for someone to take up
+part of the burden, and I volunteered.
+
+@cindex Hoekwater, Taco
+@cindex Breitenlohner, Peter
+[Karl writes again.] Indeed, time goes on. As of 2006 or so, Olaf's
+available time for Kpathsea was reduced, and I started taking overall
+care of it again, although I did not do any significant new
+development. In 2009, Taco Hoekwater implemented a major
+rearrangement to make the library suitable for use within the MetaPost
+library (@pxref{Programming overview}). Also, for some years now,
+Peter Breitenlohner has made many improvements to the infrastructure
+and kept it up-to-date with respect to the overall @TeX{} Live build,
+where Kpathsea is now maintained.
+
+
+@c emacs-page separate file so we can easily generate unixtex.ftp.
+@include unixtex.texi
+
+
+@node Security
+@chapter Security
+
+@cindex security considerations
+
+None of the programs in the @TeX{} system require any special system
+privileges, so there's no first-level security concern of people gaining
+illegitimate root access.
+
+@cindex trojan horse attack
+@flindex .rhosts@r{, writable by @TeX{}}
+A @TeX{} document, however, can write to arbitrary files, e.g.,
+@file{~/.rhosts}, and thus an unwitting user who runs @TeX{} on a random
+document is vulnerable to a trojan horse attack. This loophole is
+closed by default, but you can be permissive if you so desire in
+@file{texmf.cnf}. @xref{tex invocation,,, web2c, Web2c}. MetaPost has
+the same issue.
+
+Dvips, Xdvi, and @TeX{} can also execute shell commands under some
+circumstances. To disable this, see the @samp{-R} option in @ref{Option
+details,,, dvips, Dvips}, the xdvi man page, and @ref{tex
+invocation,,, web2c, Web2c}, respectively.
+
+@cindex local cache of fonts
+@cindex cache of fonts, local
+Another security issue arises because it's very useful---almost
+necessary---to make arbitrary fonts on user demand with @code{mktexpk}
+and friends. Where do these files get installed? By default, the
+@code{mktexpk} distributed with Kpathsea assumes a world-writable
+@file{/var/tmp} directory; this is a simple and convenient approach, but
+it may not suit your situation because it means that a local cache of
+fonts is created on every machine.
+
+@cindex globally writable directories
+To avoid this duplication, many people consider a shared, globally
+writable font tree desirable, in spite of the potential security
+problems. To do this you should change the value of @code{VARTEXFONTS}
+in @file{texmf.cnf} to refer to some globally known directory.
+@xref{mktex configuration}.
+
+@cindex append-only directories and @code{mktexpk}
+The first restriction you can apply is to make newly-created directories
+under @file{texmf} be append-only with an option in @file{mktex.cnf}.
+@xref{mktex configuration}.
+
+@cindex group-writable directories
+@cindex setgid scripts
+Another approach is to establish a group (or user) for @TeX{} files,
+make the @file{texmf} tree writable only to that group (or user), and
+make @code{mktexpk} et al.@: setgid to that group (or setuid to that
+user). Then users must invoke the scripts to install things. (If
+you're worried about the inevitable security holes in scripts, then you
+could write a C wrapper to exec the script.)
+
+@cindex file permissions
+@cindex permissions, file
+The @file{mktex@dots{}} scripts install files with the same read and
+write permissions as the directory they are installed in. The
+executable, sgid, suid, and sticky bits are always cleared.
+
+@cindex directory permissions
+@cindex permissions, directory
+Any directories created by the @file{mktex@dots{}} scripts have the
+same permissions as their parent directory, unless the
+@code{appendonlydir} feature is used, in which case the sticky bit is
+always set.
+
+
+@node TeX directory structure
+@chapter @TeX{} directory structure
+
+@vindex TEXMF
+@cindex @TeX{} directory structure
+@cindex directory structure, for @TeX{} files
+@cindex skeleton @TeX{} directory
+@cindex TDS
+
+This section describes the default installation hierarchy of the
+distribution. It conforms to both the GNU coding standards and the
+@TeX{} directory structure (TDS) standard. For rationale and further
+explanation, please see those documents. The GNU document is
+available from @url{https://gnu.org/prep/standards}. The TDS
+document is available from @url{http://mirror.ctan.org/tds}
+(@pxref{unixtex.ftp}).
+
+In short, here is a skeleton of the default directory structure,
+extracted from the TDS document:
+
+@example
+@var{prefix}/ @r{installation root (@file{/usr/local} by default)}
+ bin/ @r{executables}
+ man/ @r{man pages}
+ include/ @r{C header files}
+ info/ @r{GNU info files}
+ lib/ @r{libraries (@file{libkpathsea.*})}
+ share/ @r{architecture-independent files}
+ texmf/ @r{TDS root}
+ bibtex/ @r{Bib@TeX{} input files}
+ bib/ @r{Bib@TeX{} databases}
+ base/ @r{base distribution (e.g., @samp{xampl.bib})}
+ misc/ @r{single-file databases}
+ @var{pkg}/ @r{name of a package}
+ bst/ @r{Bib@TeX{} style files}
+ base/ @r{base distribution (e.g., @samp{plain.bst}, @samp{acm.bst})}
+ misc/ @r{single-file styles}
+ @var{pkg}/ @r{name of a package}
+ doc/ @r{additional documentation}
+ dvips/ @r{@samp{.pro}, @samp{.ps}, @samp{psfonts.map}}
+ fonts/ @r{font-related files}
+ @var{type}/ @r{file type (e.g., @samp{tfm}, @samp{pk})}
+ @var{mode}/ @r{type of output device (types @samp{pk} and @samp{gf} only)}
+ @var{supplier}/ @r{name of a font supplier (e.g., @samp{public})}
+ @var{typeface}/ @r{name of a typeface (e.g., @samp{cm})}
+ dpi@var{nnn}/ @r{font resolution (types @samp{pk} and @samp{gf} only)}
+ metafont/ @r{Metafont (non-font) input files}
+ base/ @r{base distribution (e.g., @samp{plain.mf})}
+ misc/ @r{single-file packages (e.g., @samp{modes.mf})}
+ @var{pkg}/ @r{name of a package (e.g., @samp{mfpic})}
+ metapost/ @r{MetaPost input files}
+ base/ @r{base distribution (e.g., @samp{plain.mp})}
+ misc/ @r{single-file packages}
+ @var{pkg}/ @r{name of a package}
+ support/ @r{support files for MetaPost-related utilities (e.g., @samp{trfonts.map})}
+ mft/ @r{@samp{MFT} inputs (e.g., @samp{plain.mft})}
+ tex/ @r{@TeX{} input files}
+ @var{format}/ @r{name of a format (e.g., @samp{plain})}
+ base/ @r{base distribution for @var{format} (e.g., @samp{plain.tex})}
+ misc/ @r{single-file packages (e.g., @samp{webmac.tex})}
+ local/ @r{local additions to or local configuration files for @var{format}}
+ @var{pkg}/ @r{name of a package (e.g., @samp{graphics}, @samp{mfnfss})}
+ generic/ @r{format-independent packages}
+ hyphen/ @r{hyphenation patterns (e.g., @samp{hyphen.tex})}
+ images/ @r{image input files (e.g., Encapsulated PostScript)}
+ misc/ @r{single-file format-independent packages (e.g., @samp{null.tex}).}
+ @var{pkg}/ @r{name of a package (e.g., @samp{babel})}
+ web2c/ @r{implementation-dependent files (@file{.pool}, @file{.fmt}, @file{texmf.cnf}, etc.)}
+@end example
+
+Some concrete examples for most file types:
+
+@example
+/usr/local/bin/tex
+/usr/local/man/man1/xdvi.1
+/usr/local/info/kpathsea.info
+/usr/local/lib/libkpathsea.a
+/usr/local/share/texmf/bibtex/bst/base/plain.bst
+/usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk
+/usr/local/share/texmf/fonts/source/public/pandora/pnr10.mf
+/usr/local/share/texmf/fonts/tfm/public/cm/cmr10.tfm
+/usr/local/share/texmf/fonts/type1/adobe/utopia/putr.pfa
+/usr/local/share/texmf/metafont/base/plain.mf
+/usr/local/share/texmf/metapost/base/plain.mp
+/usr/local/share/texmf/tex/plain/base/plain.tex
+/usr/local/share/texmf/tex/generic/hyphen/hyphen.tex
+/usr/local/share/texmf/web2c/tex.pool
+/usr/local/share/texmf/web2c/tex.fmt
+/usr/local/share/texmf/web2c/texmf.cnf
+@end example
+
+
+@node Path searching
+@chapter Path searching
+
+@cindex path searching
+
+This chapter describes the generic path searching mechanism Kpathsea
+provides. For information about searching for particular file types
+(e.g., @TeX{} fonts), see the next chapter.
+
+@cindex translations, of path searching description
+This section, with minor differences, has been translated into several
+other languages (Chinese, Spanish, Russian, Japanese, French, German,
+@dots{}) as part of the @TeX{} Live guide; see
+@url{https://tug.org/texlive/doc.html} for links.
+
+@menu
+* Searching overview:: Basic scheme for searching.
+* Path sources:: Where search paths can be defined.
+* Path expansion:: Special constructs in search paths.
+* Casefolding search:: Fallback to case-insensitive search.
+* Filename database:: Using an externally-built list to search.
+* Invoking kpsewhich:: Standalone path lookup.
+@end menu
+
+
+@node Searching overview
+@section Searching overview
+
+@cindex searching overview
+@cindex path searching, overview
+@cindex overview of path searching
+
+@cindex search path, defined
+A @dfn{search path} is a colon-separated list of @dfn{path elements},
+which are directory names with a few extra frills. A search path can
+come from (a combination of) many sources; see below. To look up a file
+@samp{foo} along a path @samp{.:/dir}, Kpathsea checks each element of
+the path in turn: first @file{./foo}, then @file{/dir/foo}, returning
+the first match (or possibly all matches).
+
+@cindex magic characters
+@kindex : @r{may not be :}
+@kindex / @r{may not be /}
+The ``colon'' and ``slash'' mentioned here aren't necessarily @samp{:}
+and @samp{/} on non-Unix systems. Kpathsea tries to adapt to other
+operating systems' conventions.
+
+@cindex database search
+@cindex searching the database
+To check a particular path element @var{e}, Kpathsea first sees if a
+prebuilt database (@pxref{Filename database}) applies to @var{e}, i.e.,
+if the database is in a directory that is a prefix of @var{e}. If so,
+the path specification is matched against the contents of the database.
+
+@cindex floating directories
+@cindex filesystem search
+@cindex disk search
+@cindex searching the disk
+If the database does not exist, or does not apply to this path element,
+or contains no matches, the filesystem is searched (if this was not
+forbidden by the specification with @samp{!!} and if the file being
+searched for must exist). Kpathsea constructs the list of directories
+that correspond to this path element, and then checks in each for the
+file being searched for. (To help speed future lookups of files in the
+same directory, the directory in which a file is found is floated to the
+top of the directory list.)
+
+@cindex must exist
+@cindex VF files, not found
+@flindex cmr10.vf
+@findex \openin
+The ``file must exist'' condition comes into play with VF files and
+input files read by the @TeX{} @samp{\openin} command. These files
+might very well not exist (consider @file{cmr10.vf}), and so it would
+be wrong to search the disk for them. Therefore, if you fail to
+update @file{ls-R} when you install a new VF file, it will not be
+found.
+
+Each path element is checked in turn: first the database, then the
+disk. If a match is found, the search stops and the result is
+returned (unless the search explicitly requested all matches). This
+avoids possibly-expensive processing of path specifications that are
+never needed on a particular run.
+
+On Unix-like systems, if no match is found by any of the above, and
+the path element allows checking the filesystem (per the above), a
+final check is made for a case-insensitive match. Thus, looking for a
+name like @samp{./FooBar.TeX} will match a file @samp{./foobar.tex},
+and vice versa. This is not done on Windows. @xref{Casefolding
+search}.
+
+@cindex expansion, path element
+Although the simplest and most common path element is a directory name,
+Kpathsea supports additional features in search paths: layered default
+values, environment variable names, config file values, users' home
+directories, and recursive subdirectory searching. Thus, we say that
+Kpathsea @dfn{expands} a path element, meaning transforming all the
+magic specifications into the basic directory name or names. This
+process is described in the sections below. It happens in the same
+order as the sections.
+
+@cindex absolute filenames
+@cindex relative filenames
+@cindex explicitly relative filenames
+@cindex filenames, absolute or explicitly relative
+Exception to all of the above: If the filename being searched for is
+absolute or explicitly relative, i.e., starts with @samp{/} or @samp{./}
+or @samp{../}, Kpathsea simply checks if that file exists, with a
+fallback to a casefolding match if needed and enabled, as described above.
+
+@cindex permission denied
+@cindex unreadable files
+@cindex access warnings
+@cindex warnings, file access
+@flindex lost+found @r{directory}
+@vindex TEX_HUSH
+Ordinarily, if Kpathsea tries to access a file or directory that
+cannot be read, it gives a warning. This is so you will be alerted to
+directories or files that accidentally lack any read permission (for
+example, a @file{lost+found} directory). If you prefer not to see
+these warnings, include the value @samp{readable} in the
+@code{TEX_HUSH} environment variable or config file value.
+
+This generic path searching algorithm is implemented in
+@file{kpathsea/pathsearch.c}. It is employed by a higher-level
+algorithm when searching for a file of a particular type (@pxref{File
+lookup}, and @ref{Glyph lookup}).
+
+
+@node Path sources
+@section Path sources
+
+@cindex path sources
+@cindex sources for search paths
+
+A search path or other configuration value can come from many sources.
+In the order in which Kpathsea looks for them:
+
+@enumerate
+@item
+@opindex @samp{--cnf-line}, source for path
+A command-line option such as @code{--cnf-line}, available in
+@file{kpsewhich} and most @TeX{} engines. @xref{Path searching
+options}.
+
+@cindex environment variable, source for path
+A user-set environment variable, e.g., @code{TEXINPUTS}.
+Environment variables with an underscore and the program name appended
+override; for example, @code{TEXINPUTS_latex} overrides @code{TEXINPUTS}
+if the program being run is named @samp{latex}.
+
+@item
+A program-specific configuration file, e.g., an @samp{S /a:/b} line in
+Dvips' @file{config.ps} (@pxref{Config files,,, dvips, Dvips}).
+
+@item
+@cindex configuration file, source for path
+@cindex Kpathsea config file, source for path
+@flindex texmf.cnf@r{, source for path}
+A line in a Kpathsea configuration file @file{texmf.cnf}, e.g.,
+@samp{TEXINPUTS=/c:/d} (see below).
+
+@item
+@cindex compilation value, source for path
+The compile-time default (specified in @file{kpathsea/paths.h}).
+@end enumerate
+
+You can see each of these values for a given search path by using the
+debugging options (@pxref{Debugging}).
+
+These sources may be combined via default expansion (@pxref{Default
+expansion}).
+
+@menu
+* Config files:: Kpathsea's runtime config files (texmf.cnf).
+@end menu
+
+
+@node Config files
+@subsection Config files
+
+@cindex config files
+@flindex texmf.cnf@r{, definition for}
+
+@cindex runtime configuration files
+@vindex TEXMFCNF
+As mentioned above, Kpathsea reads @dfn{runtime configuration files}
+named @file{texmf.cnf} for search path and other definitions. The
+search path used to look for these configuration files is named
+@code{TEXMFCNF}, and is constructed in the usual way, as described
+above, except that configuration files cannot be used to define the
+path, naturally; also, an @file{ls-R} database is not used to search for
+them.
+
+Kpathsea reads @emph{all} @file{texmf.cnf} files in the search path, not
+just the first one found; definitions in earlier files override those in
+later files. Thus, if the search path is @samp{.:$TEXMF}, values from
+@file{./texmf.cnf} override those from @file{$TEXMF/texmf.cnf}.
+
+@vindex KPATHSEA_WARNING
+@cindex warning, about missing @file{texmf.cnf}
+@cindex @file{texmf.cnf} missing, warning about
+If Kpathsea cannot find any @file{texmf.cnf} file, it reports a
+warning including all the directories it checked. If you don't want
+to see this warning, set the environment variable
+@env{KPATHSEA_WARNING} to the single character @samp{0} (zero, not
+oh).
+
+While (or instead of) reading this description, you may find it helpful
+to look at the distributed @file{texmf.cnf}, which uses or at least
+mentions most features. The format of @file{texmf.cnf} files follows:
+
+@itemize @bullet
+@item
+@cindex comments, in @file{texmf.cnf}
+Comments start with @samp{%}, either at the beginning of a line or
+preceded by whitespace, and continue to the end of the line. That is,
+similar to most shells, a @samp{%} in the ``middle'' of a value does not
+start a comment. Examples:
+
+@example
+% this is a comment
+var = a%b % but the value of var will be "a%b"
+@end example
+
+@item
+@cindex blank lines, in @file{texmf.cnf}
+Blank lines are ignored.
+
+@item
+@cindex backslash-newline
+@cindex continuation character
+@cindex whitespace, not ignored on continuation lines
+@kindex \@r{, line continuation in @file{texmf.cnf}}
+A @samp{\} at the end of a line acts as a continuation character, i.e.,
+the next line is appended. Whitespace at the beginning of continuation
+lines is not ignored.
+
+@item Each remaining line will look like:
+
+@example
+@var{variable} @r{[}. @var{progname}@r{]} @r{[}=@r{]} @var{value}
+@end example
+
+@noindent where the @samp{=} and surrounding whitespace is optional.
+
+@item
+@cindex identifiers, characters valid in
+The @var{variable} name may contain any character other than whitespace,
+@samp{=}, or @samp{.}, but sticking to @samp{A-Za-z_} is safest.
+
+@kindex .@var{progname} @r{qualifier in @file{texmf.cnf}}
+@item If @samp{.@var{progname}} is present (preceding spaces are
+ignored), the definition only applies if the program that is running
+is named (i.e., the last component of @code{argv[0]} is)
+@var{progname} or @file{@var{progname}.@{exe,bat,cmd,...@}}. Most
+notably, this allows different flavors of @TeX{} to have different
+search paths. The @var{progname} value is used literally, without
+variable or other expansions.
+
+@item
+@cindex right-hand side of variable assignments
+Considered as strings, @var{value} may contain any character.
+However, in practice most @file{texmf.cnf} values are related to path
+expansion, and since various special characters are used in expansion,
+such as braces and commas, they cannot be used in directory names.
+
+The @samp{$@var{var}.@var{prog}} feature is not available on the
+right-hand side; instead, you must use an additional variable (see
+below for example).
+
+@kindex ; @r{translated to @samp{:} in @file{texmf.cnf}}
+A @samp{;} in @var{value} is translated to @samp{:} if running under
+Unix, in order to have a single @file{texmf.cnf} that can support both
+Unix and Windows systems. This translation happens with any value, not
+just search paths, but fortunately in practice @samp{;} is not needed
+in other values.
+
+@item All definitions are read before anything is expanded, so you can
+use variables before they are defined (like Make, unlike most other
+programs).
+@end itemize
+
+@noindent Here is a configuration file fragment illustrating most of
+these points:
+
+@example
+% TeX input files -- i.e., anything to be found by \input or \openin ...
+latex209_inputs = .:$TEXMF/tex/latex209//:$TEXMF/tex//
+latex2e_inputs = .:$TEXMF/tex/latex//:$TEXMF/tex//
+TEXINPUTS = .:$TEXMF/tex//
+TEXINPUTS.latex209 = $latex209_inputs
+TEXINPUTS.latex2e = $latex2e_inputs
+TEXINPUTS.latex = $latex2e_inputs
+@end example
+
+@cindex shell scripts as configuration files
+@cindex configuration files as shell scripts.
+This format has some similarity to Bourne shell scripts---change the
+comment character to @code{#}, disallow spaces around the @code{=},
+and get rid of the @code{.@var{name}} convention, and it could be run
+through the shell. However, there seemed little advantage in this,
+since all the information would have to passed back to Kpathsea and
+parsed there anyway, since the @code{sh} process couldn't affect its
+parent's environment.
+
+@kindex = @r{omitted in @file{texmf.cnf} and misparsing}
+The combination of spaces being ignored before the @code{.} of a
+program name qualifer and the optional @samp{=} for the assignment has
+an unexpected consequence: if the value begins with a literal @samp{.}
+and the @samp{=} is omitted, the intended value is interpreted as a
+program name. For example, a line @code{var .;/some/path} is taken as
+an empty value for @code{var} running under the program named
+@samp{;/some/path}. To diagnose this, Kpathsea warns if the program
+name contains a path separator or other special character. The
+simplest way to avoid the problem is to use the @code{=}.
+
+Exactly when a character will be considered special or act as itself
+depends on the context in which it is used. The rules are inherent in
+the multiple levels of interpretation of the configuration (parsing,
+expansion, search, @dots{}) and so cannot be concisely stated,
+unfortunately. There is no general escape mechanism; in particular,
+@samp{\} is not an ``escape character'' in @file{texmf.cnf} files.
+When it comes choosing directory names for installation, it is safest to
+avoid them all.
+
+@flindex cnf.c
+The implementation of all this is in @file{kpathsea/cnf.c}.
+
+
+@node Path expansion
+@section Path expansion
+
+@cindex path expansion
+@cindex expansion, search path
+
+Kpathsea recognizes certain special characters and constructions in
+search paths, similar to that in shells. As a general example:
+@samp{~$USER/@{foo,bar@}//baz} expands to all subdirectories under
+directories @file{foo} and @file{bar} in @t{$USER}'s home directory that
+contain a directory or file @file{baz}.
+
+These expansions are explained in the sections below.
+
+@menu
+* Default expansion:: a: or :a or a::b expands to a default.
+* Variable expansion:: $foo and $@{foo@} expand to environment values.
+* Tilde expansion:: ~ and ~user expand to home directories.
+* Brace expansion:: a@{foo,bar@}b expands to afoob abarb.
+* KPSE_DOT expansion:: . is replaced with $KPSE_DOT if it is defined.
+* Subdirectory expansion:: a// and a//b recursively expand to subdirs.
+@end menu
+
+
+@node Default expansion
+@subsection Default expansion
+
+@kindex :: @r{expansion}
+@cindex doubled colons
+@cindex leading colons
+@cindex trailing colons
+@cindex extra colons
+@cindex default expansion
+@cindex expansion, default
+
+If the highest-priority search path (@pxref{Path sources}) contains an
+@dfn{extra colon} (i.e., leading, trailing, or doubled), Kpathsea
+inserts at that point the next-highest-priority search path that is
+defined. If that inserted path has an extra colon, the same happens
+with the next-highest. (An extra colon in the compile-time default
+value has unpredictable results, so installers beware.)
+
+For example, given an environment variable setting
+
+@example
+setenv TEXINPUTS /home/karl:
+@end example
+
+@noindent and a @code{TEXINPUTS} value from @file{texmf.cnf} of
+
+@example
+.:$TEXMF//tex
+@end example
+
+@noindent then the final value used for searching will be:
+
+@example
+/home/karl:.:$TEXMF//tex
+@end example
+
+Put another way, default expansion works on ``formats'' (search
+paths), and not directly on environment variables. Example, showing
+the trailing @samp{:} ignored in the first case and expanded in the second:
+
+@example
+$ env TTFONTS=/tmp: kpsewhich --expand-path '$TTFONTS'
+/tmp
+$ env TTFONTS=/tmp: kpsewhich --show-path=.ttf
+/tmp:.:/home/olaf/texmf/fonts/truetype//:...
+@end example
+
+Since Kpathsea looks for multiple configuration files, it would be
+natural to expect that (for example) an extra colon in
+@file{./texmf.cnf} would expand to the path in @file{$TEXMF/texmf.cnf}.
+Or, with Dvips' configuration files, that an extra colon in
+@file{config.$PRINTER} would expand to the path in @file{config.ps}.
+This doesn't happen. It's not clear this would be desirable in all
+cases, and trying to devise a way to specify the path to which the extra
+colon should expand seemed truly baroque.
+@cindex Bach, Johann Sebastian
+
+Technicality: Since it would be useless to insert the default value in
+more than one place, Kpathsea changes only one extra @samp{:} and leaves
+any others in place (they will eventually be ignored). Kpathsea checks
+first for a leading @samp{:}, then a trailing @samp{:}, then a doubled
+@samp{:}.
+
+@flindex kdefault.c
+You can trace this by debugging ``paths'' (@pxref{Debugging}).
+Default expansion is implemented in the source file
+@file{kpathsea/kdefault.c}.
+
+
+@node Variable expansion
+@subsection Variable expansion
+
+@kindex $ @r{expansion}
+@cindex environment variables in paths
+@cindex variable expansion
+@cindex expansion, variable
+@flindex texmf.cnf@r{, and variable expansion}
+
+@samp{$foo} or @samp{$@{foo@}} in a path element is replaced by (1) the
+value of an environment variable @samp{foo} (if defined); (2) the value
+of @samp{foo} from @file{texmf.cnf} (if defined); (3) the empty string.
+
+If the character after the @samp{$} is alphanumeric or @samp{_}, the
+variable name consists of all consecutive such characters. If the
+character after the @samp{$} is a @samp{@{}, the variable name consists
+of everything up to the next @samp{@}} (braces may not be nested around
+variable names). Otherwise, Kpathsea gives a warning and ignores the
+@samp{$} and its following character.
+
+@cindex quoting variable values
+@cindex shell variables
+You must quote the @t{$}'s and braces as necessary for your shell.
+@emph{Shell} variable values cannot be seen by Kpathsea, i.e., ones
+defined by @code{set} in C shells and without @code{export} in Bourne
+shells.
+
+For example, given
+@example
+setenv tex /home/texmf
+setenv TEXINPUTS .:$tex:$@{tex@}prev
+@end example
+@noindent the final @code{TEXINPUTS} path is the three directories:
+@example
+.:/home/texmf:/home/texmfprev
+@end example
+
+The @samp{.@var{progname}} suffix on variables and
+@samp{_@var{progname}} on environment variable names are not implemented
+for general variable expansions. These are only recognized when search
+paths are initialized (@pxref{Path sources}).
+
+@flindex variable.c
+Variable expansion is implemented in the source file
+@file{kpathsea/variable.c}.
+
+
+@node Tilde expansion
+@subsection Tilde expansion
+
+@kindex ~ @r{expansion}
+@cindex home directories in paths
+@cindex tilde expansion
+@cindex expansion, tilde
+
+@vindex HOME@r{, as ~ expansion}
+@vindex USERPROFILE@r{, as ~ expansion}
+A leading @samp{~} in a path element is replaced by the value of the
+environment variable @code{HOME}, or @file{.} if @code{HOME} is not
+set. On Windows, the environment variable @code{USERPROFILE} is
+checked instead of @code{HOME}.
+
+A leading @samp{~@var{user}} in a path element is replaced by
+@var{user}'s home directory from the system @file{passwd} database.
+
+For example,
+@example
+setenv TEXINPUTS ~/mymacros:
+@end example
+
+@noindent will prepend a directory @file{mymacros} in your home
+directory to the default path.
+
+@cindex @t{root} user
+@cindex trailing @samp{/} in home directory
+@kindex /@r{, trailing in home directory}
+As a special case, if a home directory ends in @samp{/}, the trailing
+slash is dropped, to avoid inadvertently creating a @samp{//} construct
+in the path. For example, if the home directory of the user @samp{root}
+is @samp{/}, the path element @samp{~root/mymacros} expands to just
+@samp{/mymacros}, not @samp{//mymacros}.
+
+@flindex tilde.c
+Tilde expansion is implemented in the source file @file{kpathsea/tilde.c}.
+
+
+@node Brace expansion
+@subsection Brace expansion
+
+@kindex @{ @r{expansion}
+@cindex brace expansion
+
+@samp{x@{@var{a},@var{b}@}y} expands to @samp{x@var{a}y:x@var{b}y}.
+For example:
+
+@example
+foo/@{1,2@}/baz
+@end example
+
+@noindent expands to @samp{foo/1/baz:foo/2/baz}. @samp{:} is the path
+separator on the current system; e.g., on a Windows system, it's @samp{;}.
+
+Braces can be nested; for example, @samp{x@{A,B@{1,2@}@}y} expands to
+@samp{xAy:xB1y:xB2y}.
+
+Multiple non-nested braces are expanded from right to left; for example,
+@samp{x@{A,B@}@{1,2@}y} expands to @samp{x@{A,B@}1y:x@{A,B@}2y}, which
+expands to @samp{xA1y:xB1y:xA2y:xB2y}.
+
+@cindex multiple @TeX{} hierarchies
+This feature can be used to implement multiple @TeX{} hierarchies, by
+assigning a brace list to @code{$TEXMF}, as mentioned in
+@file{texmf.in}.
+
+You can also use the path separator instead of the comma. The last
+example could have been written @samp{x@{A:B@}@{1:2@}y} (on Unix).
+
+
+@flindex expand.c
+Brace expansion is implemented in the source file
+@file{kpathsea/expand.c}.
+
+
+@node KPSE_DOT expansion
+@subsection @code{KPSE_DOT} expansion
+
+@kindex KPSE_DOT @r{expansion}
+
+When @code{KPSE_DOT} is defined in the environment, it names a directory
+that should be considered the current directory for the purpose of
+looking up files in the search paths. This feature is needed by the
+@samp{mktex@dots{}} scripts @ref{mktex scripts}, because these
+change the working directory. You should not ever define it yourself.
+
+
+@node Subdirectory expansion
+@subsection Subdirectory expansion
+
+@kindex //
+@cindex subdirectory searching
+@cindex expansion, subdirectory
+
+@cindex alphabetical order, not
+Two or more consecutive slashes in a path element following a directory
+@var{d} is replaced by all subdirectories of @var{d}: first those
+subdirectories directly under @var{d}, then the subsubdirectories under
+those, and so on. At each level, the order in which the directories are
+searched is unspecified. (It's ``directory order'', and definitely not
+alphabetical.)
+
+If you specify any filename components after the @samp{//}, only
+subdirectories which match those components are included. For example,
+@samp{/a//b} would expand into directories @file{/a/1/b}, @file{/a/2/b},
+@file{/a/1/1/b}, and so on, but not @file{/a/b/c} or @file{/a/1}.
+
+You can include multiple @samp{//} constructs in the path.
+
+@samp{//} at the beginning of a path is ignored; you didn't really want
+to search every directory on the system, did you?
+
+@cindex trick for detecting leaf directories
+@cindex leaf directory trick
+@cindex Farwell, Matthew
+@cindex MacKenzie, David
+I should mention one related implementation trick, which I took from GNU
+find. Matthew Farwell suggested it, and David MacKenzie implemented it.
+
+@vindex st_nlink
+The trick is that in every real Unix implementation (as opposed to the
+POSIX specification), a directory which contains no subdirectories will
+have exactly two links (namely, one for @file{.} and one for @file{..}).
+That is to say, the @code{st_nlink} field in the @samp{stat} structure
+will be two. Thus, we don't have to stat everything in the bottom-level
+(leaf) directories---we can just check @code{st_nlink}, notice it's two,
+and do no more work.
+
+But if you have a directory that contains a single subdirectory and 500
+regular files, @code{st_nlink} will be 3, and Kpathsea has to stat every
+one of those 501 entries. Therein lies slowness.
+
+@vindex ST_NLINK_TRICK
+You can disable the trick by undefining @code{ST_NLINK_TRICK} in
+@file{kpathsea/config.h}. (It is undefined by default except under Unix.)
+
+@flindex elt-dirs.c
+Unfortunately, in some cases files in leaf directories are
+@code{stat}'d: if the path specification is, say,
+@samp{$TEXMF/fonts//pk//}, then files in a subdirectory
+@samp{@dots{}/pk}, even if it is a leaf, are checked. The reason
+cannot be explained without reference to the implementation, so read
+@file{kpathsea/elt-dirs.c} (search for @samp{may descend}) if you are
+curious. And if you find a way to solve the problem, please let me
+know.
+
+@flindex elt-dirs.c
+Subdirectory expansion is implemented in the source file
+@file{kpathsea/elt-dirs.c}.
+
+
+@node Casefolding search
+@section Casefolding search
+
+@cindex casefolding search
+@cindex search, case-insensitive
+
+In Kpathsea version 6.3.0 (released with @TeX{} Live 2018), a new
+fallback search was implemented on Unix-like systems, including Macs:
+for each path element in turn, if no match is found by the normal
+search, and the path element allows for checking the filesystem, a
+second check is made for a case-insensitive match.
+
+@vindex texmf_casefold_search
+This is enabled at compile-time on Unix systems, and enabled at
+runtime by setting the configuration variable
+@code{texmf_casefold_search}, to a true value, e.g., @samp{1}; this is
+done by default in @TeX{} Live.
+
+@menu
+* Rationale: Casefolding rationale.
+* Examples: Casefolding examples.
+@end menu
+
+@node Casefolding rationale
+@subsection Casefolding rationale
+
+@cindex casefolding fallback rationale
+@cindex rationale for casefolding fallback
+@cindex system-dependent casefolding behavior
+
+@cindex filesystem, case-(in)sensitive
+@cindex Apple filesystem, case-insensitive
+@cindex Mac filesystem, case-insensitive
+The purpose of the fallback casefolding search is to ease moving
+complex documents between case-insensitive (file)systems and
+case-sensitive ones. In particular, Apple decided to make the default
+filesystem on Macs be case-insensitive some years ago, and this has
+exacerbated a problem of people creating documents that use, say, an
+image under the name @file{foo.jpg}, while the actual file is named
+@file{foo.JPG} or @file{Foo.jpg}. It works on the Mac but if the
+document is transferred and run on a standard case-sensitive Unix
+(file)system, the file can't be found, due only to differences in
+case.
+
+This same problematic scenario has always existed on Windows, but for
+whatever reason, it has become much more common since Apple also went
+to a case-insensitive filesystem. Hence the relatively late change
+to the Kpathsea behavior.
+
+@cindex Windows and casefolding
+The fallback case-insensitive search is omitted at compile-time on
+Windows, where (for practical purposes) all file names are
+case-insensitive at the kernel level, and so the normal search will
+already have definitively matched or not. Therefore, search results
+in unusual cases can be different on Windows and Unix---but this has
+always been true.
+
+
+@node Casefolding examples
+@subsection Casefolding examples
+
+@cindex casefolding examples
+@cindex examples, of casefolding searches
+
+The casefolding implementation prefers exact matches to casefolded
+matches within a given path element, so as to retain most
+compatibility. Backward compatibility is not perfect, however, as a
+casefolded match may be found in an earlier path element than an exact
+match was previously found (see example #4 below). Still, preferring
+the match in the earlier element seemed potentially less confusing
+than otherwise, and is in fact consistent with past behavior on
+Windows. Since case mismatches are rare to begin with, and name
+collisions with respect only to case thus even more rare, the hope is
+that it will not cause difficulties in practice.
+
+If it's desirable in a given situation to have the exact same search
+behavior as previously, that can be accomplished by setting the
+configuration variable @code{texmf_casefold_search} to @samp{0}
+(@pxref{Path sources}).
+
+Some examples to illustrate the new behavior follow.
+
+Example #1: suppose the file @file{./foobar.tex} exists. Now,
+searching for @file{./FooBar.TeX} (or any other case variation) will
+succeed, returning @file{./foobar.tex}---the name as stored on disk.
+In previous releases, or if @code{texmf_casefold_search} is false, the
+search would fail.
+
+Example #2: suppose we are using a case-sensitive (file)system, and
+the search path is @samp{.:/somedir}, and the files
+@file{./foobar.tex} and @file{/somedir/FooBar.TeX} both exist. Both
+now and previously, searching for @file{foobar.tex} returns
+@file{./foobar.tex}. However, searching for @file{FooBar.TeX} now
+returns @file{./foobar.tex} instead of @file{/somedir/FooBar.TeX};
+this is the incompatibility mentioned above. Also (as expected),
+searching for @file{FOOBAR.TEX} (or whatever variation) will now
+return @file{./foobar.tex}, whereas before it would fail. Searching
+for all (@samp{kpsewhich --all}) @file{foobar.tex} will return both
+matches.
+
+Example #3: same as example #2, but on a case-insensitive
+(file)system: both now and previously, searching for @file{FooBar.TeX}
+returns @file{./foobar.tex}, since the system considers that a match.
+The Kpathsea casefolding never comes into play.
+
+Example #4: if we have (on a case-sensitive system) both
+@file{./foobar.tex} and @file{./FOOBAR.TEX}, searching with the exact
+case returns that exact match, now and previously. Searching for
+@file{FooBar.tex} will now return one or the other (chosen
+arbitrarily), rather than failing. Perhaps unexpectedly, searching
+for all @file{foobar.tex} or @file{FooBar.tex} will also return only
+one or the other, not both (see more below).
+
+Example #5: the font file @file{STIX-Regular.otf} is included in
+@TeX{} Live in the system directory
+@file{texmf-dist/fonts/opentype/public/stix}. Because Kpathsea never
+searches the disk in the big system directory, the casefolding is not
+done, and a search for @samp{stix-regular.otf} will fail (on
+case-sensitive systems), as it always has.
+
+@kindex !! @r{and casefolding}
+The caveat about not searching the disk amounts to saying that
+casefolding does not happen in the trees specified with @samp{!!}
+(@pxref{ls-R}), that is, where only database (@file{ls-R}) searching
+is done. In @TeX{} Live, that is the @samp{texmf-local} and
+@samp{texmf-dist} trees (also @code{$TEXMFSYSCONFIG} and
+@code{$TEXMFSYSVAR}, but those are rarely noticed). The rationale for
+this is that in practice, case mangling happens with user-created
+files, not with packages distributed as part of the @TeX{} system.
+
+One more caveat: the purpose of @code{kpsewhich} is to exercise the
+path searching in Kpathsea as it is actually done. Therefore, as
+shown above, @samp{kpsewhich --all} will not return all matches
+regardless of case within a given path element. If you want to find
+all matches in all directories, @code{find} is the best tool, although
+the setup takes a couple steps:
+
+@example
+kpsewhich -show-path=tex >/tmp/texpath # search path specification
+kpsewhich -expand-path="`cat /tmp/texpath`" >/tmp/texdirs # all dirs
+tr ':' '\n' </tmp/texdirs >/tmp/texdirlist # colons to newlines
+find `cat /tmp/texdirlist` -iname somefile.tex -print </tmp/texdirlist
+@end example
+
+@cindex Findutils, GNU package
+@opindex -iname@r{, find predicate}
+Sorry that it's annoyingly lengthy, but implementing this inside
+Kpathsea would be a lot of error-prone trouble for something that is
+only useful for debugging. If your @code{find} does not support
+@code{-iname}, you can get GNU Find from
+@url{https://gnu.org/software/findutils}.
+
+The casefolding search is implemented in the source file
+@file{kpathsea/pathsearch.c}. Two implementation points:
+
+@itemize
+@findex access @r{system call}
+@item
+Kpathsea never tries to check if a given directory resides on a
+case-insensitive filesystem, because there is no efficient and
+portable way to do so. All it does is try to see if a potential file
+name is a readable normal file (with, usually, the @code{access}
+system call).
+
+@item
+Kpathsea does not do any case-insensitive matching of the directories
+along the path. It's not going to find @file{/Some/Random/file.tex}
+when looking for @file{/some/random/file.tex}. The casefolding only
+happens with the elements of the leaf directory.
+
+@end itemize
+
+
+@node Filename database
+@section Filename database (@code{ls-R})
+
+@cindex filename database
+@cindex database, for filenames
+@cindex externally-built filename database
+
+Kpathsea goes to some lengths to minimize disk accesses for searches
+(@pxref{Subdirectory expansion}). Nevertheless, in practice searching
+every possible directory in typical @TeX{} installations takes an
+excessively long time.
+
+Therefore, Kpathsea can use an externally-built @dfn{filename
+database} file named @file{ls-R} that maps files to directories, thus
+avoiding the need to exhaustively search the disk.
+
+A second database file @file{aliases} allows you to give additional
+names to the files listed in @file{ls-R}.
+
+The @file{ls-R} and @file{aliases} features are implemented in the
+source file @file{kpathsea/db.c}.
+
+@menu
+* ls-R:: The main filename database.
+* Filename aliases:: Aliases for those names.
+* Database format:: Syntax details of the database file.
+@end menu
+
+
+@node ls-R
+@subsection @file{ls-R}
+
+@flindex ls-R @r{database file}
+
+As mentioned above, you must name the main filename database
+@file{ls-R}. You can put one at the root of each @TeX{} installation
+hierarchy you wish to search (@code{$TEXMF} by default, which expands
+to a braced list of several hierarchies in @TeX{} Live).
+
+@vindex TEXMFDBS
+@kindex !! @r{in @code{TEXMFDBS}}
+Kpathsea looks for @file{ls-R} files along the @code{TEXMFDBS}
+path. It is best for this to contain all and only those hierarchies
+from @code{$TEXMF} which are specified with @code{!!}---and also to
+specify them with @code{!!} in @code{TEXMFDBS}. (See the end of this
+section for more on @code{!!}.)
+
+The recommended way to create and maintain @samp{ls-R} is to run the
+@code{mktexlsr} script, which is installed in @samp{$(bindir)}
+(@file{/usr/local/bin} by default). That script goes to some trouble to
+follow symbolic links as necessary, etc. It's also invoked by the
+distributed @samp{mktex@dots{}} scripts.
+
+@flindex ls-R@r{, simplest build}
+At its simplest, though, you can build @file{ls-R} with the command
+@example
+cd @var{/your/texmf/root} && ls -LAR ./ >ls-R
+@end example
+
+@noindent
+@opindex --color=tty
+@flindex /etc/profile @r{and aliases}
+presuming your @code{ls} produces the right output format (see the
+section below). GNU @code{ls}, for example, outputs in this format.
+Also presuming your @code{ls} hasn't been aliased in a system file
+(e.g., @file{/etc/profile}) to something problematic, e.g., @samp{ls
+--color=tty}. In that case, you will have to disable the alias before
+generating @file{ls-R}. For the precise definition of the file format,
+see @ref{Database format}.
+
+Regardless of whether you use the supplied script or your own, you
+will almost certainly want to invoke it via @code{cron}, so when you
+make changes in the installed files (say if you install a new @LaTeX{}
+package), @file{ls-R} will be automatically updated. However, for
+those using @TeX{} Live or system distributions, the package managers
+should run @code{mktexlsr} as needed.
+
+@opindex -A @r{option to @code{ls}}
+@cindex dot files
+@flindex . @r{files}
+@flindex . @r{directories, ignored}
+@flindex .tex @r{file, included in @file{ls-R}}
+The @samp{-A} option to @code{ls} includes files beginning with @samp{.}
+(except for @file{.} and @file{..}), such as the file @file{.tex}
+included with the @LaTeX{} tools package. (On the other hand,
+@emph{directories} whose names begin with @samp{.} are always ignored.)
+
+@cindex symbolic links, and @file{ls-R}
+@opindex -L @r{option to @code{ls}}
+If your system does not support symbolic links, omit the @samp{-L}.
+
+@cindex automounter, and @file{ls-R}
+@cindex NFS and @file{ls-R}
+@code{ls -LAR @var{/your/texmf/root}} will also work. But using
+@samp{./} avoids embedding absolute pathnames, so the hierarchy can be
+easily transported. It also avoids possible trouble with automounters
+or other network filesystem conventions.
+
+@cindex warning about unusable @file{ls-R}
+@cindex unusable @file{ls-R} warning
+Kpathsea warns you if it finds an @file{ls-R} file, but the file does
+not contain any usable entries. The usual culprit is running plain
+@samp{ls -R} instead of @samp{ls -LR ./} or @samp{ls -R
+@var{/your/texmf/root}}. Another possibility is some system directory
+name starting with a @samp{.} (perhaps if you are using AFS); Kpathsea
+ignores everything under such directories.
+
+@kindex !! @r{in path specifications}
+@cindex disk searching, avoiding
+If a particular path element begins with @samp{!!}, @emph{only} the
+database will be searched for that element, never the disk; and if the
+database does not exist, nothing at all will be searched. In @TeX{}
+Live, most of the trees are specified with @samp{!!}.
+
+For path elements that do not begin with @samp{!!}, if the database
+exists, it will be used, and the disk will not be searched. However,
+in this case, if the database does not exist, the disk will be
+searched. In @TeX{} Live, the most notable case of this is the
+@code{TEXMFHOME} tree, to allow users to add and remove files from
+their own tree without having to worry about @code{ls-R}.
+
+(Aside: there are uncommon cases where a @samp{!!} tree will be
+searched on disk even if the @code{ls-R} file exists; they are too
+obscure to try to explain here. See @file{pathsearch.c} in the source
+if you need to know.)
+
+To sum up: do not create an @code{ls-R} file unless you also take care
+to keep it up to date. Otherwise newly-installed files will not be
+found.
+
+
+
+@node Filename aliases
+@subsection Filename aliases
+
+@cindex filename aliases
+@cindex aliases, for filenames
+
+In some circumstances, you may wish to find a file under several names.
+For example, suppose a @TeX{} document was created using a DOS system
+and tries to read @file{longtabl.sty}. But now it's being run on a Unix
+system, and the file has its original name, @file{longtable.sty}. The
+file won't be found. You need to give the actual file
+@file{longtable.sty} an alias @samp{longtabl.sty}.
+
+@c As another example, suppose you are creating a @TeX{} distribution on a
+@c CD-ROM or a DOS system; then the file @file{mf.base} gets stored as
+@c @file{mf.bas}. But Metafont on Unix wants to find @file{mf.base}. Here
+@c you need to give the actual file @file{mf.bas} an alias @samp{mf.base}.
+
+You can handle this by creating a file @file{aliases} as a companion to
+the @file{ls-R} for the hierarchy containing the file in question. (You
+must have an @file{ls-R} for the alias feature to work.)
+
+The format of @file{aliases} is simple: two whitespace-separated words
+per line; the first is the real name @file{longtable.sty}, and second is
+the alias (@file{longtabl.sty}). These must be base filenames, with no
+directory components. @file{longtable.sty} must be in the sibling
+@file{ls-R}.
+
+Also, blank lines and lines starting with @samp{%} or @samp{#} are
+ignored in @file{aliases}, to allow for comments.
+
+If a real file @file{longtabl.sty} exists, it is used regardless of any
+aliases.
+
+
+@node Database format
+@subsection Database format
+
+@cindex format of external database
+@cindex database, format of
+
+The ``database'' read by Kpathsea is a line-oriented file of plain
+text. The format is that generated by GNU (and most other) @code{ls}
+programs given the @samp{-R} option, as follows.
+
+@itemize @bullet
+@item
+Blank lines are ignored.
+
+@item
+If a line begins with @samp{/} or @samp{./} or @samp{../} and ends with
+a colon, it's the name of a directory. (@samp{../} lines aren't useful,
+however, and should not be generated.)
+
+@item
+All other lines define entries in the most recently seen directory.
+@t{/}'s in such lines will produce possibly-strange results.
+
+@item
+Files with no preceding directory line are ignored.
+@end itemize
+
+For example, here's the first few lines of @file{ls-R} (which totals
+about 30K bytes) on my system:
+
+@example
+bibtex
+dvips
+fonts
+ls-R
+metafont
+metapost
+tex
+web2c
+
+./bibtex:
+bib
+bst
+doc
+
+./bibtex/bib:
+asi.bib
+btxdoc.bib
+@dots{}
+@end example
+
+
+@node Invoking kpsewhich
+@section @code{kpsewhich}: Standalone path searching
+
+@pindex kpsewhich
+@cindex path searching, standalone
+@cindex standalone path searching
+
+The Kpsewhich program exercises the path searching functionality
+independent of any particular application. This can also be useful as a
+sort of @code{find} program to locate files in your @TeX{} hierarchies,
+perhaps in administrative scripts. It is used heavily in the
+distributed @samp{mktex@dots{}} scripts.
+
+Synopsis:
+
+@example
+kpsewhich @var{option}@dots{} @var{filename}@dots{}
+@end example
+
+The options and filename(s) to look up can be intermixed.
+Options can start with either @samp{-} or @samp{--}, and any unambiguous
+abbreviation is accepted.
+
+@menu
+* Path searching options:: Changing the mode, resolution, etc.
+* Specially-recognized files:: Default formats for texmf.cnf, etc.
+* Auxiliary tasks:: Path and variable expansion, etc.
+* Standard options:: @samp{--help} and @samp{--version}.
+@end menu
+
+
+@node Path searching options
+@subsection Path searching options
+
+@cindex path searching options
+
+Kpsewhich looks up each non-option argument on the command line as a
+filename, and returns the first file found.
+
+Various options alter the path searching behavior:
+
+@table @samp
+@item --all
+@opindex --all
+@cindex all matches, finding
+Report all matches found, one per line. By default, if there is more
+than one match, just one will be reported (chosen effectively at
+random). Exception: with the glyph formats (@code{pk}, @code{gf}),
+this option has no effect and only the first match is returned.
+
+@item --casefold-search
+@itemx --no-casefold-search
+@opindex --casefold-search
+@opindex --no-casefold-search
+Explicitly enable or disable the fallback to a case-insensitive search
+on Unix platforms (@pxref{Casefolding search}); no effect on Windows.
+The default is enabled, set in @code{texmf.cnf}. Disabling
+(@code{--no-casefold-search}) does not mean that searches magically
+become case-sensitive when the underlying (file)system is
+case-insensitive, it merely means that Kpathsea does not do any
+casefolding itself.
+
+@item --cnf-line=@var{str}
+@opindex --cnf-line
+Parse @var{str} as if it were a line in the @file{texmf.cnf}
+configuration file (@pxref{Config files}), overriding settings in the
+actual configuration files, and also in the environment (@pxref{Path
+sources}). This is implemented by making any settings from @var{str}
+in the environment, overwriting any value already there. Thus, an
+extra colon in a @samp{--cnf-line} value will refer to the value from
+a configuration file, not a user-set environment variable.
+
+Furthermore, any variable set from @var{str} will also be set with the
+program name suffix. For example, @code{pdftex
+--cnf-line=TEXINPUTS=/foo:} will set both @code{TEXINPUTS} and
+@code{TEXINPUTS_pdftex} in the environment (and the value will be
+@file{/foo} followed by the setting from @file{texmf.cnf}, ignoring
+any user-set @code{TEXINPUTS}).
+
+This behavior is desirable because, in practice, many variables in the
+distributed @file{texmf.cnf} are program-specific, and the intuitive
+behavior is for values set on the command line with @code{--cnf-line}
+to override them.
+
+@item --dpi=@var{num}
+@opindex --dpi=@var{num}
+@opindex -D @var{num}
+@cindex resolution, setting
+Set the resolution to @var{num}; this only affects @samp{gf} and
+@samp{pk} lookups. @samp{-D} is a synonym, for compatibility with
+Dvips. Default is 600.
+
+@item --engine=@var{name}
+@opindex --engine=@var{name}
+@cindex engine name
+Set the engine name to @var{name}. By default it is not set. The
+engine name is used in some search paths to allow files with the same
+name but used by different engines to coexist.
+
+In particular, since the memory dump files
+(@file{.fmt}/@file{.base}/@file{.mem}) are now stored in
+subdirectories named for the engine (@file{tex}, @file{pdftex},
+@file{xetex}, etc.), you must specify an engine name in order to find
+them. For example, @file{cont-en.fmt} typically exists for both
+@file{pdftex} and @file{xetex}. With the default path settings, you
+can use @samp{--engine=/} to look for any dump file, regardless of
+engine; if a dump file exists for more than one engine, it's
+indeterminate which one is returned. (The @samp{/} ends up specifying
+a normal recursive search along the path where the dumps are stored,
+namely @samp{$TEXMF/web2c@{/$engine,@}}.)
+
+@item --format=@var{name}
+@opindex --format=@var{name}
+Set the format for lookup to @var{name}. By default, the format is
+guessed from the filename, with @samp{tex} being used if nothing else
+fits. The recognized filename extensions (including any leading
+@samp{.}) are also allowable @var{name}s.
+
+All formats also have a name, which is the only way to specify formats
+with no associated suffix. For example, for Dvips configuration files
+you can use @samp{--format="dvips config"}. (The quotes are for the
+sake of the shell.)
+
+Here's the current list of recognized names and the associated suffixes.
+@xref{Supported file formats}, for more information on each of these.
+
+The strings in parentheses are abbreviations recognized only by
+@code{kpsewhich} (not the underlying library calls). They are
+provided when it would otherwise require an argument containing a
+space to specify the format, to simplify quoting of calls from shells.
+
+@example
+gf: gf
+pk: pk
+bitmap font (bitmapfont):
+tfm: .tfm
+afm: .afm
+base: .base
+bib: .bib
+bst: .bst
+cnf: .cnf
+ls-R: ls-R ls-r
+fmt: .fmt
+map: .map
+mem: .mem
+mf: .mf
+mfpool: .pool
+mft: .mft
+mp: .mp
+mppool: .pool
+MetaPost support (mpsupport):
+ocp: .ocp
+ofm: .ofm .tfm
+opl: .opl .pl
+otp: .otp
+ovf: .ovf .vf
+ovp: .ovp .vpl
+graphic/figure: .eps .epsi
+tex: .tex .sty .cls .fd .aux .bbl .def .clo .ldf
+TeX system documentation (doc):
+texpool: .pool
+TeX system sources (source): .dtx .ins
+PostScript header: .pro
+Troff fonts (trofffont):
+type1 fonts: .pfa .pfb
+vf: .vf
+dvips config (dvipsconfig):
+ist: .ist
+truetype fonts: .ttf .ttc .TTF .TTC .dfont
+type42 fonts: .t42 .T42
+web2c files (web2c):
+other text files (othertext):
+other binary files (otherbin):
+misc fonts (miscfont):
+web: .web .ch
+cweb: .w .web .ch
+enc files: .enc
+cmap files (cmap):
+subfont definition files: .sfd
+opentype fonts: .otf
+pdftex config (pdftexconfig):
+lig files: .lig
+texmfscripts:
+lua: .lua .luatex .luc .luctex .texlua .texluc .tlu
+font feature files: .fea
+cid maps: .cid .cidmap
+mlbib: .mlbib .bib
+mlbst: .mlbst .bst
+clua: .dll .so
+ris: .ris
+bltxml: .bltxml
+@end example
+
+This option and @samp{--path} are mutually exclusive.
+
+@item --interactive
+@opindex --interactive
+@cindex interactive query
+After processing the command line, read additional filenames to look up
+from standard input.
+
+@item --mktex=@var{filetype}
+@itemx --no-mktex=@var{filetype}
+@opindex --mktex=@var{filetype}
+@opindex --no-mktex=@var{filetype}
+Turn on or off the @samp{mktex} script associated with @var{filetype}.
+Usual values for @var{filetype} are @samp{pk}, @samp{mf}, @samp{tex},
+and @samp{tfm}. By default, all are off in Kpsewhich, even if they
+are enabled for @TeX{}. This option implies setting
+@code{--must-exist}. @xref{mktex scripts}.
+
+@item --mode=@var{string}
+@opindex --mode=@var{string}
+Set the mode name to @var{string}; this also only affects @samp{gf} and
+@samp{pk} lookups. No default: any mode will be found. @xref{mktex
+script arguments}.
+
+@item --must-exist
+@opindex --must-exist
+Do everything possible to find the files, notably including searching
+the disk and running the @samp{mktex} scripts. By default, only the
+@file{ls-R} database is checked, in the interest of efficiency.
+
+@item --path=@var{string}
+@opindex --path=@var{string}
+Search along the path @var{string} (colon-separated as usual), instead
+of guessing the search path from the filename. @samp{//} and all the
+usual expansions are supported (@pxref{Path expansion}). This option
+and @samp{--format} are mutually exclusive. To output the complete
+directory expansion of a path, instead of doing a one-shot lookup, see
+@samp{--expand-path} and @samp{--show-path} in the following section.
+
+@item --progname=@var{name}
+@opindex --progname=@var{name}
+Set the program name to @var{name}; default is @samp{kpsewhich}. This
+can affect the search paths via the @samp{.@var{prognam}} feature in
+configuration files (@pxref{Config files}).
+
+@item --subdir=@var{string}
+@opindex --subdir=@var{string}
+Report only those matches whose directory part @emph{ends} with
+@var{string} (compared literally, except case is ignored on a
+case-insensitive operating system). For example, suppose there are
+two matches for a given name:
+
+@example
+kpsewhich foo.sty
+@result{} /some/where/foo.sty
+/another/place/foo.sty
+@end example
+
+@noindent
+Then we can narrow the result to what we are interested in with
+@option{--subdir}:
+
+@example
+kpsewhich --subdir=where foo.sty
+@result{} /some/where/foo.sty
+
+kpsewhich --subdir=place foo.sty
+@result{} /another/place/foo.sty
+@end example
+
+@noindent
+The string to match must be at the end of the directory part of the
+match, and it is taken literally, with no pattern matching:
+
+@example
+kpsewhich --subdir=another foo.sty
+@result{}
+@end example
+
+@noindent
+The string to match may cross directory components:
+
+@example
+kpsewhich --subdir=some/where foo.sty
+@result{} /some/where/foo.sty
+@end example
+
+@noindent
+@option{--subdir} implies @option{--all}; if there is more than one
+match, they will all be reported (in our example, both @samp{where}
+and @samp{place} end in @samp{e}):
+
+@example
+kpsewhich --subdir=e
+@result{} /some/where/foo.sty
+/another/place/foo.sty
+@end example
+
+@noindent
+Because of the above rules, the presence of a leading @samp{/} is
+important, since it ``anchors'' the match to a full component name:
+
+@example
+kpsewhich --subdir=/lace foo.sty
+@result{}
+@end example
+
+@noindent
+However, a trailing @samp{/} is immaterial (and ignored), since the
+match always takes place at the end of the directory part:
+
+@example
+kpsewhich --subdir=lace/ foo.sty
+@result{} /another/place/foo.sty
+@end example
+
+@noindent
+The purpose of these rules is to make it convenient to find results
+only within a particular area of the tree. For instance, a given
+script named @file{foo.lua} might exist within both
+@file{texmf-dist/scripts/pkg1/} and @file{texmf-dist/scripts/pkg2/}.
+By specifying, say, @samp{--subdir=/pkg1}, you can be sure of getting
+the one you are interested in.
+
+We only match at the end because a site might happen to install @TeX{}
+in @file{/some/coincidental/pkg1/path/}, and we wouldn't want to match
+@file{texmf-dist/scripts/pkg2/} that when searching for @samp{/pkg1}.
+
+@end table
+
+
+@node Specially-recognized files
+@subsection Specially-recognized files for @command{kpsewhich}
+
+@command{kpsewhich} recognizes a few special filenames on the command
+line and defaults to using the `known' file formats for them, merely
+to save the time and trouble of specifying the format. This is only a
+feature of @command{kpsewhich}; when using the Kpathsea library
+itself, none of these special filenames are recognized, and it's still
+up to the caller to specify the desired format.
+
+Here is the list of special filenames to @command{kpsewhich}, along
+with their corresponding format:
+
+@table @file
+
+@flindex config.ps
+@item config.ps
+@code{dvips config}
+
+@flindex dvipdfmx.cfg
+@item dvipdfmx.cfg
+@samp{other text files}
+
+@flindex fmtutil.cnf
+@item fmtutil.cnf
+@samp{web2c files}
+
+@flindex glyphlist.txt
+@item glyphlist.txt
+@samp{map}
+
+@flindex mktex.cnf
+@item mktex.cnf
+@samp{web2c files}
+
+@flindex pdfglyphlist.txt
+@item pdfglyphlist.txt
+@samp{map}
+
+@flindex pdftex.cfg
+@flindex pdftexconfig.tex
+@item pdftex.cfg
+@samp{pdftex config} (although @file{pdftex.cfg} is not used any more;
+look for the file @file{pdftexconfig.tex} instead.)
+
+@flindex texmf.cnf
+@item texmf.cnf
+@samp{cnf}
+
+@flindex XDvi
+@item XDvi
+@samp{other text files}
+
+@end table
+
+A user-specified format will override the above defaults.
+
+@flindex tcfmgr.map
+Another useful configuration file in this regard is @file{tcfmgr.map},
+found in @file{texmf/texconfig/tcfmgr.map}, which records various
+information about the above configuration files (among others).
+
+
+@node Auxiliary tasks
+@subsection Auxiliary tasks
+
+@cindex auxiliary tasks
+
+Kpsewhich provides some features in addition to path lookup as such:
+
+@table @samp
+@item --debug=@var{num}
+@opindex --debug=@var{num}
+Set debugging options to @var{num}. @xref{Debugging}.
+
+@item --expand-braces=@var{string}
+@opindex --expand-braces=@var{string}
+Output variable, tilde, and brace expansion of @var{string}, which is
+assumed to be a single path element. @xref{Path expansion}.
+
+@item --expand-path=@var{string}
+@opindex --expand-path=@var{string}
+Output the complete expansion of @var{string}, with each element
+separated by the usual path separator on the current system (@samp{;}
+on Windows, @samp{:} 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
+@samp{--show-path}.
+
+Nonexistent directories are culled from the output:
+
+@example
+$ kpsewhich --expand-path '/tmp'
+@result{} /tmp
+$ kpsewhich --expand-path '/nonesuch'
+@result{}
+@end example
+
+For one-shot uses of an arbitrary (not built in to Kpathsea) path, see
+@samp{--path} (@pxref{Path searching options}).
+
+@item --expand-var=@var{string}
+@opindex --expand-var=@var{string}
+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}. 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
+Output information about each supported format (@pxref{Supported file
+formats}), including the names and abbreviations, variables
+looked for, and the original path.
+
+@item --safe-in-name=@var{name}
+@itemx --safe-out-name=@var{name}
+@opindex --safe-in-name=@var{name}
+@opindex --safe-out-name=@var{name}
+Exit successfully if @var{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 (@pxref{Calling sequence}).
+
+@item --show-path=@var{name}
+@opindex --show-path=@var{name}
+Show the path that would be used for file lookups of file type
+@var{name}. Either a filename extension (@samp{pk}, @samp{.vf}, etc.)
+or an integer can be used, just as with @samp{--format}, described in
+the previous section.
+
+@item --var-brace-value=@var{variable}
+@opindex --var-brace-value=@var{variable}
+Like @samp{--var-value} (next), but also expands @samp{@{...@}}
+constructs. (@pxref{Brace expansion}). Thus, the value is assumed to
+possibly be several path elements, and @samp{~} is expanded at the
+beginning of each. The path separator is changed to that of the
+current system in the expansion.
+
+Example: @samp{FOO='.;~' kpsewhich --var-brace-value=FOO} outputs (on
+a Unix-ish system) @samp{.:/home/karl}, supposing the latter is the
+current user's home directory. Note that the @samp{;} in the source
+value, as commonly used in @file{texmf.cnf}, has changed to a
+@samp{:}, as the normal path separator on the current system. On a
+Windows-ish system, the @samp{;} would remain.
+
+@item --var-value=@var{variable}
+@opindex --var-value=@var{variable}
+Outputs the value of @var{variable} (a simple identifier like
+@samp{TEXMFDIST}, with no @samp{$} or other constructs), expanding
+@samp{$} (@pxref{Variable expansion}) and @samp{~} (@pxref{Tilde
+expansion}) constructs in the value. @samp{~} 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: @samp{--var-value=texmf_casefold_search} outputs (if the
+default is not changed) @samp{1}.
+
+Example to contrast with @samp{--var-brace-value}: @samp{FOO='.;~'
+kpsewhich --var-value=FOO} outputs @samp{.;~}, i.e., the same as the
+input value, on all systems.
+
+@end table
+
+
+@node Standard options
+@subsection Standard options
+
+@cindex standard options
+
+Kpsewhich accepts the standard GNU options:
+
+@itemize @bullet
+@item
+@opindex --help
+@samp{--help} prints a help message on standard output and exits
+successfully.
+
+@item
+@opindex --version
+@samp{--version} prints the Kpathsea version number and exits successfully.
+@end itemize
+
+
+@node TeX support
+@chapter @TeX{} support
+
+@cindex @TeX{} support
+
+Although the basic features in Kpathsea can be used for any type of
+path searching, it came about, as usual, with a specific application
+in mind: I wrote Kpathsea specifically for @TeX{} system programs. I
+had been struggling with the programs I was using (Dvips, Xdvi, and
+@TeX{} itself) having slightly different notions of how to specify
+paths; and debugging was painful, since no code was shared.
+
+Therefore, Kpathsea provides some @TeX{}-specific formats and
+features. Indeed, many of the purportedly generic path searching
+features were provided because they seemed useful in that con@TeX{}t
+(font lookup, particularly).
+
+Kpathsea provides a standard way to search for files of any of the
+supported file types; glyph fonts are a bit different than all the
+rest. Searches are based solely on names of files, not their
+contents---if a GF file is (mis)named @file{cmr10.600pk}, it will be
+found as a PK file.
+
+@menu
+* Supported file formats:: File types Kpathsea knows about.
+* File lookup:: Searching for most kinds of files.
+* Glyph lookup:: Searching for bitmap fonts.
+* Suppressing warnings:: Avoiding warnings via TEX_HUSH.
+* mktex scripts:: Generating files at runtime.
+@end menu
+
+
+@node Supported file formats
+@section Supported file formats
+
+@cindex supported file formats
+@cindex file formats, supported
+
+@cindex environment variables for @TeX{}
+@cindex @TeX{} environment variables
+
+Kpathsea has support for a number of file types. Each file type has a
+list of environment and config file variables that are checked to define
+the search path, and most have a default suffix that plays a role in
+finding files (see the next section). Some also define additional
+suffixes, and/or a program to be run to create missing files on the fly.
+
+@cindex program-varying paths
+Since environment variables containing periods, such as
+@samp{TEXINPUTS.latex}, are not allowed on some systems, Kpathsea looks
+for environment variables with an underscore, e.g.,
+@samp{TEXINPUTS_latex} (@pxref{Config files}).
+
+The following table lists the above information. You can also get the
+list by giving the @samp{--help-formats} option to @code{kpsewhich}
+(@pxref{Auxiliary tasks}).
+
+@table @samp
+@item afm
+@flindex .afm
+@vindex AFMFONTS
+(Adobe font metrics, @pxref{Metric files,,, dvips, Dvips})
+@code{AFMFONTS};
+suffix @samp{.afm}.
+
+@item base
+@flindex .base
+@vindex MFBASES
+@vindex TEXMFINI
+(Metafont memory dump, @pxref{Memory dumps,,, web2c, Web2c})
+@code{MFBASES}, @code{TEXMFINI};
+suffix @samp{.base}.
+
+@item bib
+@flindex .bib
+@vindex BIBINPUTS
+@vindex TEXBIB
+(Bib@TeX{} bibliography source, @pxref{bibtex invocation,,, web2c, Web2c})
+@code{BIBINPUTS}, @code{TEXBIB};
+suffix @samp{.bib}.
+
+@item bltxml
+@flindex .bltxml
+@vindex BLTXMLINPUTS
+(Bib@LaTeX{}ML bibliography files for Biber, @url{https://ctan.org/pkg/biber})
+@code{BLTXMLINPUTS}
+suffix @samp{.bltxml}.
+
+@item bst
+@flindex .bst
+@vindex BSTINPUTS
+(Bib@TeX{} style, @pxref{Basic BibTeX style files,, Basic Bib@TeX{}
+style files, web2c, Web2c})
+@code{BSTINPUTS};
+suffix @samp{.bst}.
+
+@item clua
+@flindex .dll
+@flindex .so
+@vindex CLUAINPUTS
+(dynamic libraries for Lua, @url{https://ctan.org/pkg/luatex})
+@code{CLUAINPUTS}
+suffixes @samp{.dll} and @samp{.so}.
+
+@item cmap
+@flindex .cmap
+@vindex CMAPFONTS
+(character map files)
+@code{CMAPFONTS};
+suffix @samp{.cmap}.
+
+@item cnf
+@flindex .cnf
+@vindex TEXMFCNF
+(Runtime configuration files, @pxref{Config files})
+@code{TEXMFCNF};
+suffix @samp{.cnf}.
+
+@item cweb
+@flindex .w
+@flindex .web
+@vindex CWEBINPUTS
+(CWEB input files)
+@code{CWEBINPUTS};
+suffixes @samp{.w}, @samp{.web};
+additional suffix @samp{.ch}.
+
+@item dvips config
+@vindex TEXCONFIG
+@flindex config.ps@r{, search path for}
+(Dvips @samp{config.*} files, such as @file{config.ps}, @pxref{Config
+files,,, dvips, Dvips})
+@code{TEXCONFIG}.
+
+@item enc files
+@flindex .enc
+@vindex ENCFONTS
+(encoding vectors)
+@code{ENCFONTS};
+suffix @samp{.enc}.
+
+@item fmt
+@flindex .fmt
+@vindex TEXFORMATS
+@vindex TEXMFINI
+(@TeX{} memory dump, @pxref{Memory dumps,,, web2c, Web2c})
+@code{TEXFORMATS}, @code{TEXMFINI};
+suffix @samp{.fmt}.
+
+@item font cid map
+@flindex .cid
+@vindex FONTCIDMAPS
+(CJK mapping)
+@code{FONTCIDMAPS}
+suffix @samp{.cid}.
+
+@item font feature files
+@flindex .fea
+@vindex FONTFEATURES
+(primarily for OpenType font features)
+@code{FONTFEATURES}
+suffix @samp{.fea}.
+
+@item gf
+@flindex gf
+@vindex GFFONTS
+@vindex GLYPHFONTS
+@vindex TEXFONTS
+(generic font bitmap, @pxref{Glyph files,,, dvips, Dvips})
+@code{@var{program}FONTS}, @code{GFFONTS}, @code{GLYPHFONTS}, @code{TEXFONTS};
+suffix @samp{gf}.
+
+@item graphic/figure
+@flindex .eps
+@flindex .epsi
+@vindex TEXPICTS
+@vindex TEXINPUTS
+(Encapsulated PostScript figures, @pxref{PostScript figures,,, dvips, Dvips})
+@code{TEXPICTS}, @code{TEXINPUTS};
+additional suffixes: @samp{.eps}, @samp{.epsi}.
+
+@item ist
+@flindex .ist
+@vindex TEXINDEXSTYLE
+@vindex INDEXSTYLE
+(makeindex style files)
+@code{TEXINDEXSTYLE}, @code{INDEXSTYLE};
+suffix @samp{.ist}.
+
+@item lig files
+@flindex .lig
+@vindex LIGFONTS
+(ligature definition files)
+@code{LIGFONTS};
+suffix @samp{.lig}.
+
+@item ls-R
+@flindex ls-R
+@vindex TEXMFDBS
+(Filename databases, @pxref{Filename database})
+@code{TEXMFDBS}.
+
+@item map
+@flindex .map
+@vindex TEXFONTMAPS
+(Fontmaps, @pxref{Fontmap})
+@code{TEXFONTMAPS};
+suffix @samp{.map}.
+
+@item mem
+@flindex .mem
+@vindex MPMEMS
+@vindex TEXMFINI
+(MetaPost memory dump, @pxref{Memory dumps,,, web2c, Web2c})
+@code{MPMEMS}, @code{TEXMFINI};
+suffix @samp{.mem}.
+
+@item @r{MetaPost support}
+@vindex MPSUPPORT
+(MetaPost support files, used by DMP; @pxref{dmp invocation,,, web2c, Web2c})
+@code{MPSUPPORT}.
+
+@item mf
+@flindex .mf
+@vindex MFINPUTS
+(Metafont source, @pxref{mf invocation,,, web2c, Web2c})
+@code{MFINPUTS};
+suffix @samp{.mf};
+dynamic creation program: @code{mktexmf}.
+
+@item mfpool
+@flindex .pool
+@vindex MFPOOL
+(Metafont program strings, @pxref{pooltype invocation,,, web2c, Web2c})
+@code{MFPOOL}, @code{TEXMFINI};
+suffix @samp{.pool}.
+
+@item mft
+@flindex .mft
+@vindex MFTINPUTS
+(@code{MFT} style file, @pxref{mft invocation,,, web2c, Web2c})
+@code{MFTINPUTS};
+suffix @samp{.mft}.
+
+@item misc fonts
+@vindex MISCFONTS
+(font-related files that don't fit the other categories)
+@code{MISCFONTS}
+
+@item mlbib
+@flindex .mlbib
+@vindex MLBIBINPUTS
+@vindex BIBINPUTS
+@vindex TEXBIB
+(MlBib@TeX{} bibliography source)
+@code{MLBIBINPUTS}, @code{BIBINPUTS}, @code{TEXBIB};
+suffixes @samp{.mlbib}, @samp{.mlbib}.
+
+@item mlbst
+@flindex .mlbst
+@vindex MLBSTINPUTS
+@vindex BSTINPUTS
+(MlBib@TeX{} style)
+@code{MLBSTINPUTS}, @code{BSTINPUTS};
+suffixes @samp{.mlbst}, @samp{.bst}.
+
+@item mp
+@flindex .mp
+@vindex MPINPUTS
+(MetaPost source, @pxref{mpost invocation,,, web2c, Web2c})
+@code{MPINPUTS};
+suffix @samp{.mp}.
+
+@item mppool
+@flindex .pool
+@vindex MPPOOL
+(MetaPost program strings, @pxref{pooltype invocation,,, web2c, Web2c})
+@code{MPPOOL}, @code{TEXMFINI};
+suffix @samp{.pool}.
+
+@item ocp
+@flindex .ocp
+@vindex OCPINPUTS
+(Omega compiled process files)
+@code{OCPINPUTS}; @*
+suffix @samp{.ocp};
+dynamic creation program: @code{MakeOmegaOCP}.
+
+@item ofm
+@flindex .ofm
+@vindex OFMFONTS
+(Omega font metrics)
+@code{OFMFONTS}, @code{TEXFONTS}; @*
+suffixes @samp{.ofm}, @samp{.tfm};
+dynamic creation program: @code{MakeOmegaOFM}.
+
+@item opentype fonts
+@vindex OPENTYPEFONTS
+(OpenType fonts)
+@code{OPENTYPEFONTS}.
+
+@item opl
+@flindex .opl
+(Omega property lists)
+@code{OPLFONTS}, @code{TEXFONTS};
+suffix @samp{.opl}.
+
+@item otp
+@flindex .otp
+@vindex OTPINPUTS
+(Omega translation process files)
+@code{OTPINPUTS};
+suffix @samp{.otp}.
+
+@item ovf
+@flindex .ovf
+@vindex OVFFONTS
+(Omega virtual fonts)
+@code{OVFFONTS}, @code{TEXFONTS};
+suffix @samp{.ovf}.
+
+@item ovp
+@flindex .ovp
+@vindex OVPFONTS
+(Omega virtual property lists)
+@code{OVPFONTS}, @code{TEXFONTS};
+suffix @samp{.ovp}.
+
+@item pdftex config
+@vindex PDFTEXCONFIG
+(PDF@TeX{}-specific configuration files)
+@code{PDFTEXCONFIG}.
+
+@item pk
+@flindex .pk
+@vindex PKFONTS
+@vindex TEXPKS
+@vindex GLYPHFONTS
+@vindex TEXFONTS
+(packed bitmap fonts, @pxref{Glyph files,,, dvips, Dvips})
+@code{@var{PROGRAM}FONTS} (@var{program} being @samp{XDVI}, etc.),
+@code{PKFONTS}, @code{TEXPKS}, @code{GLYPHFONTS}, @code{TEXFONTS};
+suffix @samp{pk};
+dynamic creation program: @code{mktexpk}.
+
+@item PostScript header
+@flindex .pro
+@vindex TEXPSHEADERS
+@vindex PSHEADERS
+(downloadable PostScript, @pxref{Header files,,, dvips, Dvips})
+@code{TEXPSHEADERS}, @code{PSHEADERS};
+additional suffix @samp{.pro}.
+
+@item ris
+@flindex .ris
+@vindex RISINPUTS
+(RIS bibliography files, primarily for Biber, @url{https://ctan.org/pkg/biber})
+@code{RISINPUTS}
+suffix @samp{.ris}.
+
+@item subfont definition files
+@flindex .sfd
+@vindex SFDFONTS
+(subfont definition files)
+@code{SFDFONTS}
+suffix @samp{.sfd}.
+
+@item tex
+@flindex .tex
+@vindex TEXINPUTS
+(@TeX{} source, @pxref{tex invocation,,, web2c, Web2c})
+@code{TEXINPUTS};
+suffix @samp{.tex};
+additional suffixes: none, because such a list cannot be complete;
+dynamic creation program: @code{mktextex}.
+
+@item TeX system documentation
+@flindex doc files
+@vindex TEXDOCS
+(Documentation files for the @TeX{} system)
+@code{TEXDOCS}.
+
+@item TeX system sources
+@flindex source files
+@vindex TEXSOURCES
+(Source files for the @TeX{} system)
+@code{TEXSOURCES}.
+
+@item texmfscripts
+@vindex TEXMFSCRIPTS
+(Architecture-independent executables distributed in the texmf trees)
+@code{TEXMFSCRIPTS}.
+
+@item texpool
+@flindex .pool
+@vindex TEXPOOL
+(@TeX{} program strings, @pxref{pooltype invocation,,, web2c, Web2c})
+@code{TEXPOOL}, @code{TEXMFINI};
+suffix @samp{.pool}.
+
+@item tfm
+@flindex .tfm
+@vindex TFMFONTS
+@vindex TEXFONTS
+(@TeX{} font metrics, @pxref{Metric files,,, dvips, Dvips})
+@code{TFMFONTS}, @code{TEXFONTS};
+suffix @samp{.tfm};
+dynamic creation program: @code{mktextfm}.
+
+@item Troff fonts
+@vindex TRFONTS
+(Troff fonts, used by DMP; @pxref{DMP invocation,,, web2c, Web2c})
+@code{TRFONTS}.
+
+@item truetype fonts
+@flindex .ttf
+@flindex .ttc
+@vindex TTFONTS
+(TrueType outline fonts) @code{TTFONTS}; suffixes @samp{.ttf} and
+@samp{.TTF}, @samp{.ttc} and @samp{.TTC}, @samp{.dfont}.
+
+@item type1 fonts
+@flindex .pfa
+@flindex .pfb
+@vindex T1FONTS
+@vindex T1INPUTS
+@vindex TEXPSHEADERS
+@vindex DVIPSHEADERS
+(Type 1 PostScript outline fonts, @pxref{Glyph files,,, dvips, Dvips})
+@code{T1FONTS}, @code{T1INPUTS}, @code{TEXPSHEADERS}, @code{DVIPSHEADERS};
+suffixes @samp{.pfa}, @samp{.pfb}.
+
+@item type42 fonts
+@vindex T42FONTS
+(Type 42 PostScript outline fonts) @code{T42FONTS}.
+
+@item vf
+@flindex .vf
+@vindex VFFONTS
+@vindex TEXFONTS
+(virtual fonts, @pxref{Virtual fonts,,, dvips, Dvips})
+@code{VFFONTS}, @code{TEXFONTS};
+suffix @samp{.vf}.
+
+@item web
+@flindex .web
+@vindex WEBINPUTS
+(WEB input files)
+@code{WEBINPUTS};
+suffix @samp{.web};
+additional suffix @samp{.ch}.
+
+@item web2c files
+@vindex WEB2C
+(files specific to the web2c implementation)
+@code{WEB2C}.
+@end table
+
+There are two special cases, because the paths and environment variables
+always depend on the name of the program: the variable name is
+constructed by converting the program name to upper case, and then
+appending @samp{INPUTS}. Assuming the program is called @samp{foo},
+this gives us the following table.
+
+@table @samp
+@item other text files
+@vindex FOOINPUTS
+(text files used by @samp{foo})
+@code{FOOINPUTS}.
+
+@item other binary files
+@vindex FOOINPUTS
+(binary files used by @samp{foo})
+@code{FOOINPUTS}.
+@end table
+
+If an environment variable by these names are set, the corresponding
+@file{texmf.cnf} definition won't be looked at (unless, as usual, the
+environment variable value has an extra @samp{:}). @xref{Default
+expansion}.
+
+For the font variables, the intent is that:
+@itemize @bullet
+@item
+@code{TEXFONTS} is the default for everything.
+
+@item
+@code{GLYPHFONTS} is the default for bitmap (or, more precisely,
+non-metric) files.
+
+@item
+Each font format has a variable of its own.
+
+@item
+@vindex XDVIFONTS
+@vindex DVIPSFONTS
+Each program has its own font override path as well; e.g.,
+@code{DVIPSFONTS} for Dvipsk. Again, this is for bitmaps, not metrics.
+
+@end itemize
+
+
+@node File lookup
+@section File lookup
+
+@cindex file lookup
+@cindex searching for files
+@cindex @TeX{} file lookup
+
+This section describes how Kpathsea searches for most files (bitmap font
+searches are the exception, as described in the next section).
+
+Here is the search strategy for a file @var{name}:
+
+@enumerate
+@item
+If the file format defines default suffixes, and the suffix of
+@var{name} name is not already a known suffix for that format, try the
+name with each default appended, and use alternative names found in
+the fontmaps if necessary. Example: given @samp{foo.bar}, look for
+@samp{foo.bar.tex}.
+
+@item
+Search for @var{name}, and if necessary for alternative names found in
+the fontmaps. Example: given @samp{foo.bar}, we also look for
+@samp{foo.bar}.
+
+@item
+If the file format defines a program to invoke to create missing files,
+run it (@pxref{mktex scripts}).
+@end enumerate
+
+@cindex extensions, filename
+@cindex suffixes, filename
+@vindex try_std_extension_first
+The order in which we search for ``suffixed'' name (item@tie{}1) or
+the ``as-is'' name (item@tie{}2) is controlled by the
+@file{try_std_extension_first} configuration value. The default set
+in @file{texmf.cnf} is true, since common suffixes are already
+recognized: @samp{babel.sty} will only look for @samp{babel.sty}, not
+@samp{babel.sty.tex}, regardless of this setting.
+
+When the suffix is unknown (e.g., @samp{foo.bar}), both names are
+always tried; the difference is the order in which they are tried.
+
+@file{try_std_extension_first} only affects names being looked up
+which *already* have an extension. A name without an extension (e.g.,
+@samp{tex story}) will always have an extension added first.
+
+@flindex tex-file.c
+@findex kpathsea_find_file
+This algorithm is implemented in the function
+@code{kpathsea_find_file} in the source file
+@file{kpathsea/tex-file.c}. You can watch it in action with the
+debugging options (@pxref{Debugging}).
+
+
+@node Glyph lookup
+@section Glyph lookup
+
+@cindex glyph lookup
+@cindex searching for glyphs
+@cindex @TeX{} glyph lookup
+
+This section describes how Kpathsea searches for a bitmap font in GF or
+PK format (or either) given a font name (e.g., @samp{cmr10}) and a
+resolution (e.g., 600).
+
+Here is an outline of the search strategy (details in the sections
+below) for a file @var{name} at resolution @var{dpi}. The search stops
+at the first successful lookup.
+
+@enumerate
+@item
+Look for an existing file @var{name}.@var{dpi}@var{format} in the
+specified format(s).
+
+@item If @var{name} is an alias for a file @var{f} in the fontmap
+file @file{texfonts.map}, look for @var{f}.@var{dpi}.
+
+@item Run an external program (typically named @samp{mktexpk}) to
+generate the font (@pxref{mktex scripts})
+
+@item Look for @var{fallback}.@var{dpi}, where @var{fallback} is some
+last-resort font (typically @samp{cmr10}).
+@end enumerate
+
+@flindex tex-glyph.c
+@findex kpathsea_find_glyph
+This is implemented in @code{kpathsea_find_glyph} in
+@file{kpathsea/tex-glyph.c}.
+
+@menu
+* Basic glyph lookup:: Features common to all glyph lookups.
+* Fontmap:: Aliases for fonts.
+* Fallback font:: Resolutions and fonts of last resort.
+@end menu
+
+
+@node Basic glyph lookup
+@subsection Basic glyph lookup
+
+@cindex basic glyph lookup
+@cindex common features in glyph lookup
+
+When Kpathsea looks for a bitmap font @var{name} at resolution @var{dpi}
+in a format @var{format}, it first checks each directory in the search
+path for a file @samp{@var{name}.@var{dpi}@var{format}}; for example,
+@samp{cmr10.600pk}. Kpathsea looks for a PK file first, then a GF file.
+
+If that fails, Kpathsea looks for
+@samp{dpi@var{dpi}/@var{name}.@var{format}}; for example,
+@samp{dpi600/cmr10.pk}. This is how fonts are typically stored on
+filesystems (such as DOS) that permit only three-character extensions.
+
+@cindex tolerance for glyph lookup
+@cindex glyph lookup bitmap tolerance
+@findex KPSE_BITMAP_TOLERANCE
+If that fails, Kpathsea looks for a font with a close-enough @var{dpi}.
+``Close enough'' is defined by the macro @code{KPSE_BITMAP_TOLERANCE} in
+@file{kpathsea/tex-glyph.h} to be @code{@var{dpi} / 500 + 1}. This is
+slightly more than the 0.2% minimum allowed by the DVI standard
+(@url{@var{CTAN:}/dviware/driv-standard/level-0}).
+
+
+@node Fontmap
+@subsection Fontmap
+
+@cindex fontmap files
+@cindex font alias files
+@cindex aliases for fonts
+
+@flindex texfonts.map
+If a bitmap font or metric file is not found with the original name (see
+the previous section), Kpathsea looks through any @dfn{fontmap} files
+for an @dfn{alias} for the original font name. These files are named
+@file{texfonts.map} and searched for along the @code{TEXFONTMAPS}
+environment/config file variable. All @file{texfonts.map} files that
+are found are read; earlier definitions override later ones.
+
+This feature is intended to help in two respects:
+
+@enumerate
+
+@item
+@cindex fontnames, arbitrary length
+An alias name is limited in length only by available memory, not by your
+filesystem. Therefore, if you want to ask for @samp{Times-Roman}
+instead of @file{ptmr}, you can (you get @samp{ptmr8r}).
+
+@item
+@cindex circle fonts
+@flindex lcircle10
+A few fonts have historically had multiple names: specifically,
+La@TeX{}'s ``circle font'' has variously been known as @file{circle10},
+@file{lcircle10}, and @file{lcirc10}. Aliases can make all the names
+equivalent, so that it no longer matters what the name of the installed
+file is; @TeX{} documents will find their favorite name.
+
+@end enumerate
+
+The format of fontmap files is straightforward:
+
+@itemize @bullet
+@cindex comments, in fontmap files
+@item Comments start with the last @samp{%} on a line and continue to
+the end of the line. (This provides for names that include a %,
+ill-advised as that may be.)
+
+@cindex whitespace, in fontmap files
+@item Blank lines are ignored.
+
+@item Each nonblank line is broken up into a series of @dfn{words}:
+ a sequence of non-whitespace characters.
+
+@findex include @r{fontmap directive}
+@item If the first word is @samp{include}, the second word is used as
+ a filename, and it is searched for and read.
+
+@item Otherwise, the first word on each line is the true filename;
+
+@item the second word is the alias;
+
+@item subsequent words are ignored.
+@end itemize
+
+If an alias has an extension, it matches only those files with that
+extension; otherwise, it matches anything with the same root, regardless
+of extension. For example, an alias @samp{foo.tfm} matches only when
+@file{foo.tfm} is being searched for; but an alias @samp{foo} matches
+@file{foo.vf}, @file{foo.600pk}, etc.
+
+As an example, here is an excerpt from the @file{texfonts.map} in the
+Web2c distribution. It makes the old and new names of the @LaTeX{}
+circle fonts equivalent.
+
+@example
+circle10 lcircle10
+circle10 lcirc10
+lcircle10 circle10
+lcircle10 lcirc10
+lcirc10 circle10
+lcirc10 lcircle10
+@dots{}
+@end example
+
+Fontmaps are implemented in the file @file{kpathsea/fontmap.c}.
+The Fontname distribution has much more information on font naming
+(@pxref{,,,fontname, Filenames for @TeX{} fonts}).
+
+
+@node Fallback font
+@subsection Fallback font
+
+@cindex fallback font
+@cindex fallback resolutions
+@cindex font of last resort
+@cindex resolutions, last-resort
+@cindex last-resort font
+
+@vindex DVIPSSIZES
+@vindex XDVISIZES
+@vindex DVILJSIZES
+@vindex TEXSIZES
+@vindex default_texsizes
+If a bitmap font cannot be found or created at the requested size,
+Kpathsea looks for the font at a set of @dfn{fallback resolutions}. You
+specify these resolutions as a colon-separated list (like search paths).
+Kpathsea looks first for a program-specific environment variable (e.g.,
+@code{DVIPSSIZES} for Dvipsk), then the environment variable
+@code{TEXSIZES}, then a default specified at compilation time (the Make
+variable @code{default_texsizes}). You can set this list to be empty if
+you prefer to find fonts at their stated size or not at all.
+
+@flindex cmr10@r{, as fallback font}
+@findex kpathsea_init_prog
+Finally, if the font cannot be found even at the fallback resolutions,
+Kpathsea looks for a fallback font, typically @file{cmr10}. Programs
+must enable this feature by calling @code{kpathsea_init_prog}
+(@pxref{Calling sequence}); the default is no fallback font.
+
+
+@node Suppressing warnings
+@section Suppressing warnings
+
+@cindex warnings, suppressing
+@cindex suppressing warnings
+
+@vindex TEX_HUSH
+Kpathsea provides a way to suppress selected usually-harmless warnings;
+this is useful at large sites where most users are not administrators,
+and thus the warnings are merely a source of confusion, not a help. To
+do this, you set the environment variable or configuration file value
+@code{TEX_HUSH} to a colon-separated list of values. Here are the
+possibilities:
+
+@vtable @samp
+@item all
+Suppress everything possible.
+
+@item checksum
+@cindex mismatched checksum warnings
+Suppress mismatched font checksum warnings.
+
+@item lostchar
+@cindex missing character warnings
+Suppress warnings when a character is missing from a font that a DVI or
+VF file tries to typeset.
+
+@item none
+Don't suppress any warnings.
+
+@item readable
+@cindex unreadable file warnings
+Suppress warnings about attempts to access a file whose permissions
+render it unreadable.
+
+@item special
+@cindex unknown special warnings
+@findex \special@r{, suppressing warnings about}
+Suppresses warnings about an unimplemented or unparsable
+@samp{\special} command.
+@end vtable
+
+@noindent @file{tex-hush.c} defines the function that checks the
+variable value. Each driver implements its own checks where
+appropriate.
+
+
+@node mktex scripts
+@section @file{mktex} scripts
+
+@cindex @file{mktex} scripts
+@cindex scripts for file creation
+
+@cindex font set, infinite
+@cindex dynamic creation of files
+@cindex Sauter fonts, and dynamic source creation
+@cindex EC fonts, and dynamic source creation
+If Kpathsea cannot otherwise find a file, for some file types it is
+configured by default to invoke an external program to create it
+dynamically (@pxref{mktex configuration}). These are collectively
+known as @dfn{@code{mktex} scripts}, since most of them are named
+@code{mktex...}.
+
+For example, this is useful for fonts (bitmaps, TFM's, and
+arbitrarily-sizable Metafont sources such as the Sauter and EC fonts),
+since any given document can use fonts never before referenced.
+Building all fonts in advance is therefore impractical, if not
+impossible.
+
+It is also useful for the @TeX{} @samp{.fmt} (and Metafont
+@samp{.base} and Metapost @samp{.mem} files, @pxref{Memory
+dumps,,,Web2c,web2c}), where pre-generating every format consumes a
+lot of both time and space.
+
+The script is passed the name of the file to create and possibly other
+arguments, as explained below. It must echo the full pathname of the
+file it created (and nothing else) to standard output; it can write
+diagnostics to standard error.
+
+@menu
+* config: mktex configuration.
+* names: mktex script names.
+* args: mktex script arguments.
+@end menu
+
+
+@node mktex configuration
+@subsection @file{mktex} configuration
+
+@cindex @file{mktex} script configuration
+@cindex configuration of @file{mktex} scripts
+@cindex enabling @file{mktex} scripts
+@cindex disabling @file{mktex} scripts
+
+The list of file types and program names that can run an external
+program to create missing files is listed in the next section. In the
+absence of @code{configure} options specifying otherwise, everything
+but @file{mktextex} will be enabled by default. The @code{configure}
+options to change the defaults are:
+
+@cindex @code{configure} options for @file{mktex} scripts
+@opindex --without-mktexfmt-default
+@opindex --without-mktexmf-default
+@opindex --without-mktexocp-default
+@opindex --without-mktexofm-default
+@opindex --without-mktexpk-default
+@opindex --without-mktextfm-default
+@opindex --with-mktextex-default
+@example
+--without-mktexfmt-default
+--without-mktexmf-default
+--without-mktexocp-default
+--without-mktexofm-default
+--without-mktexpk-default
+--without-mktextfm-default
+--with-mktextex-default
+@end example
+
+The @code{configure} setting is overridden if the environment variable
+or configuration file value named for the script is set; e.g.,
+@file{MKTEXPK} (@pxref{mktex script arguments}).
+
+@flindex fmtutils.cnf
+@code{mktexfmt} reads a file @file{fmtutil.cnf}, typically located in
+@file{texmf/web2c/} to glean its configuration information. The rest
+of the files and features in this section are primarily intended for
+the font generation scripts.
+
+@flindex mktex.cnf
+@flindex mktex.opt
+@cindex site overrides for @code{mktex@dots{}}
+As distributed, all the scripts source a file
+@file{texmf/web2c/mktex.cnf} if it exists, so you can override various
+defaults.
+See @file{mktex.opt}, for instance, which defines the default mode,
+resolution, some special directory names, etc. If you prefer not to
+change the distributed scripts, you can simply create @file{mktex.cnf}
+with the appropriate definitions (you do not need to create it if you
+have nothing to put in it). @file{mktex.cnf} has no special syntax;
+it's an arbitrary Bourne shell script. The distribution contains a
+sample @file{mktex.cnf} for you to copy and modify as you please (it
+is not installed anywhere).
+
+@flindex mktex.opt
+@vindex MT_FEATURES
+In addition, you can configure a number of features with the
+@code{MT_FEATURES} variable, which you can define:
+
+@itemize @bullet
+@item
+in @file{mktex.opt}, as just mentioned;
+
+@item
+by editing the file @file{mktex.opt}, either before @samp{make
+install} (in the source hierarchy) or after (in the installed
+hierarchy);
+
+@item
+or in the environment.
+@end itemize
+
+If none of the options below are enabled, @code{mktexpk},
+@code{mktextfm}, and @code{mktexmf} follow the following procedure to
+decide where fonts should be installed. Find the tree where the font's
+sources are, and test the permissions of the @samp{fonts} directory of
+that tree to determine whether it is writable. If it is, put the files
+in the tree in appropriate locations. If it isn't writable, see whether
+the tree is a system tree (named in @code{SYSTEXMF}). If so, the
+@code{VARTEXFONTS} tree is used. In all other cases the working
+directory is used.
+
+The @samp{appendonlydir} option is enabled by default.
+
+@vtable @samp
+@item appendonlydir
+@cindex directories, making append-only
+@flindex mktexdir
+Tell @code{mktexdir} to create directories append-only, i.e., set
+their sticky bit (@pxref{Mode Structure,,, coreutils, GNU Core
+Utilities}). This feature is silently ignored on non-Unix platforms
+(e.g. Windows/NT and MS-DOS) which don't support similar functionality.
+This feature is enabled by default.
+
+@item dosnames
+@cindex 8.3 filenames, using
+@cindex DOS compatible names
+@flindex dpi@var{nnn} directories
+Use 8.3 names; e.g., @file{dpi600/cmr10.pk} instead of
+@file{cmr10.600pk}. Note that this feature only affects filenames that
+would otherwise clash with other TeX-related filenames; @file{mktex}
+scripts do nothing about filenames which exceed the 8+3 MS-DOS limits
+but remain unique when truncated (by the OS) to these limits, and nether
+do the scripts care about possible clashes with files which aren't
+related with TeX. For example, @file{cmr10.600pk} would clash with
+@file{cmr10.600gf} and is therefore changed when @samp{dosnames} is in
+effect, but @file{mf.pool} and @file{mp.base} don't clash with any
+TeX-related files and are therefore unchanged.
+
+This feature is turned on by default on MS-DOS. If you do not wish
+@samp{dosnames} to be set on an MS-DOS platform, you need to set the
+@code{MT_FEATURES} environment variable to a value that doesn't include
+@samp{dosnames}. You can also change the default setting by editing
+@file{mktex.opt}, but only if you use the @file{mktex} shell scripts;
+the emulation programs don't consult @file{mktex.opt}.
+
+@item fontmaps
+@cindex fontmaps
+@cindex fontname
+Instead of deriving the location of a font in the destination tree from
+the location of the sources, the aliases and directory names from the
+Fontname distribution are used. (@pxref{Top,, Introduction, fontname,
+Fontname}).
+
+@item nomfdrivers
+@cindex metafont driver files
+Let mktexpk and mktextfm create metafont driver files in a temporary
+directory. These will be used for just one metafont run and not
+installed permanently.
+
+@item nomode
+@cindex mode directory, omitting
+Omit the directory level for the mode name; this is fine as long as
+you generate fonts for only one mode.
+
+@item stripsupplier
+@cindex supplier directory, omitting
+Omit the font supplier name directory level.
+
+@item striptypeface
+@cindex typeface directory, omitting
+Omit the font typeface name directory level.
+
+@item strip
+@cindex supplier directory, omitting
+@cindex typeface directory, omitting
+Omit the font supplier and typeface name directory levels. This feature
+is deprecated in favour of @samp{stripsupplier} and @samp{striptypeface}.
+
+@item varfonts
+@flindex /var/tmp/texfonts
+@vindex VARTEXFONTS
+@cindex Linux File System Standard
+When this option is enabled, fonts that would otherwise be written in
+system texmf tree go to the @code{VARTEXFONTS} tree instead. The
+default value in @file{kpathsea/Makefile.in} is
+@file{/var/tmp/texfonts}. The @cite{Linux File System Standard}
+recommends @file{/var/tex/fonts}.
+
+@vindex USE_VARTEXFONTS
+The @samp{varfonts} setting in @code{MT_FEATURES} is overridden by the
+@code{USE_VARTEXFONTS} environment variable: if set to @samp{1}, the
+feature is enabled, and if set to @samp{0}, the feature is disabled.
+
+@item texmfvar
+@vindex TEXMFVAR
+Force generated files that would go into a system tree (as defined by
+@code{SYSTEXMF}) into @code{TEXMFVAR}. Starting with te@TeX{}-3.0, the
+variable @code{TEXMFVAR} is always set. The @samp{varfonts} feature takes
+precedence if also set.
+
+@vindex USE_TEXMFVAR
+The @samp{texmfvar} setting in @code{MT_FEATURES} is overridden by the
+@code{USE_TEXMFVAR} environment variable: if set to @samp{1}, the
+feature is enabled, and if set to @samp{0}, the feature is disabled.
+@end vtable
+
+
+@node mktex script names
+@subsection @file{mktex} script names
+
+@cindex @file{mktex} script names
+@cindex names for @file{mktex} scripts
+
+The following table shows the default name of the script for each
+of the file types which support runtime generation.
+
+@table @file
+@item mktexfmt
+@pindex mktexfmt
+@pindex fmtutil
+(@samp{.fmt}, @samp{.base}, @samp{.mem}) @TeX{}/Metafont/MetaPost
+formats. This script is also named @command{fmtutil}, and reads
+@file{fmtutil.cnf} for configuration information.
+
+@item mktexmf
+@pindex mktexmf
+(@samp{.mf}) Metafont input files.
+
+@item mkocp
+@pindex mkocp
+(@samp{.ocp}) Omega compiled process files.
+
+@item mkofm
+@pindex mkofm
+(@samp{.ofm}) Omega font metric files.
+
+@item mktexpk
+@pindex mktexpk
+(@samp{pk}) Glyph fonts.
+
+@item mktextex
+@pindex mktextex
+(@samp{.tex}) @TeX{} input files (disabled by default).
+
+@item mktextfm
+@pindex mktextfm
+(@samp{.tfm}) TFM files.
+@end table
+
+@vindex DVIPSMAKEPK
+@vindex XDVIMAKEPK
+@vindex DVILJMAKEPK
+@noindent These names can be overridden by an environment variable specific
+to the program---for example, @code{DVIPSMAKEPK} for Dvipsk.
+
+@comment next two paragraphs are repeated in dvips.texi
+@flindex missfont.log
+@cindex failed @code{mktex@dots{}} script invocation
+If a @code{mktex@dots{}} script fails, the invocation is appended to a
+file @file{missfont.log} (by default) in the current directory. You can
+then execute the log file to create the missing files after fixing the
+problem.
+
+@vindex TEXMFOUTPUT
+@vindex MISSFONT_LOG
+If the current directory is not writable and the environment variable or
+configuration file value @code{TEXMFOUTPUT} is set, its value is
+used. Otherwise, nothing is written. The name @samp{missfont.log} is
+overridden by the @code{MISSFONT_LOG} environment variable or
+configuration file value.
+
+
+@node mktex script arguments
+@subsection @file{mktex} script arguments
+
+@cindex arguments to @file{mktex}
+
+The first argument to a @file{mktex} script is always the name
+of the file to be created.
+
+In the default @file{mktexpk} implementation, additional arguments may
+also be passed:
+
+@table @samp
+@item --dpi @var{num}
+Sets the resolution of the generated font to @var{num}.
+@item --mfmode @var{name}
+Sets the Metafont mode to @var{name}.
+@item --bdpi @var{num}
+Sets the ``base dpi'' for the font. This must match the mode being
+used.
+@item --mag @var{string}
+A ``magstep'' string suitable for the Metafont @code{mag} variable.
+This must match the combination of @var{bdpi} and @var{dpi} being used.
+@item --destdir @var{string}
+A directory name. If the directory is absolute, it is used as-is.
+Otherwise, it is appended to the root destination directory set in the
+script.
+@end table
+
+
+@node Programming
+@chapter Programming
+
+This chapter is for programmers who wish to use Kpathsea.
+@xref{Introduction}, for the conditions under which you may do so (in
+short, it is released under LGPLv2.1 or later).
+
+@menu
+* Overview: Programming overview. Introduction.
+* Calling sequence:: Specifics of what to call.
+* Program-specific files:: How to handle these.
+* Config: Programming with config files. Getting info from texmf.cnf.
+@end menu
+
+
+@node Programming overview
+@section Programming overview
+
+@cindex programming overview
+@cindex overview of programming with Kpathsea
+
+Aside from this manual, your best source of information is the source
+to the programs that use Kpathsea (@pxref{Introduction}). First,
+Kpsewhich is a small utility program whose sole purpose is to exercise
+the main path-searching functionality. Of the drivers, Dviljk is
+probably the simplest full application program. Xdvik adds VF support
+and the complication of X resources. Dvipsk adds the complication of
+its own config files. Web2c is source code I also maintain, so it
+uses Kpathsea rather straightforwardly, but is of course complicated
+by the Web to C translation.
+
+@cindex re-entrant API
+@cindex API, re-entrant
+When looking at these program sources, you should know that previous
+versions of the library had a different programming interface; the
+current interface supports re-entrancy. Historically, the library
+function names were prefixed with @code{kpse_} instead of
+@code{kpathsea_}, and they did not need an instance variable as first
+argument. This change was made in 2009. The old functions will never
+disappear, and can reliably continue to be used when they suffice, as
+they do for the programs above. The main application using the
+re-entrant API is the MetaPost library used by MetaPost and Lua@TeX{}.
+
+@flindex pathsearch.h
+@flindex tex-file.h
+@flindex tex-glyph.h
+@flindex kpathsea.h
+Beyond these examples, the @file{.h} files in the Kpathsea source
+describe the interfaces and functionality (and of course the @file{.c}
+files define the actual routines, which are the ultimate documentation).
+@file{pathsearch.h} declares the basic searching routine.
+@file{tex-file.h} and @file{tex-glyph.h} define the interfaces for
+looking up particular kinds of files. In view of the way the headers
+depend on each other, it is recommended to use @code{#include
+<kpathsea/kpathsea.h>}, which includes every Kpathsea header.
+
+@flindex config.h
+@flindex c-auto.h
+If you want to include only specific headers, you should still consider
+including @file{kpathsea/config.h} before including any other Kpathsea
+header, as it provides symbols used in the other headers. Note that
+@file{kpathsea/config.h} includes @file{kpathsea/c-auto.h}, which is
+generated by Autoconf.
+
+@cindex file types, registering new
+The library provides no way for an external program to register new file
+types: @file{tex-file.[ch]} must be modified to do this. For example,
+Kpathsea has support for looking up Dvips config files, even though no
+program other than Dvips will likely ever want to do so. I felt this
+was acceptable, since along with new file types should also come new
+defaults in @file{texmf.cnf} (and its descendant @file{paths.h}), since
+it's simplest for users if they can modify one configuration file for
+all kinds of paths.
+
+Kpathsea does not parse any formats itself; it barely opens any files.
+Its primary purpose is to return filenames. The GNU font utilities does
+contain libraries to read TFM, GF, and PK files, as do the programs
+above, of course.
+
+
+@node Calling sequence
+@section Calling sequence
+
+@cindex programming with Kpathsea
+@cindex calling sequence
+
+The typical way to use Kpathsea in your program goes something like this:
+
+@enumerate
+
+@item
+@findex kpathsea_new
+Call @code{kpathsea_new} to create a new library instance. This variable
+must be passed as the first argument to all the following library functions.
+The rest of this manual will be using @code{kpse} as a placeholder for
+the name of this variable.
+
+@item
+@findex kpathsea_set_program_name
+@vindex argv[0]
+Call @code{kpathsea_set_program_name} with @code{argv[0]} as the second
+argument; the third argument is a string or @code{NULL}. The third
+argument is used by Kpathsea as the program name for the
+@code{.@var{program}} feature of config files (@pxref{Config files}).
+If the third argument is @code{NULL}, the value of the second argument
+is used. This function must be called before any other use of the
+Kpathsea library.
+
+@vindex kpse->invocation_name
+@vindex kpse->invocation_short_name
+@vindex kpse->program_name
+@cindex error message macros
+@code{kpathsea_set_program_name} always sets the variables
+@code{kpse->invocation_name} and @code{kpse->invocation_short_name}.
+These variables are used in the error message macros defined in
+@file{kpathsea/lib.h}. It sets the variable
+@code{kpse->program_name} to the program name it uses.
+
+@vindex KPATHSEA_DEBUG
+It also initializes debugging options based on the environment
+variable @code{KPATHSEA_DEBUG} (if that is set).
+
+@cindex SELFAUTOLOC
+@cindex SELFAUTODIR
+@cindex SELFAUTOPARENT
+@cindex symlinks, resolving
+@cindex expanding symlinks
+Finally, it sets the environment variables @code{SELFAUTOLOC}, @code{SELFAUTODIR}
+and @code{SELFAUTOPARENT} to the location, parent and grandparent
+directory of the executable, removing @file{.} and @file{..} path
+elements and resolving symbolic links. These are used in the default
+configuration file to allow people to invoke TeX from anywhere. You
+can use @samp{kpsewhich --expand-var=\$SELFAUTOLOC}, etc., to see the
+values.
+
+@item
+@vindex kpse->debug @r{variable}
+@cindex debugging options, in Kpathsea-using program
+Set debugging options. @xref{Debugging}. If your program doesn't have a
+debugging option already, you can define one and set
+@code{kpse->debug} to the number that the user supplies (as in Dviljk
+and Web2c), or you can just omit this altogether (people can always set
+@code{KPATHSEA_DEBUG}). If you do have runtime debugging already, you
+need to merge Kpathsea's options with yours (as in Dvipsk and Xdvik).
+
+@item
+@vindex client_path @r{in @code{kpse->format_info}}
+@vindex kpse->format_info
+@flindex resident.c
+@cindex config files, for Kpathsea-using programs
+If your program has its own configuration files that can define search
+paths, you should assign those paths to the @code{client_path} member in
+the appropriate element of the @code{kpse->format_info} array. (This
+array is indexed by file type; see @file{tex-file.h}.) See
+@file{resident.c} in Dvipsk for an example.
+
+@item
+@findex kpathsea_init_prog
+@flindex proginit.h
+Call @code{kpathsea_init_prog} (see @file{proginit.c}). It's useful for the
+DVI drivers, at least, but for other programs it may be simpler to
+extract the parts of it that actually apply. This does not initialize
+any paths, it just looks for (and sets) certain environment variables
+and other random information. (A search path is always initialized at
+the first call to find a file of that type; this eliminates much useless
+work, e.g., initializing the Bib@TeX{} search paths in a DVI driver.)
+
+@item
+@findex kpathsea_find_file
+The routine to actually find a file of type @var{format} is
+@file{kpathsea_find_file}. You can call
+@code{kpathsea_find_file} after doing only the first and second of the
+initialization steps above---Kpathsea automatically reads the
+@file{texmf.cnf} generic config files, looks for environment variables,
+and does expansions at the first lookup.
+
+@item
+To find PK and/or GF bitmap fonts, the routine
+is @code{kpathsea_find_glyph}, defined in
+@file{tex-glyph.h}. This returns a structure in addition to the
+resultant filename, because fonts can be found in so many ways. See the
+documentation in the source.
+
+@item
+@findex kpathsea_open_file
+To actually open a file, not just return a filename, call
+@code{kpathsea_open_file}. This function takes the name to look up and a
+Kpathsea file format as arguments, and returns the usual @code{FILE *}.
+It always assumes the file must exist, and thus will search the disk if
+necessary (unless the search path specified @samp{!!}, etc.). In other
+words, if you are looking up a VF or some other file that need not
+exist, don't use this.
+
+@item
+@findex kpathsea_out_name_ok
+@TeX{} can write output files, via the @code{\openout} primitive; this opens
+a security hole vulnerable to Trojan horse attack: an unwitting user could
+run a @TeX{} program that overwrites, say, @file{~/.rhosts}. Analogous
+security holes exist for many other programs. To alleviate this, there is a
+configuration variable @code{openout_any}, which selects one of three levels
+of security. When it is set to @samp{a} (for ``any''), no restrictions are
+imposed. When it is set to @samp{r} (for ``restricted''), filenames
+beginning with @samp{.} are disallowed (except @file{.tex} because @LaTeX{}
+needs it). When it is set to @samp{p} (for ``paranoid'') additional
+restrictions are imposed: an absolute filename must refer to a file in (a
+subdirectory) of @code{TEXMFOUTPUT}, and any attempt to go up a directory
+level is forbidden (that is, paths may not contain a @samp{..} component).
+The paranoid setting is the default. (For backwards compatibility, @samp{y}
+and @samp{1} are synonyms of @samp{a}, while @samp{n} and @samp{0} are
+synonyms for @samp{r}.) The function @code{kpathsea_out_name_ok}, with a
+filename as second argument, returns @code{true} if that filename is
+acceptable to be opend for output or @code{false} otherwise.
+
+@item
+@findex kpathsea_in_name_ok
+Similarly, the function @code{kpathsea_in_name_ok}, with a filename as
+second argument, returns @code{true} if that filename is acceptable to be
+opend for input or @code{false} otherwise, depending on the value of the
+configuration variable @code{openin_any} (with @samp{a} as default).
+
+@item
+@findex kpathsea_finish
+To close the kpathsea library instance you are using, call
+@code{kpathsea_finish}. This function closes any open log files and
+frees the memory used by the instance.
+
+@end enumerate
+
+@cindex hash table routines
+@cindex memory allocation routines
+@cindex string routines
+@cindex reading arbitrary-length lines
+@cindex input lines, reading
+@cindex lines, reading arbitrary-length
+Kpathsea also provides many utility routines. Some are generic: hash
+tables, memory allocation, string concatenation and copying, string
+lists, reading input lines of arbitrary length, etc. Others are
+filename-related: default path, tilde, and variable expansion,
+@code{stat} calls, etc. (Perhaps someday I'll move the former to a
+separate library.)
+
+@flindex c-*.h
+@pindex autoconf@r{, recommended}
+The @file{c-*.h} header files can also help your program adapt to many
+different systems. You will almost certainly want to use Autoconf and
+probably Automake for configuring and building your software if you use
+Kpathsea; I strongly recommend using Autoconf and Automake regardless.
+They are available from @url{https://gnu.org/software}.
+
+
+@node Program-specific files
+@section Program-specific files
+
+Many programs will need to find some configuration files. Kpathsea
+contains some support to make it easy to place them in their own
+directories. The Standard @TeX{} directory structure (@pxref{Top,,
+Introduction, tds, A Directory Structure for @TeX{} files}), specifies
+that such files should go into a subdirectory named after the program,
+like @samp{texmf/ttf2pk}.
+
+Two formats, @samp{kpse_program_text_format} and
+@samp{kpse_program_binary_format}, use @code{.:$TEXMF/@var{program}//}
+as their compiled-in search path. To override this default, you can
+use the variable @code{@var{PROGRAM}INPUTS} in the environment and/or
+@samp{texmf.cnf}. That is to say, the name of the variable is
+constructed by converting the name of the program to upper case, and
+appending @code{INPUTS}.
+
+The only difference between these two formats is whether
+@code{kpathsea_open_file} will open the files it finds in text or binary
+mode.
+
+
+@node Programming with config files
+@section Programming with config files
+
+@cindex programming with config files
+@cindex config files, programming with
+
+You can (and probably should) use the same @code{texmf.cnf}
+configuration file that Kpathsea uses for your program. This helps
+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 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 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
+If for some reason you want to retrieve a value @emph{only} from a
+config file, not automatically looking for a corresponding environment
+variable, call @code{kpathsea_cnf_get} (declared in @file{kpathsea/cnf.h})
+with the string @var{var}.
+
+No initialization calls are needed.
+
+
+@node Reporting bugs
+@chapter Reporting bugs
+
+@cindex reporting bugs
+@cindex bugs, reporting
+
+@flindex tex-k@@tug.org @r{(bug address)}
+@cindex bug address
+If you have problems or suggestions, please report them to
+@email{tex-k@@tug.org} using the bug checklist below.
+
+Please report bugs in the documentation; not only factual errors or
+inconsistent behavior, but unclear or incomplete explanations, typos,
+wrong fonts, @dots{}
+
+@menu
+* Bug checklist:: What to include in a good bug report.
+* Mailing lists:: Joining the bugs or announcements mailing lists.
+* Debugging:: Analyzing runtime problems.
+* Logging:: Recording searches.
+* Common problems:: When things go wrong.
+@end menu
+
+
+@node Bug checklist
+@section Bug checklist
+
+@cindex checklist for bug reports
+@cindex bug checklist
+
+Before reporting a bug, please check below to be sure it isn't already
+known (@pxref{Common problems}).
+
+Bug reports should be sent via electronic mail to
+@email{tex-k@@tug.org}.
+
+The general principle is that a good bug report includes all the
+information necessary for reproduction. Therefore, to enable
+investigation, your report should include the following:
+
+@itemize @bullet
+@item
+@cindex version numbers, determining
+The version number(s) of the program(s) involved, and of Kpathsea
+itself. You can get the former by giving a sole option @samp{--version}
+to the program, and the latter by running @samp{kpsewhich --version}.
+The @file{NEWS} and @file{ChangeLog} files also contain the version
+number.
+
+@item
+@pindex uname
+The hardware, operating system (including version), compiler, and
+@code{make} program you are using (the output of @code{uname -a} is a
+start on the first two, though incomplete).
+
+@item
+@flindex config.log
+Any options you gave to @code{configure}. This is recorded in the
+@file{config.status} files.
+
+@cindex configuration bugs
+@flindex config.status
+If you are reporting a bug in @samp{configure} itself, it's probably
+system-dependent, and it will be unlikely the maintainers can do
+anything useful if you merely report that thus-and-such is broken.
+Therefore, you need to do some additional work: for some bugs, you can
+look in the file @file{config.log} where the test that failed should
+appear, along with the compiler invocation and source program in
+question. You can then compile it yourself by hand, and discover why
+the test failed. Other @samp{configure} bugs do not involve the
+compiler; in that case, the only recourse is to inspect the
+@code{configure} shell script itself, or the Autoconf macros that
+generated @code{configure}.
+
+@item
+The log of all debugging output, if the bug is in path searching. You
+can get this by setting the environment variable @code{KPATHSEA_DEBUG}
+to @samp{-1} before running the program. Please look at the log
+yourself to make sure the behavior is really a bug before reporting it;
+perhaps ``old'' environment variable settings are causing files not to
+be found, for example.
+
+@item
+The contents of any input files necessary to reproduce the bug. For
+bugs in DVI-reading programs, for example, this generally means a DVI
+file (and any EPS or other files it uses)---@TeX{} source files are
+helpful, but the DVI file is required, because that's the actual
+program input.
+
+@item
+@cindex context diff
+@cindex sending patches
+@flindex ChangeLog @r{entry}
+If you are sending a patch (do so if you can!), please do so in the form
+of a context diff (@samp{diff -c}) against the original distribution
+source. Any other form of diff is either not as complete or harder for
+me to understand. Please also include a @file{ChangeLog} entry.
+
+@item
+@cindex stack trace
+@cindex debugger
+@cindex crashes, reporting
+@cindex core dumps, reporting
+@cindex null pointers, dereferencing
+@pindex gdb@r{, recommended}
+If the bug involved is an actual crash (i.e., core dump), it is easy
+and useful to include a stack trace from a debugger (I recommend the
+GNU debugger GDB (@url{https://gnu.org/software/gdb}). If the
+cause is apparent (a @code{NULL} value being dereferenced, for
+example), please send the details along. If the program involved is
+@TeX{} or Metafont, and the crash is happening at apparently-sound
+code, however, the bug may well be in the compiler, rather than in the
+program or the library (@pxref{TeX or Metafont failing,, @TeX{} or
+Metafont failing}).
+
+@item
+Any additional information that will be helpful in reproducing,
+diagnosing, or fixing the bug.
+@end itemize
+
+
+@node Mailing lists
+@section Mailing lists
+
+@cindex mailing lists
+@cindex bug mailing list
+@cindex announcement mailing list
+
+@flindex tex-k@@tug.org
+Web2c and Kpathsea in general are discussed on the mailing list
+@email{tex-k@@tug.org}. You can subscribe and peruse the archives on
+the web @url{https://lists.tug.org/tex-k}.
+
+You do not need to join to submit a report, nor will it affect whether
+you get a response. Be aware that large data files are sometimes
+included in bug reports. If this is a problem for you, do not join
+the list.
+
+If you are looking for general @TeX{} help, such as how to install a
+full @TeX{} system or how to use @LaTeX{}, please see
+@url{https://tug.org/begin.html}.
+
+
+@node Debugging
+@section Debugging
+
+@cindex debugging
+@cindex runtime debugging
+@cindex options for debugging
+
+@vindex kpse->debug
+@flindex debug.h
+Kpathsea provides a number of runtime debugging options, detailed below
+by their names and corresponding numeric values. When the files you
+expect aren't being found, the thing to do is enable these options and
+examine the output.
+
+You can set these with some runtime argument (e.g., @samp{-d}) to the
+program; in that case, you should use the numeric values described in
+the program's documentation (which, for Dvipsk and Xdvik, are different
+than those below). It's best to give the @samp{-d} (or whatever) option
+first, for maximal output. Dvipsk and Xdvik have additional
+program-specific debugging options as well.
+
+@vindex KPATHSEA_DEBUG
+@vindex kpse->debug
+You can also set the environment variable @code{KPATHSEA_DEBUG}; in this
+case, you should use the numbers below. If you run the program under a
+debugger and set the instance variable @code{kpse->debug}, also use the numbers
+below.
+
+@kindex -1 @r{debugging value}
+In any case, by far the simplest value to use is @samp{-1}, which will
+turn on all debugging output. This is usually better than guessing
+which particular values will yield the output you need.
+
+@cindex debugging output
+@cindex standard error and debugging output
+Debugging output always goes to standard error, so you can redirect it
+easily. For example, in Bourne-compatible shells:
+@example
+dvips -d -1 @dots{} 2>/tmp/debug
+@end example
+
+@cindex Kpsewhich, and debugging
+It is sometimes helpful to run the standalone Kpsewhich utility
+(@pxref{Invoking kpsewhich}), instead of the original program.
+
+@cindex numeric debugging values
+In any case, you cannot use the names below; you must always use
+somebody's numbers. (Sorry.) To set more than one option, just sum
+the corresponding numbers.
+
+@vtable @code
+@item KPSE_DEBUG_STAT @r{(1)}
+Report @samp{stat}(2) calls. This is useful for verifying that your
+directory structure is not forcing Kpathsea to do many additional file
+tests (@pxref{Slow path searching}, and @pxref{Subdirectory
+expansion}). If you are using an up-to-date @file{ls-R} database
+(@pxref{Filename database}), this should produce no output unless a
+nonexistent file that must exist is searched for.
+
+@item KPSE_DEBUG_HASH @r{(2)}
+Report lookups in all hash tables: @file{ls-R} and @file{aliases}
+(@pxref{Filename database}); font aliases (@pxref{Fontmap}); and config
+file values (@pxref{Config files}). Useful when expected values are not
+being found, e.g.., file searches are looking at the disk instead of
+using @file{ls-R}.
+
+@item KPSE_DEBUG_FOPEN @r{(4)}
+@findex fopen@r{, redefined}
+Report file openings and closings. Especially useful when your system's
+file table is full, for seeing which files have been opened but never
+closed. In case you want to set breakpoints in a debugger: this works by
+redefining @samp{fopen} (@samp{fclose}) to be @samp{kpse_fopen_trace}
+(@samp{kpse_fclose_trace}).
+
+@item KPSE_DEBUG_PATHS @r{(8)}
+@tindex kpse_format_info_type
+Report general path information for each file type Kpathsea is asked to
+search. This is useful when you are trying to track down how a
+particular path got defined---from @file{texmf.cnf}, @file{config.ps},
+an environment variable, the compile-time default, etc. This is the
+contents of the @code{kpse_format_info_type} structure defined in
+@file{tex-file.h}.
+
+@item KPSE_DEBUG_EXPAND @r{(16)}
+Report the directory list corresponding to each path element Kpathsea
+searches. This is only relevant when Kpathsea searches the disk, since
+@file{ls-R} searches don't look through directory lists in this way.
+
+@item KPSE_DEBUG_SEARCH @r{(32)}
+Report on each file search: the name of the file searched for, the path
+searched in, whether or not the file must exist (when drivers search for
+@file{cmr10.vf}, it need not exist), and whether or not we are
+collecting all occurrences of the file in the path (as with, e.g.,
+@file{texmf.cnf} and @file{texfonts.map}), or just the first (as with
+most lookups). This can help you correlate what Kpathsea is doing with
+what is in your input file.
+
+@item KPSE_DEBUG_VARS @r{(64)}
+Report the value of each variable Kpathsea looks up. This is useful for
+verifying that variables do indeed obtain their correct values.
+
+@item GSFTOPK_DEBUG @r{(128)}
+Activates debugging printout specific to @code{gsftopk} program.
+
+@item MAKETEX_DEBUG @r{(512)}
+If you use the optional @code{mktex} programs instead of the
+traditional shell scripts, this will report the name of the site file
+(@file{mktex.cnf} by default) which is read, directories created by
+@code{mktexdir}, the full path of the @file{ls-R} database built by
+@code{mktexlsr}, font map searches, @code{MT_FEATURES} in effect,
+parameters from @code{mktexnam}, filenames added by
+@code{mktexupd}, and some subsidiary commands run by the programs.
+
+@item MAKETEX_FINE_DEBUG @r{(1024)}
+When the optional @code{mktex} programs are used, this will print
+additional debugging info from functions internal to these programs.
+@end vtable
+
+@cindex @samp{kdebug:}
+@vindex hash_summary_only @r{variable for debugging}
+@cindex hash table buckets, printing
+Debugging output from Kpathsea is always written to standard error, and
+begins with the string @samp{kdebug:}. (Except for hash table buckets,
+which just start with the number, but you can only get that output
+running under a debugger. See comments at the @code{hash_summary_only}
+variable in @file{kpathsea/db.c}.)
+
+
+@node Logging
+@section Logging
+
+@cindex log file
+
+@cindex logging successful searches
+@cindex recording successful searches
+@cindex usage patterns, finding
+@cindex disk usage, reducing
+Kpathsea can record the time and filename found for each successful
+search. This may be useful in finding good candidates for deletion when
+your filesystem is full, or in discovering usage patterns
+at your site.
+
+@vindex TEXMFLOG
+To do this, define the environment or config file variable
+@code{TEXMFLOG}. The value is the name of the file to append the
+information to. The file is created if it doesn't exist, and appended
+to if it does.
+
+@cindex epoch, seconds since
+@findex time @r{system call}
+Each successful search turns into one line in the log file: two words
+separated by a space. The first word is the time of the search, as the
+integer number of seconds since ``the epoch'', i.e., UTC midnight 1
+January 1970 (more precisely, the result of the @code{time} system
+call). The second word is the filename.
+
+For example, after @code{setenv TEXMFLOG /tmp/log}, running Dvips on
+@file{story.dvi} appends the following lines:
+
+@example
+774455887 /usr/local/share/texmf/dvips/config.ps
+774455887 /usr/local/share/texmf/dvips/psfonts.map
+774455888 /usr/local/share/texmf/dvips/texc.pro
+774455888 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmbx10.600pk
+774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmsl10.600pk
+774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk
+774455889 /usr/local/share/texmf/dvips/texc.pro
+@end example
+
+@cindex privacy, semblance of
+@noindent Only filenames that are absolute are recorded, to preserve
+some semblance of privacy.
+
+In addition to this Kpathsea-specific logging, @command{pdftex}
+provides an option @option{-recorder} to write the names of all files
+accessed during a run to the file @file{@var{basefile}.fls}.
+
+Finally, most systems provide a general tool to output each system
+call, thus including opening and closing files. It might be named
+@command{strace}, @command{truss}, @command{struss}, or something
+else.
+
+
+@node Common problems
+@section Common problems
+
+@cindex common problems
+@cindex problems, common
+@cindex FAQ, Kpathsea
+
+Here are some common problems with configuration, compilation, linking,
+execution, @dots{}
+
+@menu
+* Unable to find files:: If your program can't find fonts (or whatever).
+* Slow path searching:: If it takes forever to find anything.
+* Unable to generate fonts:: If mktexpk fails.
+* TeX or Metafont failing:: Likely compiler bugs.
+@end menu
+
+@node Unable to find files
+@subsection Unable to find files
+
+@cindex unable to find files
+@cindex files, unable to find
+
+If a program complains it cannot find fonts (or other input files), any
+of several things might be wrong. In any case, you may find the
+debugging options helpful. @xref{Debugging}.
+
+@itemize @bullet
+@item
+Perhaps you simply haven't installed all the necessary files; the basic
+fonts and input files are distributed separately from the programs.
+@xref{unixtex.ftp}.
+
+@item
+@flindex /etc/profile
+@cindex environment variables, old
+You have (perhaps unknowingly) told Kpathsea to use search paths that
+don't reflect where the files actually are. One common cause is having
+environment variables set from a previous installation, thus overriding
+what you carefully set in @file{texmf.cnf} (@pxref{Supported file
+formats}). System @file{/etc/profile} or other files such may be the
+culprit.
+
+@item
+@cindex symbolic links not found
+@cindex leaf directories wrongly guessed
+Your files reside in a directory that is only pointed to via a symbolic
+link, in a leaf directory and is not listed in @file{ls-R}.
+
+Unfortunately, Kpathsea's subdirectory searching has an irremediable
+deficiency: If a directory @var{d} being searched for subdirectories
+contains plain files and symbolic links to other directories, but no
+true subdirectories, @var{d} will be considered a leaf directory, i.e.,
+the symbolic links will not be followed. @xref{Subdirectory expansion}.
+
+You can work around this problem by creating an empty dummy subdirectory
+in @var{d}. Then @var{d} will no longer be a leaf, and the symlinks will
+be followed.
+
+The directory immediately followed by the @samp{//} in the path
+specification, however, is always searched for subdirectories, even if
+it is a leaf. Presumably you would not have asked for the directory to
+be searched for subdirectories if you didn't want it to be.
+
+@item
+If the fonts (or whatever) don't already exist, @code{mktexpk} (or
+@code{mktexmf} or @code{mktextfm}) will try to create them. If
+these rather complicated shell scripts fail, you'll eventually get an
+error message saying something like @samp{Can't find font
+@var{fontname}}. The best solution is to fix (or at least report) the
+bug in @code{mktexpk}; the workaround is to generate the necessary
+fonts by hand with Metafont, or to grab them from a CTAN site
+(@pxref{unixtex.ftp}).
+
+@item
+There is a bug in the library. @xref{Reporting bugs}.
+@end itemize
+
+
+@node Slow path searching
+@subsection Slow path searching
+
+@cindex excessive startup time
+@cindex slow startup time
+@cindex startup time, excessive
+
+If your program takes an excessively long time to find fonts or other
+input files, but does eventually succeed, here are some possible culprits:
+
+@itemize @bullet
+@item
+Most likely, you just have a lot of directories to search, and that
+takes a noticeable time. The solution is to create and maintain a
+separate @file{ls-R} file that lists all the files in your main @TeX{}
+hierarchy. @xref{Filename database}. Kpathsea always uses @file{ls-R}
+if it's present; there's no need to recompile or reconfigure any of the
+programs.
+
+@item
+Your recursively-searched directories (e.g.,
+@file{/usr/local/share/texmf/fonts//}), contain a mixture of files and
+directories. This prevents Kpathsea from using a useful optimization
+(@pxref{Subdirectory expansion}).
+
+It is best to have only directories (and perhaps a @file{README}) in the
+upper levels of the directory structure, and it's very important to have
+@emph{only} files, and no subdirectories, in the leaf directories where
+the dozens of TFM, PK, or whatever files reside.
+@end itemize
+
+In any case, you may find the debugging options helpful in determining
+precisely when the disk or network is being pounded. @xref{Debugging}.
+
+
+@node Unable to generate fonts
+@subsection Unable to generate fonts
+
+@cindex unable to generate fonts
+@cindex font generation failures
+
+Metafont outputs fonts in bitmap format, tuned for a particular
+device at a particular resolution, in order to allow for the
+highest-possible quality of output. Some DVI-to-whatever programs,
+such as Dvips, try to generate these on the fly when they are needed,
+but this generation may fail in several cases.
+
+@cindex @code{mktexpk} can't guess mode
+If @code{mktexpk} runs, but fails with this error:
+@example
+mktexpk: Can't guess mode for @var{nnn} dpi devices.
+mktexpk: Use a config file to specify the mode, or update me.
+@end example
+you need to ensure the resolution and mode match; just
+specifying the resolution, as in @code{-D 360}, is not enough.
+
+You can specify the mode name with the @code{-mode} option on the
+Dvips command line, or in a Dvips configuration file (@pxref{Config
+files,,, dvips, Dvips}), such as @file{config.ps} in your document
+directory, @file{~/.dvipsrc} in your home directory, or in a system
+directory (again named @file{config.ps}). (Other drivers use other
+files, naturally.)
+
+For example, if you need 360@dmn{dpi} fonts, you could include this in
+a configuration file:
+@example
+D 360
+M lqmed
+@end example
+
+@cindex Metafont using the wrong device
+@cindex device, wrong
+If Metafont runs, but generates fonts at the wrong resolution or for
+the wrong device, most likely @code{mktexpk}'s built-in guess for the
+mode is wrong, and you should override it as above.
+
+See @url{https://ctan.org/pkg/modes} for a list of resolutions and mode
+names for most devices (additional submissions are welcome).
+
+@flindex .2602gf
+@flindex 2602gf
+@cindex Metafont making too-large fonts
+@cindex proof mode
+@cindex online Metafont display, spurious
+If Metafont runs but generates fonts at a resolution of 2602@dmn{dpi}
+(and prints out the name of each character as well as just a character
+number, and maybe tries to display the characters), then your Metafont
+base file probably hasn't been made properly. (It's using the default
+@code{proof} mode, instead of an actual device mode.) To make a proper
+@file{plain.base}, assuming the local mode definitions are contained in
+a file @file{modes.mf}, run the following command (assuming Unix):
+
+@example
+inimf "plain; input modes; dump"
+@end example
+
+@noindent
+@flindex plain.base
+Then copy the @file{plain.base} file from the current directory to where
+the base files are stored on your system
+(@file{/usr/local/share/texmf/web2c} by default), and make a link
+(either hard or soft) from @file{plain.base} to @file{mf.base} in that
+directory.
+@xref{inimf invocation,,, web2c, Web2c}.
+
+@cindex Metafont installation
+If @code{mf} is a command not found at all by @code{mktexpk}, then you
+need to install Metafont (@pxref{unixtex.ftp}).
+
+
+@node TeX or Metafont failing
+@subsection @TeX{} or Metafont failing
+
+@cindex @TeX{} failures
+@cindex Metafont failures
+@cindex compiler bugs
+If @TeX{} or Metafont get a segmentation fault or otherwise fail while
+running a normal input file, the problem is usually a compiler bug
+(unlikely as that may sound). Even if the trip and trap tests are
+passed, problems may lurk. Optimization occasionally causes trouble in
+programs other than @TeX{} and Metafont themselves, too.
+
+@cindex optimization caveat
+For a workaround, if you enabled any optimization flags, it's best to
+omit optimization entirely. In any case, the way to find the facts is
+to run the program under the debugger and see where it's failing.
+
+@cindex GNU C compiler bugs
+@cindex system C compiler bugs
+Also, if you have trouble with a system C compiler, I advise trying the
+GNU C compiler. And vice versa, unfortunately; but in that case I also
+recommend reporting a bug to the GCC mailing list; see @ref{Bugs,,, gcc,
+Using and Porting GNU CC}.
+
+@cindex compiler bugs, finding
+To report compiler bugs effectively requires perseverance and
+perspicacity: you must find the miscompiled line, and that usually
+involves delving backwards in time from the point of error, checking
+through @TeX{}'s (or whatever program's) data structures. Good luck.
+
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@bye