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.texi2455
1 files changed, 2455 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..c33aeb7aefe
--- /dev/null
+++ b/Build/source/texk/kpathsea/doc/kpathsea.texi
@@ -0,0 +1,2455 @@
+\input texinfo
+@setfilename kpathsea.info
+@settitle Kpathsea: A library for path searching
+
+@set version 3.5.7
+@set month-year July 2008
+
+@copying
+This file documents the Kpathsea library for path searching.
+
+Copyright @copyright{} 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003,
+2004, 2005, 2007, 2008 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 Free Software Foundation.
+@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 (@email{kb@@mail.tug.org})
+@author Olaf Weber (@email{infovore@@xs4all.nl})
+
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+
+@contents
+
+
+@ifnottex
+@node Top
+@top Kpathsea library
+
+This manual documents how to install and use the Kpathsea library for
+filename lookup. It corresponds to version @value{version},
+released in @value{month-year}.
+
+@menu
+* Introduction:: Overview.
+* Installation:: Compilation, installation, and bug reporting.
+
+* Path searching:: How filename lookups work.
+* TeX support:: Special support for TeX-related file lookups.
+
+* Programming:: How to use Kpathsea features in your program.
+
+* 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 we maintain, uses this library:
+
+@itemize @bullet
+@item Dviljk (see the @samp{dvilj} man page)
+@item Dvipsk (@pxref{Top, , Introduction, dvips, Dvips: A DVI driver})
+@item GNU font utilities (@pxref{Top, , Introduction, fontu, GNU font
+utilities})
+@item Web2c (@pxref{Top, , Introduction, 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.
+
+@cindex interface, not frozen
+@cindex comments, making
+@cindex suggestions, making
+We are still actively maintaining the library (and probably always will
+be, despite our hopes). If you have comments or suggestions, please send
+them to us (@pxref{Reporting bugs}).
+
+@cindex conditions for use
+@cindex license for using the library
+@cindex GNU General Public License
+We distribute the library under the GNU Library General Public License
+(LGPL). 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, although we hope you will. See the files
+@file{GPL} and @file{LGPL} for the text of the GNU 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, great!). 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. Anyway, here is the address:
+
+@flindex tug@@tug.org
+@display
+@TeX{} Users Group
+P.O. Box 2311
+Portland OR 97208-2311
+USA
+phone: +1 503 223-9994
+fax: +1 503 223-3960
+email: @email{tug@@tug.org}
+@end display
+
+@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 @cite{Software---Practice and
+Experience} 19(7), July 1989.)
+
+@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. 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, though I think Paul Vojta has completely rewritten Xdvi's
+support by now. That is, I tried to go with the flow in each program,
+rather than changing the program's calling sequences to conform to
+common routines.
+
+Then, as bugs inevitably appeared, I found I was fixing the same thing
+three times (Web2c and fontutils were always sharing code, since I
+maintained 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 that 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.
+
+
+@include install.texi
+@include hier.texi
+@include unixtex.texi
+@include bugs.texi
+
+
+@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.
+
+@menu
+* Searching overview:: Basic scheme for searching.
+* Path sources:: Where search paths can be defined.
+* Path expansion:: Special constructs in search paths.
+* 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. This
+avoids possibly-expensive processing of path specifications that are
+never needed on a particular run. (Unless the search explicitly
+requested all matches.)
+
+@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.
+
+@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 can come from many sources. In the order in which
+Kpathsea uses them:
+
+@enumerate
+@item
+@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{%} and continue to the end of the line.
+
+@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 must 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.
+
+@item If @samp{.@var{progname}} is present, 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}. This allows different flavors of @TeX{} to
+have different search paths, for example.
+
+@item
+@cindex right-hand side of variable assignments
+@var{value} may contain any characters except @samp{%} and @samp{@@}.
+(These restrictions are only necessary because of the processing done on
+@file{texmf.cnf} at build time, so you can stick those characters in
+after installation if you have to.) 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). A @samp{;} in
+@var{value} is translated to @samp{:} if running under Unix; this is
+useful to write a single @file{texmf.cnf} which can be used under both
+Unix and NT.
+
+@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.
+Although this format has obvious similarities 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. But there seemed little
+advantage to doing 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.
+
+@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 DOS 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 in stead of the comma. The last
+example could have been written @samp{x@{A:B@}@{1:2@}y}.
+
+
+@flindex expand.c
+Brace expansion is implemented in the source file
+@file{kpathsea/expand.c}. It is a modification of the Bash sources, and
+is thus covered by the GNU General Public License, rather than the
+Library General Public License that covers the rest of Kpathsea.
+
+
+@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 can find a way to @emph{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 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
+each 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}. This can be helpful to adapt
+to ``8.3'' filename conventions in source files.
+
+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}
+@vindex TEXMFDBS
+
+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); most sites have
+only one hierarchy. Kpathsea looks for @file{ls-R} files along the
+@code{TEXMFDBS} path, so that should presumably match the list of
+hierarchies.
+
+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 La@TeX{}
+package), @file{ls-R} will be automatically updated.
+
+@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 La@TeX{} 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
+Because the database may be out-of-date for a particular run, if a file
+is not found in the database, by default Kpathsea goes ahead and
+searches the disk. If a particular path element begins with @samp{!!},
+however, @emph{only} the database will be searched for that element,
+never the disk. If the database does not exist, nothing will be
+searched. Because this can surprise users (``I see the font
+@file{foo.tfm} when I do an @code{ls}; why can't Dvips find it?''), it
+is not in any of the default search paths.
+
+
+@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.
+* Standard options:: --help and --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).
+
+@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.
+@example
+gf: gf
+pk: pk
+bitmap font
+afm: .afm
+base: .base
+bib: .bib
+bst: .bst
+cnf: .cnf
+ls-R: ls-R
+fmt: .fmt
+map: .map
+mem: .mem
+mf: .mf
+mfpool: .pool
+mft: .mft
+mp: .mp
+mppool: .pool
+MetaPost support
+ocp: .ocp
+ofm: .ofm .tfm
+opl: .opl
+otp: .otp
+ovf: .ovf
+ovp: .ovp
+graphic/figure: .eps .epsi
+tex: .tex
+TeX system documentation
+texpool: .pool
+TeX system sources
+PostScript header/font: .pro
+Troff fonts
+tfm: .tfm
+type1 fonts: .pfa .pfb
+vf: .vf
+dvips config
+ist: .ist
+truetype fonts: .ttf .ttc
+type42 fonts
+web2c files
+other text files
+other binary files
+misc fonts
+web: .web
+cweb: .w .web
+enc: .enc
+cmap: .cmap
+sfd: .sfd
+opentype fonts
+pdftex config
+lig files: .lig
+texmfscripts
+@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}.
+The only values that make sense for @var{filetype} are @samp{pk},
+@samp{mf}, @samp{tex}, and @samp{tfm}. By default, all are off in
+Kpsewhich. @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. 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
+@file{texmf-dist/scripts/pkg2/} to match 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 additional features not strictly related to path
+lookup:
+
+@itemize @bullet
+@item
+@opindex --debug=@var{num}
+@samp{--debug=@var{num}} sets the debugging options to @var{num}.
+@xref{Debugging}.
+
+@item
+@opindex --var-value=@var{variable}
+@samp{--var-value=@var{variable}} outputs the value of @var{variable},
+expanding @samp{$} (@pxref{Variable expansion} and @samp{~} (@pxref{Tilde
+expansion}) constructs, but not performing other expansions.
+
+@item
+@opindex --expand-braces=@var{string}
+@samp{--expand-braces=@var{string}} outputs the variable and brace
+expansion of @var{string}. @xref{Path expansion}.
+
+@item
+@opindex --expand-var=@var{string}
+@samp{--expand-var=@var{string}} outputs the variable and tilde
+expansion of @var{string}. For example, the @samp{mktex@dots{}}
+scripts run @samp{kpsewhich --expand-var='$TEXMF'} to find the root of
+the @TeX{} system hierarchy. @xref{Path expansion}.
+
+@item
+@opindex --expand-path=@var{string}
+@samp{--expand-path=@var{string}} outputs 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}, next.
+
+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} in the previous section.
+
+@item
+@opindex --show-path=@var{name}
+@samp{--show-path=@var{name}} shows 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.
+
+@end itemize
+
+
+@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.
+
+@item
+@opindex --version
+@samp{--version} prints the Kpathsea version number and exits.
+@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 (like all libraries) 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 supposedly 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 filenames, not file contents---if a GF
+file is 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.
+@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.
+
+@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 bst
+@flindex .bst
+@vindex BSTINPUTS
+(Bib@TeX{} style file, @pxref{Basic BibTeX style files,, Basic Bib@TeX{}
+style files, web2c, Web2c})
+@code{BSTINPUTS};
+suffix @samp{.bst}.
+
+@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 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 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 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 tree)
+@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},
+@samp{.ttc}.
+
+@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 kpse_find_file
+This algorithm is implemented in the routine @code{kpse_find_file} in
+@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 kpse_find_glyph_format
+This is implemented in @code{kpse_find_glyph_format} 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 @samp{%} and continue to the end of the line.
+@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 circle fonts equivalent and includes
+automatically generated maps for most PostScript fonts available from
+various font suppliers.
+
+@example
+circle10 lcircle10
+circle10 lcirc10
+lcircle10 circle10
+lcircle10 lcirc10
+lcirc10 circle10
+lcirc10 lcircle10
+@dots{}
+include adobe.map
+include apple.map
+include bitstrea.map
+@dots{}
+@end example
+
+Fontmaps are implemented in the file @file{kpathsea/fontmap.c}.
+The Fontname distribution has much more information on font naming
+(@pxref{Introduction,,, 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}
+@vindex kpse_fallback_font
+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 assigning to the global variable
+@code{kpse_fallback_font} or calling @code{kpse_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 Programming
+@chapter Programming
+
+This chapter is for programmers who wish to use Kpathsea.
+@xref{Introduction}, for the conditions under which you may do so.
+
+@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 I've modified to use Kpathsea (@pxref{Introduction}). Of
+those, Dviljk is probably the simplest, and hence a good place to start.
+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. Finally, Kpsewhich is a small
+utility program whose sole purpose is to exercise the main
+path-searching functionality.
+
+@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 kpse_set_program_name
+@vindex argv[0]
+Call @code{kpse_set_program_name} with @code{argv[0]} as the first
+argument; the second argument is a string or @code{NULL}. The second
+argument is used by Kpathsea as the program name for the
+@code{.@var{program}} feature of config files (@pxref{Config files}).
+If the second argument is @code{NULL}, the value of the first argument
+is used. This function must be called before any other use of the
+Kpathsea library.
+
+@vindex program_invocation_name
+@vindex program_invocation_short_name
+@vindex kpse_program_name
+@cindex error message macros
+@code{kpse_set_program_name} always sets the global variables
+@code{program_invocation_name} and @code{program_invocation_short_name}.
+These variables are used in the error message macros defined in
+@file{kpathsea/lib.h}. It sets the global 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 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
+@findex kpse_set_progname
+@vindex argv[0]
+The @code{kpse_set_progname} is deprecated. A call to
+@code{kpse_set_progname} with @code{argv[0]} is equivalent to a call of
+@code{kpse_set_program_name} with first argument @code{argv[0]} and
+second argument @code{NULL}. The function is deprecated because it
+cannot ensure that the @code{.@var{program}} feature of config files
+will always work (@pxref{Config files}).
+
+@item
+@vindex kpathsea_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{kpathsea_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 kpse_init_prog
+@flindex proginit.h
+Call @code{kpse_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 kpse_find_*
+@findex kpse_find_file
+The routine to actually find a file of type @var{format} is
+@code{kpse_find_@var{format}}, defined in @file{tex-file.h}. These are
+macros that expand to a call to @file{kpse_find_file}. You can call,
+say, @code{kpse_find_tfm} after doing only the first 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 routines are @code{kpse_find_pk},
+@code{kpse_find_gf} and @code{kpse_find_glyph}, defined in
+@file{tex-glyph.h}. These return 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 kpse_open_file
+To actually open a file, not just return a filename, call
+@code{kpse_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.
+
+@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 for
+configuring your software if you use Kpathsea; I strongly recommend
+using Autoconf regardless. It is available from
+@url{ftp://prep.ai.mit.edu/pub/gnu/}.
+
+
+@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 special formats, @samp{kpse_program_text_format} and
+@samp{kpse_program_binary_format} exist, which 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{kpse_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 kpse_var_value
+@flindex variable.h
+@vindex shell_escape@r{, example for code}
+To retrieve a value @var{var} from config files, the best way is to call
+@code{kpse_var_value} on the string @code{@var{var}}. This will look
+first for an environment variable @var{var}, then a config file value.
+The result will be the value found or @samp{NULL}. This function is
+declared in @file{kpathsea/variable.h}. For an example, see the
+@code{shell_escape} code in @file{web2c/lib/texmfmp.c}.
+
+The routine to do variable expansion in the context of a search path (as
+opposed to simply retrieving a value) is @code{kpse_var_expand}, also
+declared in @file{kpathsea/variable.h}. It's generally only necessary
+to set the search path structure components as explained in the previous
+section, rather than using this yourself.
+
+@findex kpse_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{kpse_cnf_get} (declared in @file{kpathsea/cnf.h})
+with the string @var{var}.
+
+No initialization calls are needed.
+
+
+@node Index
+@unnumbered Index
+
+@printindex cp
+
+@bye