summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/info/kpathsea.info
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/info/kpathsea.info')
-rw-r--r--Master/texmf-dist/doc/info/kpathsea.info4763
1 files changed, 4763 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/info/kpathsea.info b/Master/texmf-dist/doc/info/kpathsea.info
new file mode 100644
index 00000000000..54e179d0f3d
--- /dev/null
+++ b/Master/texmf-dist/doc/info/kpathsea.info
@@ -0,0 +1,4763 @@
+This is ../../../../texk/kpathsea/doc/kpathsea.info, produced by
+makeinfo version 4.13 from ../../../../texk/kpathsea/doc/kpathsea.texi.
+
+This file documents the Kpathsea library for path searching.
+
+ Copyright (C) 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004,
+2005, 2007, 2008, 2009, 2010, 2011, 2012 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.
+
+ 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.
+
+INFO-DIR-SECTION TeX
+START-INFO-DIR-ENTRY
+* 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-INFO-DIR-ENTRY
+
+
+File: kpathsea.info, Node: Top, Next: Introduction, Up: (dir)
+
+Kpathsea library
+****************
+
+This manual documents how to install and use the Kpathsea library for
+filename lookup. It corresponds to version 6.1.0, released in
+May 2012.
+
+* 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.
+
+
+File: kpathsea.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top
+
+1 Introduction
+**************
+
+This manual corresponds to version 6.1.0 of the Kpathsea library,
+released in May 2012.
+
+ 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.
+
+ The following software, all of which we maintain, uses this library:
+
+ * Dviljk (see the `dvilj' man page)
+
+ * Dvipsk (*note Introduction: (dvips)Top.)
+
+ * GNU font utilities (*note Introduction: (fontu)Top.)
+
+ * Web2c (*note Introduction: (web2c)Top.)
+
+ * Xdvik (see the `xdvi' man page)
+
+Other software that we do not maintain also uses it.
+
+ 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 (*note Reporting bugs::).
+
+ 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 accompanying files for the text of the GNU licenses.
+
+ 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
+`TUGboat', sponsors an annual meeting and publishes the proceedings,
+and arranges courses on TeX for all levels of users throughout the
+world. See `http://tug.org' for information.
+
+* Menu:
+
+* History::
+
+
+File: kpathsea.info, Node: History, Up: Introduction
+
+1.1 History
+===========
+
+(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 `Software--Practice and Experience'
+19(7), July 1989.)
+
+ [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 `pxp' and `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
+`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 `cm', `pandora', ... in a path.
+
+ 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.)
+
+ 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.)
+
+ 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.
+
+ 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 ... 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...)
+
+ [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.
+
+
+File: kpathsea.info, Node: Installation, Next: Path searching, Prev: Introduction, Up: Top
+
+2 Installation
+**************
+
+(A copy of this chapter is in the distribution file `kpathsea/INSTALL'.)
+
+The procedure for Kpathsea (and Web2c, etc.) configuration and
+installation follows. If you encounter trouble, see *note Common
+problems::, a copy of which is in the file `kpathsea/BUGS'.
+
+* Menu:
+
+* Simple installation:: If you just want to do it.
+* Custom installation:: If you want to change things around.
+* Security:: Who can write what files, etc.
+* TeX directory structure:: Managing the horde of TeX input files.
+* unixtex.ftp:: Getting software via FTP, on CD-ROM, or on tape.
+* Reporting bugs:: Where and how to report bugs.
+
+
+File: kpathsea.info, Node: Simple installation, Next: Custom installation, Up: Installation
+
+2.1 Simple installation
+=======================
+
+Installing TeX and friends for the first time can be a daunting
+experience. Thus, you may prefer to skip this whole thing and just get
+precompiled executables: see *note unixtex.ftp::.
+
+ This section explains what to do if you wish to take the defaults for
+everything, and generally to install in the simplest possible way. Most
+steps here refer to corresponding subsection in the next section which
+explains how to override defaults and generally gives more details.
+
+ By default everything will be installed under `/usr/local' and the
+following discussion assumes this. However, if you already have TeX
+installed, its location is used to derive the directory under which
+everything is to be installed.
+
+ 1. Be sure you have enough disk space: approximately 8 megabytes for
+ the compressed archives, 15MB for sources, 50MB for compilation,
+ 40MB for the (initial) installed system (including library files).
+ *Note Disk space::.
+
+ 2. Retrieve these distribution archives:
+ `ftp://ftp.tug.org/tex/texk.tar.gz'
+ These are the sources, which you will be compiling.
+
+ `ftp://ftp.tug.org/tex/texklib.tar.gz'
+ This is a basic set of input files. You should unpack it in
+ the directory `/usr/local/share'; doing so will create a
+ `texmf' subdirectory there.
+
+ These archives are mirrored on the CTAN hosts, in the
+ `systems/web2c' directory.
+
+ *Note Kpathsea application distributions::.
+
+ 3. When using the default search paths, there is no need to edit any
+ distribution files. *Note Changing search paths::.
+
+ 4. At the top level of the distribution, run `sh configure'. (If you
+ have the GNU Bash shell installed, run `bash configure'.) *Note
+ Running configure::.
+
+ 5. `make'. *Note Running make::. If you are using a BSD 4.4 system
+ such as FreeBSD or NetBSD, you may have to use GNU make (often
+ installed in `/usr/local/bin'), not the BSD make.
+
+ 6. `make install'. *Note Installing files::.
+
+ 7. `make distclean'. *Note Cleaning up::.
+
+ 8. Set up a cron job to rebuild the filename database that makes
+ searching faster. This line will rebuild it every midnight:
+ 0 0 * * * cd /usr/local/share/texmf && /BINDIR/mktexlsr
+ *Note Filename database generation::, and *note Filename
+ database::.
+
+ 9. If you're installing Dvips, you also need to set up configuration
+ files for your printers and make any additional PostScript fonts
+ available. *Note Installation: (dvips)Installation. If you have
+ any color printers, see *note Color device configuration:
+ (dvips)Color device configuration.
+
+ 10. The first time you run a DVI driver, a bunch of PK fonts will be
+ built by Metafont via `mktexpk' (and added to the filename
+ database). This will take some time. Don't be alarmed; they will
+ created only this first time (unless something is wrong with your
+ path definitions).
+
+ By default, `mktexpk' will create these fonts in a hierarchy under
+ `/var/tmp/texfonts'; it simply assumes that `/var/tmp' exists and
+ is globally writable. If you need a different arrangement, see
+ *note mktex configuration::.
+
+ *Note mktex scripts::.
+
+ 11. For some simple tests, try `tex story \\bye' and `latex sample2e'.
+ Then run `xdvi story' or `dvips sample2e' on the resulting DVI
+ files to preview/print the documents. *Note Installation
+ testing::.
+
+
+File: kpathsea.info, Node: Custom installation, Next: Security, Prev: Simple installation, Up: Installation
+
+2.2 Custom installation
+=======================
+
+Most sites need to modify the default installation procedure in some
+way, perhaps merely changing the prefix from `/usr/local', perhaps
+adding extra compiler or loader options to work around `configure'
+bugs. This section explains how to override default choices. For
+additional distribution-specific information:
+ * `dviljk/INSTALL'.
+
+ * *Note Installation: (dvips)Installation.
+
+ * *Note Installation: (web2c)Installation.
+
+ * `xdvik/INSTALL'.
+
+ These instructions are for Unix systems. Other operating-system
+specific distributions have their own instructions. The code base
+itself supports Amiga, DOS, OS/2, and VMS.
+
+ Following are the same steps as in the previous section (which
+describes the simplest installation), but with much more detail.
+
+* Menu:
+
+* Disk space::
+* Kpathsea application distributions::
+* Changing search paths::
+* Running configure::
+* Running make::
+* Installing files::
+* Cleaning up::
+* Filename database generation::
+* mktex scripts::
+* Installation testing::
+
+
+File: kpathsea.info, Node: Disk space, Next: Kpathsea application distributions, Up: Custom installation
+
+2.2.1 Disk space
+----------------
+
+Here is a table showing the disk space needed for each distribution
+(described in the next section). The `(totals)' line reflects the
+`texk' source distribution and `texklib'; the individual distributions
+don't enter into it. Sizes are in megabytes. All numbers are
+approximate.
+
+Distribution .tar.gz Unpacked Compiled Installed
+dviljk .9 3.8
+dvipsk .9 3.2
+xdvik .7 2.5
+web2c 1.3 5.0
+web 1.9 6.5 - -
+texk 7.5 32.1 95.3 33.5
+texklib 6.3 15.0 - 15.0
+(totals) 14.6 47.1 95.3 48.5
+
+
+File: kpathsea.info, Node: Kpathsea application distributions, Next: Changing search paths, Prev: Disk space, Up: Custom installation
+
+2.2.2 Kpathsea application distributions
+----------------------------------------
+
+The archive `ftp://ftp.tug.org/tex/texk.tar.gz' contains all of the
+Kpathsea applications I maintain, and the library itself. For example,
+since NeXT does not generally support X11, you'd probably want to skip
+`xdvik' (or simply remove it after unpacking `texk.tar.gz'. If you are
+not interested in all of them, you can also retrieve them separately:
+
+`dviljk.tar.gz'
+ DVI to PCL, for LaserJet printers.
+
+`dvipsk.tar.gz'
+ DVI to PostScript, for previewers, printers, or PDF generation.
+
+`web2c.tar.gz'
+ The software needed to compile TeX and friends.
+
+`web.tar.gz'
+ The original WEB source files, also used in compilation.
+
+`xdvik.tar.gz'
+ DVI previewing under the X window system.
+
+
+ If you want to use the Babel LaTeX package for support of non-English
+typesetting, you may need to retrieve additional files. See the file
+`install.txt' in the Babel distribution.
+
+
+File: kpathsea.info, Node: Changing search paths, Next: Running configure, Prev: Kpathsea application distributions, Up: Custom installation
+
+2.2.3 Changing search paths
+---------------------------
+
+If the search paths for your installation differ from the standard TeX
+directory structure (*note Introduction: (tds)Top.), edit the file
+`kpathsea/texmf.in' as desired, before running `configure'. For
+example, if you have all your fonts or macros in one big directory.
+
+ You may also wish to edit the file `mktex.cnf', either before or
+after installation, to control various aspects of `mktexpk' and
+friends. *Note mktex configuration::.
+
+ You do not need to edit `texmf.in' to change the default top-level
+or other installation _directories_ (only the paths). You can and
+should do that when you run `configure' (next step).
+
+ You also do not need to edit `texmf.in' if you are willing to rely
+on `texmf.cnf' at runtime to define the paths, and let the compile-time
+default paths be incorrect. Usually there is no harm in doing this.
+
+ The section below explains default generation in more detail.
+
+* Menu:
+
+* Default path features::
+* Default path generation::
+
+
+File: kpathsea.info, Node: Default path features, Next: Default path generation, Up: Changing search paths
+
+2.2.3.1 Default path features
+.............................
+
+The purpose of having all the different files described in the section
+above is to avoid having the same information in more than one place. If
+you change the installation directories or top-level prefix at
+`configure'-time, those changes will propagate through the whole
+sequence. And if you change the default paths in `texmf.in', those
+changes are propagated to the compile-time defaults.
+
+ The Make definitions are all repeated in several Makefile's; but
+changing the top-level `Makefile' should suffice, as it passes down all
+the variable definitions, thus overriding the submakes. (The
+definitions are repeated so you can run Make in the subdirectories, if
+you should have occasion to.)
+
+ By default, the bitmap font paths end with `/$MAKETEX_MODE', thus
+including the device name (usually a Metafont mode name such as
+`ljfour'). This distinguishes two different devices with the same
+resolution--a write/white from a write/black 300dpi printer, for
+example.
+
+ However, since most sites don't have this complication, Kpathsea
+(specifically, the `kpse_init_prog' function in `kpathsea/proginit.c')
+has a special case: if the mode has not been explicitly set by the user
+(or in a configuration file), it sets `MAKETEX_MODE' to `/'. This
+makes the default PK path, for example, expand into `.../pk//', so
+fonts will be found even if there is no subdirectory for the mode (if
+you arranged things that way because your site has only one printer,
+for example) or if the program is mode-independent (e.g., `pktype').
+
+ To make the paths independent of the mode, simply edit `texmf.in'
+before installation, or the installed `texmf.cnf', and remove the
+`$MAKETEX_MODE'.
+
+ *Note mktex script arguments::, for how this interacts with
+`mktexpk'.
+
+ *Note TeX directory structure: TeX directory structure, for a
+description of the default arrangement of the input files that comprise
+the TeX system.
+
+
+File: kpathsea.info, Node: Default path generation, Prev: Default path features, Up: Changing search paths
+
+2.2.3.2 Default path generation
+...............................
+
+This section describes how the default paths are constructed.
+
+ You may wish to ignore the whole mess and simply edit `texmf.cnf'
+after it is installed, perhaps even copying it into place beforehand so
+you can complete the installation, if it seems necessary.
+
+ To summarize the chain of events that go into defining the default
+paths:
+
+ 1. `configure' creates a `Makefile' from each `Makefile.in'.
+
+ 2. When Make runs in the `kpathsea' directory, it creates a file
+ `texmf.sed' that substitutes the Make value of `$(var)' for a
+ string `@var@'. The variables in question are the one that define
+ the installation directories.
+
+ 3. `texmf.sed' (together with a little extra magic--see
+ `kpathsea/Makefile') is applied to `texmf.in' to generate
+ `texmf.cnf'. This is the file that will eventually be installed
+ and used.
+
+ 4. The definitions in `texmf.cnf' are recast as C `#define''s in
+ `paths.h'. These values will be the compile-time defaults; they
+ are not used at runtime unless no `texmf.cnf' file can be found.
+
+ (That's a lie: the compile-time defaults are what any extra :'s in
+ `texmf.cnf' expand into; but the paths as distributed have no extra
+ :'s, and there's no particular reason for them to.)
+
+
+File: kpathsea.info, Node: Running configure, Next: Running make, Prev: Changing search paths, Up: Custom installation
+
+2.2.4 Running `configure'
+-------------------------
+
+Run `sh configure OPTIONS' (in the top-level directory, the one
+containing `kpathsea/'), possibly using a shell other than `sh' (*note
+configure shells::).
+
+ `configure' adapts the source distribution to the present system via
+`#define''s in `*/c-auto.h', which are created from the corresponding
+`c-auto.in'. It also creates a `Makefile' from the corresponding
+`Makefile.in', doing `@VAR@' and `ac_include' substitutions).
+
+ `configure' is the best place to control the configuration,
+compilation, and installed location of the software, either via
+command-line options, or by setting environment variables before
+invoking it. For example, you can disable `mktexpk' by default with
+the option `--disable-mktexpk'. *Note configure options::.
+
+* Menu:
+
+* configure shells::
+* configure options::
+* configure environment::
+* configure scenarios::
+* Shared library::
+
+
+File: kpathsea.info, Node: configure shells, Next: configure options, Up: Running configure
+
+2.2.4.1 `configure' shells
+..........................
+
+Considerable effort has gone into trying to ensure that the `configure'
+scripts can be run by most Bourne shell variants. If `sh' runs into
+trouble, your best bet is to use Bash, the GNU Bourne-again shell
+(*note Top: (bash)Top.).
+
+ Bourne shell variants for which problems have been reported in the
+past are:
+`ksh'
+ Old versions of the Korn shell may fail to handle the scripts.
+ The Korn shell may be installed as `/bin/sh' on AIX, in which case
+ `/bin/bsh' may serve instead.
+
+`ash'
+ Old versions of ash are unable to handle the scripts. Ash is
+ sometimes installed as `/bin/sh' on NetBSD, FreeBSD, and Linux
+ systems. `/bin/bash' should be available for those systems, but
+ might not be part of a default installation.
+
+`Ultrix /bin/sh'
+ `/bin/sh' under Ultrix is a DEC-grown shell that is notably
+ deficient in many ways. `/bin/sh5' may be necessary.
+
+
+File: kpathsea.info, Node: configure options, Next: configure environment, Prev: configure shells, Up: Running configure
+
+2.2.4.2 `configure' options
+...........................
+
+For a complete list of all `configure' options, run `configure --help'
+or see *note Running `configure' scripts: (autoconf)Invoking configure,
+(a copy is in the file `kpathsea/README.CONFIGURE'). The generic
+options are listed first in the `--help' output, and the
+package-specific options come last. The environment variables
+`configure' pays attention to are listed below.
+
+ Options particularly likely to be useful are `--prefix',
+`--datadir', and the like; see *note configure scenarios::.
+
+ This section gives pointers to descriptions of the `--with' and
+`--enable' options to `configure' that Kpathsea-using programs accept.
+
+`--without-mktexmf-default'
+`--without-mktexpk-default'
+`--without-mktextfm-default'
+`--with-mktextex-default'
+ Enable or disable the dynamic generation programs. *Note mktex
+ configuration::.
+
+`--enable-shared'
+ Build Kpathsea as a shared library, and link against it. Also
+ build the usual static library. *Note Shared library::.
+
+`--disable-static'
+ Build only the shared library. Implies `--enable-shared'.
+
+`--enable-maintainer-mode'
+ Enables make targets that are useful for the maintainer and likely
+ to be a pain for anyone else; the makefiles created when this
+ option is enabled may not work at all for you. You have been
+ warned.
+
+
+File: kpathsea.info, Node: configure environment, Next: configure scenarios, Prev: configure options, Up: Running configure
+
+2.2.4.3 `configure' environment
+...............................
+
+`configure' uses the value of the following environment variables in
+determining your system's characteristics, and substitutes for them in
+Makefile's:
+
+`CC'
+ The compiler to use: default is `gcc' if it's installed, otherwise
+ `cc'.
+
+`CFLAGS'
+ Options to give the compiler: default is `-g -O2' for `gcc', `-g'
+ otherwise. `CFLAGS' comes after any other options. You may need
+ to include `-w' here if your compilations commonly have useless
+ warnings (e.g., `NULL redefined'), or `configure' may fail to
+ detect the presence of header files (it takes the messages on
+ standard error to mean the header file doesn't exist).
+
+`CPPFLAGS'
+ Options to pass to the compiler preprocessor; this matters most for
+ configuration, not the actual source compilation. The `configure'
+ script often does only preprocessing (e.g., to check for the
+ existence of #include files), and `CFLAGS' is not used for this.
+ You may need to set this to something like
+ `-I/usr/local/include/wwwhatever' if you have the libwww library
+ installed for hyper-xdvik (see `xdvik/INSTALL').
+
+`DEFS'
+ Additional preprocessor options, but not used by `configure'.
+ Provided for enabling or disabling program features, as documented
+ in the various program-specific installation instructions. `DEFS'
+ comes before any compiler options included by the distribution
+ `Makefile's or by `configure'.
+
+`LDFLAGS'
+ Additional options to give to the loader. `LDFLAGS' comes before
+ any other linker options.
+
+`LIBS'
+ Additional libraries to link with.
+
+
+File: kpathsea.info, Node: configure scenarios, Next: Shared library, Prev: configure environment, Up: Running configure
+
+2.2.4.4 `configure' scenarios
+.............................
+
+Here are some common installation scenarios:
+
+ * Including X support in Metafont. This is disabled by default,
+ since many sites have no use for it, and it's a leading cause of
+ configuration problems.
+ configure --with-x
+
+ * Putting the binaries, TeX files, GNU info files, etc. into a single
+ TeX hierarchy, say `/here/texmf', requires overriding defaults in
+ `configure':
+ configure --prefix=/here/texmf --datadir=/here
+
+ * You can compile on multiple architectures simultaneously either by
+ building symbolic link trees with the `lndir' script from the X11
+ distribution, or with the `--srcdir' option:
+ configure --srcdir=SRCDIR
+
+ * If you are installing binaries for multiple architectures into a
+ single hierarchy, you will probably want to override the default
+ `bin' and `lib' directories, something like this:
+ configure --prefix=TEXMF --datadir=TEXMF \
+ --bindir=TEXMF/ARCH/bin --libdir=TEXMF/ARCH/lib
+ make texmf=TEXMF
+ (Unless you make provisions for architecture-specific files in
+ other ways, e.g., with Depot or an automounter.)
+
+ * To compile with optimization (to compile without debugging, remove
+ the `-g'):
+ env CFLAGS="-g -O" sh configure ...
+ For a potential problem if you optimize, see *note TeX or Metafont
+ failing: TeX or Metafont failing.
+
+
+File: kpathsea.info, Node: Shared library, Prev: configure scenarios, Up: Running configure
+
+2.2.4.5 Shared library
+......................
+
+You can compile Kpathsea as a shared library on a few systems, by
+specifying the option `--enable-shared' when you run `configure'.
+
+ The main advantage in doing this is that the executables can then
+share the code, thus decreasing memory and disk space requirements.
+
+ On some systems, you can record the location of shared libraries in a
+binary, usually by giving certain options to the linker. Then
+individual users do not need to set their system's environment variable
+(e.g., `LD_LIBRARY_PATH') to find shared libraries. If you want to do
+this, you will need to add the necessary options to `LDFLAGS' yourself;
+for example, on Solaris, include something like `-R${prefix}/lib', on
+IRIX or Linux, use `-rpath${prefix}/lib'. (Unfortunately, making this
+happen by default is very difficult, because of interactions with an
+existing installed shared library.)
+
+
+File: kpathsea.info, Node: Running make, Next: Installing files, Prev: Running configure, Up: Custom installation
+
+2.2.5 Running `make'
+--------------------
+
+`make' (still in the top-level directory). This also creates the
+`texmf.cnf' and `paths.h' files that define the default search paths,
+and (by default) the `plain' and `latex' TeX formats.
+
+ You can override directory names and other values at `make'-time.
+`make/paths.make' lists the variables most commonly reset. For
+example, `make default_texsizes=600' changes the list of fallback
+resolutions.
+
+ You can also override each of `configure''s environment variables
+(*note configure environment::). The Make variables have the same
+names.
+
+ Finally, you can supply additional options via the following
+variables. (`configure' does not use these.)
+
+`XCPPFLAGS'
+`XDEFS'
+ Preprocessor options.
+
+`XCFLAGS'
+ Compiler options.
+
+`XLDFLAGS'
+ Loader options (included at beginning of link commands).
+
+`XLOADLIBES'
+ More loader options (included at end of link commands).
+
+`XMAKEARGS'
+ Additional Make arguments passed to all sub-`make''s. You may need
+ to include assignments to the other variables here via `XMAKEARGS';
+ for example: `make XMAKEARGS="CFLAGS=-O XDEFS=-DA4"'.
+
+ It's generally a bad idea to use a different compiler (`CC') or
+libraries (`LIBS') for compilation than you did for configuration,
+since the values `configure' determined may then be incorrect.
+
+ Adding compiler options to change the "universe" you are using
+(typically BSD vs. system V) is generally a cause of trouble. It's
+best to use the native environment, whatever that is; `configure' and
+the software usually adapt best to that. In particular, under Solaris
+2.x, you should not use the BSD-compatibility library (`libucb') or
+include files (`ucbinclude').
+
+ If you want to use the Babel LaTeX package for support of non-English
+typesetting, you need to modify some files before making the LaTeX
+format. See the file `install.txt' in the Babel distribution.
+
+
+File: kpathsea.info, Node: Installing files, Next: Cleaning up, Prev: Running make, Up: Custom installation
+
+2.2.6 Installing files
+----------------------
+
+The basic command is the usual `make install'. For security issues,
+*note Security::.
+
+ The first time you install any manual in the GNU Info system, you
+should add a line (you choose where) to the file `dir' in your
+`$(infodir)' directory. Sample text for this is given near the top of
+the Texinfo source files (`kpathsea/kpathsea.texi',
+`dvipsk/dvips.texi', and `web2c/doc/web2c.texi'). If you have a recent
+version of the GNU Texinfo distribution installed
+(`ftp://prep.ai.mit.edu/pub/gnu/texinfo-3.9.tar.gz' or later), this
+should happen automatically.
+
+ On the offchance that this is your first Info installation, the
+`dir' file I use is included in the distribution as `etc/dir-example'.
+
+ You may wish to use one of the following targets, especially if you
+are installing on multiple architectures:
+ * `make install-exec' to install in architecture-dependent
+ directories, i.e., ones that depend on the `$(exec_prefix)' Make
+ variable. This includes links to binaries, libraries, etc., not
+ just "executables".
+
+ * `make install-data' to install in architecture-independent
+ directories, such as documentation, configuration files, pool
+ files, etc.
+
+ If you use the Andrew File System, the normal path (e.g.,
+PREFIX/bin) only gets you to a read-only copy of the files, and you
+must specify a different path for installation. The best way to do this
+is by setting the `prefix' variable on the `make' command line. The
+sequence becomes something like this:
+ configure --prefix=/whatever
+ make
+ make install prefix=/afs/.SYSTEM.NAME/system/1.3/@sys/whatever
+ With AFS, you will definitely want to use relative filenames in
+`ls-R' (*note Filename database::), not absolute filenames. This is
+done by default, but check anyway.
+
+
+File: kpathsea.info, Node: Cleaning up, Next: Filename database generation, Prev: Installing files, Up: Custom installation
+
+2.2.7 Cleaning up
+-----------------
+
+The basic command is `make distclean'. This removes all files created
+by the build.
+
+ Alternatively,
+ * `make mostlyclean' if you intend to compile on another
+ architecture. For Web2C, since the generated C files are portable,
+ they are not removed. If the `lex' vs. `flex' situation is going
+ to be different on the next machine, `rm web2c/lex.yy.c'.
+
+ * `make clean' to remove files created by compiling, but leave
+ configuration files and Makefiles.
+
+ * `make maintainer-clean' to remove everything that the Makefiles can
+ rebuild. This is more than `distclean' removes, and you should
+ only use it if you are thoroughly conversant with (and have the
+ necessary versions of) Autoconf.
+
+ * `make extraclean' to remove other junk, e.g., core files, log
+ files, patch rejects. This is independent of the other `clean'
+ targets.
+
+
+File: kpathsea.info, Node: Filename database generation, Next: mktex scripts, Prev: Cleaning up, Up: Custom installation
+
+2.2.8 Filename database generation
+----------------------------------
+
+You will probably want to set up a `cron' entry on the appropriate
+machine(s) to rebuild the filename database nightly or so, as in:
+ 0 0 * * * cd TEXMF && /BINDIR/mktexlsr
+ *Note Filename database::.
+
+ Although the `mktex...' scripts make every effort to add
+newly-created files on the fly, it can't hurt to make sure you get a
+fresh version every so often.
+
+
+File: kpathsea.info, Node: mktex scripts, Next: Installation testing, Prev: Filename database generation, Up: Custom installation
+
+2.2.9 `mktex' scripts
+---------------------
+
+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 (*note mktex configuration::). These are collectively
+known as "`mktex' scripts", since most of them are named `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 `.fmt' (and Metafont `.base' and
+Metapost `.mem' files, *note Memory dumps: (Web2c)Memory dumps.), 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.
+
+
+File: kpathsea.info, Node: mktex configuration, Next: mktex script names, Up: mktex scripts
+
+2.2.9.1 `mktex' configuration
+.............................
+
+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 `configure' options specifying otherwise, everything but
+`mktextex' will be enabled by default. The `configure' options to
+change the defaults are:
+
+ --without-mktexfmt-default
+ --without-mktexmf-default
+ --without-mktexocp-default
+ --without-mktexofm-default
+ --without-mktexpk-default
+ --without-mktextfm-default
+ --with-mktextex-default
+
+ The `configure' setting is overridden if the environment variable or
+configuration file value named for the script is set; e.g., `MKTEXPK'
+(*note mktex script arguments::).
+
+ `mktexfmt' reads a file `fmtutil.cnf', typically located in
+`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.
+
+ As distributed, all the scripts source a file
+`texmf/web2c/mktex.cnf' if it exists, so you can override various
+defaults. See `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 `mktex.cnf'
+with the appropriate definitions (you do not need to create it if you
+have nothing to put in it). `mktex.cnf' has no special syntax; it's an
+arbitrary Bourne shell script. The distribution contains a sample
+`mktex.cnf' for you to copy and modify as you please (it is not
+installed anywhere).
+
+ In addition, you can configure a number of features with the
+`MT_FEATURES' variable, which you can define:
+
+ * in `mktex.opt', as just mentioned;
+
+ * by editing the file `mktex.opt', either before `make install' (in
+ the source hierarchy) or after (in the installed hierarchy);
+
+ * or in the environment.
+
+ If none of the options below are enabled, `mktexpk', `mktextfm', and
+`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 `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 `SYSTEXMF'). If so, the `VARTEXFONTS' tree is used. In all
+other cases the working directory is used.
+
+ The `appendonlydir' option is enabled by default.
+
+`appendonlydir'
+ Tell `mktexdir' to create directories append-only, i.e., set their
+ sticky bit (*note Mode Structure: (coreutils)Mode Structure.).
+ 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.
+
+`dosnames'
+ Use 8.3 names; e.g., `dpi600/cmr10.pk' instead of `cmr10.600pk'.
+ Note that this feature only affects filenames that would otherwise
+ clash with other TeX-related filenames; `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, `cmr10.600pk' would clash with
+ `cmr10.600gf' and is therefore changed when `dosnames' is in
+ effect, but `mf.pool' and `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
+ `dosnames' to be set on an MS-DOS platform, you need to set the
+ `MT_FEATURES' environment variable to a value that doesn't include
+ `dosnames'. You can also change the default setting by editing
+ `mktex.opt', but only if you use the `mktex' shell scripts; the
+ emulation programs don't consult `mktex.opt'.
+
+`fontmaps'
+ 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. (*note Introduction:
+ (fontname)Top.).
+
+`nomfdrivers'
+ 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.
+
+`nomode'
+ Omit the directory level for the mode name; this is fine as long as
+ you generate fonts for only one mode.
+
+`stripsupplier'
+ Omit the font supplier name directory level.
+
+`striptypeface'
+ Omit the font typeface name directory level.
+
+`strip'
+ Omit the font supplier and typeface name directory levels. This
+ feature is deprecated in favour of `stripsupplier' and
+ `striptypeface'.
+
+`varfonts'
+ When this option is enabled, fonts that would otherwise be written
+ in system texmf tree go to the `VARTEXFONTS' tree instead. The
+ default value in `kpathsea/Makefile.in' is `/var/tmp/texfonts'.
+ The `Linux File System Standard' recommends `/var/tex/fonts'.
+
+ The `varfonts' setting in `MT_FEATURES' is overridden by the
+ `USE_VARTEXFONTS' environment variable: if set to `1', the feature
+ is enabled, and if set to `0', the feature is disabled.
+
+`texmfvar'
+ Force generated files that would go into a system tree (as defined
+ by `SYSTEXMF') into `TEXMFVAR'. Starting with teTeX-3.0, the
+ variable `TEXMFVAR' is always set. The `varfonts' feature takes
+ precedence if also set.
+
+ The `texmfvar' setting in `MT_FEATURES' is overridden by the
+ `USE_TEXMFVAR' environment variable: if set to `1', the feature is
+ enabled, and if set to `0', the feature is disabled.
+
+
+File: kpathsea.info, Node: mktex script names, Next: mktex script arguments, Prev: mktex configuration, Up: mktex scripts
+
+2.2.9.2 `mktex' script names
+............................
+
+The following table shows the default name of the script for each of
+the file types which support runtime generation.
+
+`mktexfmt'
+ (`.fmt', `.base', `.mem') TeX/Metafont/MetaPost formats. This
+ script is also named `fmtutil', and reads `fmtutil.cnf' for
+ configuration information.
+
+`mktexmf'
+ (`.mf') Metafont input files.
+
+`mkocp'
+ (`.ocp') Omega compiled process files.
+
+`mkofm'
+ (`.ofm') Omega font metric files.
+
+`mktexpk'
+ (`pk') Glyph fonts.
+
+`mktextex'
+ (`.tex') TeX input files (disabled by default).
+
+`mktextfm'
+ (`.tfm') TFM files.
+
+These names can be overridden by an environment variable specific to
+the program--for example, `DVIPSMAKEPK' for Dvipsk.
+
+ If a `mktex...' script fails, the invocation is appended to a 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.
+
+ If the current directory is not writable and the environment
+variable or configuration file value `TEXMFOUTPUT' is set, its value is
+used. Otherwise, nothing is written. The name `missfont.log' is
+overridden by the `MISSFONT_LOG' environment variable or configuration
+file value.
+
+
+File: kpathsea.info, Node: mktex script arguments, Prev: mktex script names, Up: mktex scripts
+
+2.2.9.3 `mktex' script arguments
+................................
+
+The first argument to a `mktex' script is always the name of the file
+to be created.
+
+ In the default `mktexpk' implementation, additional arguments may
+also be passed:
+
+`--dpi NUM'
+ Sets the resolution of the generated font to NUM.
+
+`--mfmode NAME'
+ Sets the Metafont mode to NAME.
+
+`--bdpi NUM'
+ Sets the "base dpi" for the font. This must match the mode being
+ used.
+
+`--mag STRING'
+ A "magstep" string suitable for the Metafont `mag' variable. This
+ must match the combination of BDPI and DPI being used.
+
+`--destdir 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.
+
+
+File: kpathsea.info, Node: Installation testing, Prev: mktex scripts, Up: Custom installation
+
+2.2.10 Installation testing
+---------------------------
+
+Besides the tests listed in *note Simple installation::, you can try
+running `make check'. This includes the torture tests (trip, trap, and
+mptrap) that come with Web2c (*note Triptrap: (web2c)Triptrap.).
+
+
+File: kpathsea.info, Node: Security, Next: TeX directory structure, Prev: Custom installation, Up: Installation
+
+2.3 Security
+============
+
+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.
+
+ A TeX document, however, can write to arbitrary files, e.g.,
+`~/.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
+`texmf.cnf'. *Note tex invocation: (web2c)tex invocation. MetaPost has
+the same issue.
+
+ Dvips, Xdvi, and TeX can also execute shell commands under some
+circumstances. To disable this, see the `-R' option in *note Option
+details: (dvips)Option details, the xdvi man page, and *note tex
+invocation: (web2c)tex invocation, respectively.
+
+ Another security issue arises because it's very useful--almost
+necessary--to make arbitrary fonts on user demand with `mktexpk' and
+friends. Where do these files get installed? By default, the
+`mktexpk' distributed with Kpathsea assumes a world-writable `/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.
+
+ 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 `VARTEXFONTS' in
+`texmf.cnf' to refer to some globally known directory. *Note mktex
+configuration::.
+
+ The first restriction you can apply is to make newly-created
+directories under `texmf' be append-only with an option in `mktex.cnf'.
+*Note mktex configuration::.
+
+ Another approach is to establish a group (or user) for TeX files,
+make the `texmf' tree writable only to that group (or user), and make
+`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.)
+
+ The `mktex...' 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.
+
+ Any directories created by the `mktex...' scripts have the same
+permissions as their parent directory, unless the `appendonlydir'
+feature is used, in which case the sticky bit is always set.
+
+
+File: kpathsea.info, Node: TeX directory structure, Next: unixtex.ftp, Prev: Security, Up: Installation
+
+2.4 TeX directory structure
+===========================
+
+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 standard is available
+as `ftp://prep.ai.mit.edu/pub/gnu/standards/standards.texi' and
+mirrors. The TDS document is available from `CTAN:/tex-archive/tds'
+(*note unixtex.ftp::).
+
+ You can change the default paths in many ways (*note Changing search
+paths::). One common desire is to put everything (binaries and all)
+under a single top-level directory such as `/usr/local/texmf' or
+`/opt/texmf'--in the terms used below, make PREFIX and TEXMF the same.
+For specific instructions on doing that, see *note configure
+scenarios::.
+
+ Here is a skeleton of the default directory structure, extracted from
+the TDS document:
+
+ PREFIX/ installation root (`/usr/local' by default)
+ bin/ executables
+ man/ man pages
+ include/ C header files
+ info/ GNU info files
+ lib/ libraries (`libkpathsea.*')
+ share/ architecture-independent files
+ texmf/ TDS root
+ bibtex/ BibTeX input files
+ bib/ BibTeX databases
+ base/ base distribution (e.g., `xampl.bib')
+ misc/ single-file databases
+ PKG/ name of a package
+ bst/ BibTeX style files
+ base/ base distribution (e.g., `plain.bst', `acm.bst')
+ misc/ single-file styles
+ PKG/ name of a package
+ doc/ additional documentation
+ dvips/ `.pro', `.ps', `psfonts.map'
+ fonts/ font-related files
+ TYPE/ file type (e.g., `tfm', `pk')
+ MODE/ type of output device (types `pk' and `gf' only)
+ SUPPLIER/ name of a font supplier (e.g., `public')
+ TYPEFACE/ name of a typeface (e.g., `cm')
+ dpiNNN/ font resolution (types `pk' and `gf' only)
+ metafont/ Metafont (non-font) input files
+ base/ base distribution (e.g., `plain.mf')
+ misc/ single-file packages (e.g., `modes.mf')
+ PKG/ name of a package (e.g., `mfpic')
+ metapost/ MetaPost input files
+ base/ base distribution (e.g., `plain.mp')
+ misc/ single-file packages
+ PKG/ name of a package
+ support/ support files for MetaPost-related utilities (e.g., `trfonts.map')
+ mft/ `MFT' inputs (e.g., `plain.mft')
+ tex/ TeX input files
+ FORMAT/ name of a format (e.g., `plain')
+ base/ base distribution for FORMAT (e.g., `plain.tex')
+ misc/ single-file packages (e.g., `webmac.tex')
+ local/ local additions to or local configuration files for FORMAT
+ PKG/ name of a package (e.g., `graphics', `mfnfss')
+ generic/ format-independent packages
+ hyphen/ hyphenation patterns (e.g., `hyphen.tex')
+ images/ image input files (e.g., Encapsulated PostScript)
+ misc/ single-file format-independent packages (e.g., `null.tex').
+ PKG/ name of a package (e.g., `babel')
+ web2c/ implementation-dependent files (`.pool', `.fmt', `texmf.cnf', etc.)
+
+ Some concrete examples for most file types:
+
+ /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
+
+
+File: kpathsea.info, Node: unixtex.ftp, Next: Reporting bugs, Prev: TeX directory structure, Up: Installation
+
+2.5 `unixtex.ftp': Obtaining TeX
+================================
+
+This is `ftp://ftp.tug.org/tex/unixtex.ftp', last updated 13 June 2010.
+Also available as `http://www.tug.org/unixtex.ftp'. Email
+<tex-k@tug.org> with comments or questions.
+
+ The principal free TeX distribution for Unix-like systems is TeX
+Live, on the web at `http://tug.org/texlive'. The pages there describe
+many ways to acquire TeX, over the Internet or on physical media, both
+the sources and precompiled binaries for many systems, either
+standalone or as part of various operating system distributions.
+
+ Web2C, Kpathsea, Dvips, and Dviljk are no longer released as a
+separate packages. Their sources are now maintained as part of TeX
+Live.
+
+ The host ftp.cs.stanford.edu is the original source for the files
+for which Donald Knuth is directly responsible: `tex.web', `plain.tex',
+etc. However, unless you want to build your TeX library tree ab initio,
+it is more reliable and less work to retrieve these files as part of a
+larger package. In any case, that ftp site is not the canonical source
+for anything except what was created as part of Stanford TeX project,
+so do not rely on the other files available there being up-to-date.
+
+
+File: kpathsea.info, Node: Reporting bugs, Prev: unixtex.ftp, Up: Installation
+
+2.6 Reporting bugs
+==================
+
+(A copy of this chapter is in the file `kpathsea/BUGS'.)
+
+If you have problems or suggestions, please report them to
+<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, ...
+
+* 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.
+
+
+File: kpathsea.info, Node: Bug checklist, Next: Mailing lists, Up: Reporting bugs
+
+2.6.1 Bug checklist
+-------------------
+
+Before reporting a bug, please check below to be sure it isn't already
+known (*note Common problems::).
+
+ Bug reports should be sent via electronic mail to <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:
+
+ * The version number(s) of the program(s) involved, and of Kpathsea
+ itself. You can get the former by giving a sole option `--version'
+ to the program, and the latter by running `kpsewhich --version'.
+ The `NEWS' and `ChangeLog' files also contain the version number.
+
+ * The hardware, operating system (including version number),
+ compiler, and `make' program you are using (the output of `uname
+ -a' is a start on the first two, though often incomplete). If the
+ bug involves the X window system, include X version and supplier
+ information as well (examples: X11R6 from MIT; X11R4 from HP;
+ OpenWindows 3.3 bundled with SunOS 4.1.4).
+
+ * Any options you gave to `configure'. This is recorded in the
+ `config.status' files.
+
+ If you are reporting a bug in `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 `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 `configure' bugs do not involve the
+ compiler; in that case, the only recourse is to inspect the
+ `configure' shell script itself, or the Autoconf macros that
+ generated `configure'.
+
+ * The log of all debugging output, if the bug is in path searching.
+ You can get this by setting the environment variable
+ `KPATHSEA_DEBUG' to `-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.
+
+ * 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 necessary, because that's
+ the actual program input.
+
+ * If you are sending a patch (do so if you can!), please do so in
+ the form of a context diff (`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
+ `ChangeLog' entry.
+
+ * 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, available from
+ `ftp://prep.ai.mit.edu/pub/gnu'). If the cause is apparent (a
+ `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 (*note TeX or Metafont failing: TeX or Metafont failing.).
+
+ * Any additional information that will be helpful in reproducing,
+ diagnosing, or fixing the bug.
+
+
+File: kpathsea.info, Node: Mailing lists, Next: Debugging, Prev: Bug checklist, Up: Reporting bugs
+
+2.6.2 Mailing lists
+-------------------
+
+Web2c and Kpathsea in general are discussed on the mailing list
+<tex-k@tug.org>. To join, email <tex-k-request@tug.org> with a line
+consisting of
+
+ subscribe YOU@YOUR.PREFERRED.EMAIL.ADDRESS
+
+in the body of the message.
+
+ You do not need to join to submit a report, nor will it affect
+whether you get a response. There is no Usenet newsgroup equivalent
+(if you can be the one to set this up, email `tex-k-request'). Traffic
+on the list is fairly light, and is mainly bug reports and enhancement
+requests to the software. The best way to decide if you want to join
+or not is read some of the archives from
+`ftp://ftp.tug.org/mail/archives/tex-k/'.
+
+ 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 use LaTeX,
+please use the mailing list <texhax@tug.org> mailing list
+(`http://lists.tug.org/texhax') which is gatewayed to the
+`comp.text.tex' Usenet newsgroup (or post to the newsgroup; the gateway
+is bidirectional).
+
+
+File: kpathsea.info, Node: Debugging, Next: Logging, Prev: Mailing lists, Up: Reporting bugs
+
+2.6.3 Debugging
+---------------
+
+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., `-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 `-d' (or whatever) option
+first, for maximal output. Dvipsk and Xdvik have additional
+program-specific debugging options as well.
+
+ You can also set the environment variable `KPATHSEA_DEBUG'; in this
+case, you should use the numbers below. If you run the program under a
+debugger and set the instance variable `kpse->debug', also use the
+numbers below.
+
+ In any case, by far the simplest value to use is `-1', which will
+turn on all debugging output. This is usually better than guessing
+which particular values will yield the output you need.
+
+ Debugging output always goes to standard error, so you can redirect
+it easily. For example, in Bourne-compatible shells:
+ dvips -d -1 ... 2>/tmp/debug
+
+ It is sometimes helpful to run the standalone Kpsewhich utility
+(*note Invoking kpsewhich::), instead of the original program.
+
+ In any case, you can _not_ use the _names_ below; you must always
+use somebody's numbers. (Sorry.) To set more than one option, just
+sum the corresponding numbers.
+
+`KPSE_DEBUG_STAT (1)'
+ Report `stat'(2) calls. This is useful for verifying that your
+ directory structure is not forcing Kpathsea to do many additional
+ file tests (*note Slow path searching::, and *note Subdirectory
+ expansion::). If you are using an up-to-date `ls-R' database
+ (*note Filename database::), this should produce no output unless a
+ nonexistent file that must exist is searched for.
+
+`KPSE_DEBUG_HASH (2)'
+ Report lookups in all hash tables: `ls-R' and `aliases' (*note
+ Filename database::); font aliases (*note Fontmap::); and config
+ file values (*note Config files::). Useful when expected values
+ are not being found, e.g.., file searches are looking at the disk
+ instead of using `ls-R'.
+
+`KPSE_DEBUG_FOPEN (4)'
+ 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 `fopen' (`fclose') to be
+ `kpse_fopen_trace' (`kpse_fclose_trace').
+
+`KPSE_DEBUG_PATHS (8)'
+ 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 `texmf.cnf', `config.ps',
+ an environment variable, the compile-time default, etc. This is
+ the contents of the `kpse_format_info_type' structure defined in
+ `tex-file.h'.
+
+`KPSE_DEBUG_EXPAND (16)'
+ Report the directory list corresponding to each path element
+ Kpathsea searches. This is only relevant when Kpathsea searches
+ the disk, since `ls-R' searches don't look through directory lists
+ in this way.
+
+`KPSE_DEBUG_SEARCH (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 `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., `texmf.cnf' and `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.
+
+`KPSE_DEBUG_VARS (64)'
+ Report the value of each variable Kpathsea looks up. This is
+ useful for verifying that variables do indeed obtain their correct
+ values.
+
+`GSFTOPK_DEBUG (128)'
+ Activates debugging printout specific to `gsftopk' program.
+
+`MAKETEX_DEBUG (512)'
+ If you use the optional `mktex' programs instead of the
+ traditional shell scripts, this will report the name of the site
+ file (`mktex.cnf' by default) which is read, directories created by
+ `mktexdir', the full path of the `ls-R' database built by
+ `mktexlsr', font map searches, `MT_FEATURES' in effect, parameters
+ from `mktexnam', filenames added by `mktexupd', and some
+ subsidiary commands run by the programs.
+
+`MAKETEX_FINE_DEBUG (1024)'
+ When the optional `mktex' programs are used, this will print
+ additional debugging info from functions internal to these
+ programs.
+
+ Debugging output from Kpathsea is always written to standard error,
+and begins with the string `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 `hash_summary_only'
+variable in `kpathsea/db.c'.)
+
+
+File: kpathsea.info, Node: Logging, Next: Common problems, Prev: Debugging, Up: Reporting bugs
+
+2.6.4 Logging
+-------------
+
+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.
+
+ To do this, define the environment or config file variable
+`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.
+
+ 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 `time' system call).
+The second word is the filename.
+
+ For example, after `setenv TEXMFLOG /tmp/log', running Dvips on
+`story.dvi' appends the following lines:
+
+ 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
+
+Only filenames that are absolute are recorded, to preserve some
+semblance of privacy.
+
+ In addition to this Kpathsea-specific logging, `pdftex' provides an
+option `-recorder' to write the names of all files accessed during a
+run to the file `BASEFILE.fls'.
+
+ Finally, most systems provide a general tool to output each system
+call, thus including opening and closing files. It might be named
+`strace', `truss', `struss', or something else.
+
+
+File: kpathsea.info, Node: Common problems, Prev: Logging, Up: Reporting bugs
+
+2.6.5 Common problems
+---------------------
+
+Here are some common problems with configuration, compilation, linking,
+execution, ...
+
+* 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.
+
+* Empty Makefiles:: When configure produces empty makefiles.
+* XtStrings:: When _XtStrings is undefined.
+* dlopen:: When dlopen is undefined.
+* ShellWidgetClass:: For dynamic linking troubles under OpenWindows.
+* Pointer combination warnings:: For old compilers that don't grok char *.
+
+
+File: kpathsea.info, Node: Unable to find files, Next: Slow path searching, Up: Common problems
+
+2.6.5.1 Unable to find files
+............................
+
+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. *Note Debugging::.
+
+ * Perhaps you simply haven't installed all the necessary files; the
+ basic fonts and input files are distributed separately from the
+ programs. *Note unixtex.ftp::.
+
+ * 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 `texmf.cnf' (*note
+ Supported file formats::). System `/etc/profile' or other files
+ such may be the culprit.
+
+ * Your files reside in a directory that is only pointed to via a
+ symbolic link, in a leaf directory and is not listed in `ls-R'.
+
+ Unfortunately, Kpathsea's subdirectory searching has an
+ irremediable deficiency: If a directory D being searched for
+ subdirectories contains plain files and symbolic links to other
+ directories, but no true subdirectories, D will be considered a
+ leaf directory, i.e., the symbolic links will not be followed.
+ *Note Subdirectory expansion::.
+
+ You can work around this problem by creating an empty dummy
+ subdirectory in D. Then D will no longer be a leaf, and the
+ symlinks will be followed.
+
+ The directory immediately followed by the `//' 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.
+
+ * If the fonts (or whatever) don't already exist, `mktexpk' (or
+ `mktexmf' or `mktextfm') will try to create them. If these rather
+ complicated shell scripts fail, you'll eventually get an error
+ message saying something like `Can't find font FONTNAME'. The best
+ solution is to fix (or at least report) the bug in `mktexpk'; the
+ workaround is to generate the necessary fonts by hand with
+ Metafont, or to grab them from a CTAN site (*note unixtex.ftp::).
+
+ * There is a bug in the library. *Note Reporting bugs::.
+
+
+File: kpathsea.info, Node: Slow path searching, Next: Unable to generate fonts, Prev: Unable to find files, Up: Common problems
+
+2.6.5.2 Slow path searching
+...........................
+
+If your program takes an excessively long time to find fonts or other
+input files, but does eventually succeed, here are some possible
+culprits:
+
+ * 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 `ls-R' file that lists all the files in your main TeX
+ hierarchy. *Note Filename database::. Kpathsea always uses `ls-R'
+ if it's present; there's no need to recompile or reconfigure any
+ of the programs.
+
+ * Your recursively-searched directories (e.g.,
+ `/usr/local/share/texmf/fonts//'), contain a mixture of files and
+ directories. This prevents Kpathsea from using a useful
+ optimization (*note Subdirectory expansion::).
+
+ It is best to have only directories (and perhaps a `README') in the
+ upper levels of the directory structure, and it's very important
+ to have _only_ files, and no subdirectories, in the leaf
+ directories where the dozens of TFM, PK, or whatever files reside.
+
+ In any case, you may find the debugging options helpful in
+determining precisely when the disk or network is being pounded. *Note
+Debugging::.
+
+
+File: kpathsea.info, Node: Unable to generate fonts, Next: TeX or Metafont failing, Prev: Slow path searching, Up: Common problems
+
+2.6.5.3 Unable to generate fonts
+................................
+
+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.
+
+ If `mktexpk' runs, but fails with this error:
+ mktexpk: Can't guess mode for NNN dpi devices.
+ mktexpk: Use a config file to specify the mode, or update me.
+ you need to ensure the resolution and mode match; just specifying
+the resolution, as in `-D 360', is not enough.
+
+ You can specify the mode name with the `-mode' option on the Dvips
+command line, or in a Dvips configuration file (*note Config files:
+(dvips)Config files.), such as `config.ps' in your document directory,
+`~/.dvipsrc' in your home directory, or in a system directory (again
+named `config.ps'). (Other drivers use other files, naturally.)
+
+ For example, if you need 360dpi fonts, you could include this in a
+configuration file:
+ D 360
+ M lqmed
+
+ If Metafont runs, but generates fonts at the wrong resolution or for
+the wrong device, most likely `mktexpk''s built-in guess for the mode
+is wrong, and you should override it as above.
+
+ See `ftp://ftp.tug.org/tex/modes.mf' for a list of resolutions and
+mode names for most devices (additional submissions are welcome).
+
+ If Metafont runs but generates fonts at a resolution of 2602dpi (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
+`proof' mode, instead of an actual device mode.) To make a proper
+`plain.base', assuming the local mode definitions are contained in a
+file `modes.mf', run the following command (assuming Unix):
+
+ inimf "plain; input modes; dump"
+
+Then copy the `plain.base' file from the current directory to where the
+base files are stored on your system (`/usr/local/share/texmf/web2c' by
+default), and make a link (either hard or soft) from `plain.base' to
+`mf.base' in that directory. *Note inimf invocation: (web2c)inimf
+invocation.
+
+ If `mf' is a command not found at all by `mktexpk', then you need to
+install Metafont (*note unixtex.ftp::).
+
+
+File: kpathsea.info, Node: TeX or Metafont failing, Next: Empty Makefiles, Prev: Unable to generate fonts, Up: Common problems
+
+2.6.5.4 TeX or Metafont failing
+...............................
+
+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.
+
+ Insufficient swap space may also cause core dumps or other erratic
+behavior.
+
+ 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.
+
+ 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 *note Bugs:
+(gcc)Bugs.
+
+ 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. Things are not
+helped by all-too-common bugs in the debugger itself. Good luck.
+
+ One known cause of trouble is the way arrays are handled. Some of
+the Pascal arrays have a lower index other than 0, and the C code will
+take the pointer to the allocated memory, subtract the lower index, and
+use the resulting pointer for the array. While this trick often works,
+ANSI C doesn't guarantee that it will. It it known to fail on HP-UX 10
+machines when the native compiler is used, unless the `+u' compiler
+switch was specified. Using GCC will work on this platform as well.
+
+
+File: kpathsea.info, Node: Empty Makefiles, Next: XtStrings, Prev: TeX or Metafont failing, Up: Common problems
+
+2.6.5.5 Empty Makefiles
+.......................
+
+On some systems (NetBSD, FreeBSD, AIX 4.1, and Mach10), `configure' may
+fail to properly create the Makefiles. Instead, you get an error which
+looks something like this:
+
+ prompt$ ./configure
+ ...
+ creating Makefile
+ sed: 1: "\\@^ac_include make/pat ...": \ can not
+ be used as a string delimiter
+
+ So far as I know, the bug here is in `/bin/sh' on these systems. I
+don't have access to a machine running any of them, so if someone can
+find a workaround that avoids the quoting bug, I'd be most grateful.
+(Search for `ac_include' in the `configure' script to get to the
+problematic code.)
+
+ It should work to run `bash configure', instead of using `/bin/sh'.
+You can get Bash from `ftp://prep.ai.mit.edu/pub/gnu' and mirrors.
+
+ Another possible cause (reported for NeXT) is a bug in the `sed'
+command. In that case the error may look like this:
+
+ Unrecognized command: \@^ac_include make/paths.make@r make/paths.make
+
+ In this case, installing GNU `sed' should solve the problem. You
+can get GNU `sed' from the same places as Bash.
+
+
+File: kpathsea.info, Node: XtStrings, Next: dlopen, Prev: Empty Makefiles, Up: Common problems
+
+2.6.5.6 `XtStrings'
+...................
+
+You may find that linking X programs results in an error from the linker
+that `XtStrings' is undefined, something like this:
+
+ gcc -o virmf ...
+ .../x11.c:130: undefined reference to `XtStrings'
+
+ This generally happens because of a mismatch between the X include
+files with which you compiled and the X libraries with which you linked;
+often, the include files are from MIT and the libraries from Sun.
+
+ The solution is to use the same X distribution for compilation and
+linking. Probably `configure' was unable to guess the proper
+directories from your installation. You can use the `configure'
+options `--x-includes=PATH' and `--x-libraries=PATH' to explicitly
+specify them.
+
+
+File: kpathsea.info, Node: dlopen, Next: ShellWidgetClass, Prev: XtStrings, Up: Common problems
+
+2.6.5.7 `dlopen'
+................
+
+(This section adapted from the file `dlsym.c' in the X distribution.)
+
+ The `Xlib' library uses the standard C function `wcstombs'. Under
+SunOS 4.1, `wcstombs' uses the `dlsym' interface defined in `libdl.so'.
+Unfortunately, the SunOS 4.1 distribution does not include a static
+`libdl.a' library.
+
+ As a result, if you try to link an X program statically under SunOS,
+you may get undefined references to `dlopen', `dlsym', and `dlclose'.
+One workaround is to include these definitions when you link:
+
+ void *dlopen() { return 0; }
+ void *dlsym() { return 0; }
+ int dlclose() { return -1; }
+
+These are contained in the `dlsym.c' file in the MIT X distribution.
+
+
+File: kpathsea.info, Node: ShellWidgetClass, Next: Pointer combination warnings, Prev: dlopen, Up: Common problems
+
+2.6.5.8 `ShellWidgetClass'
+..........................
+
+(This section adapted from the comp.sys.sun.admin FAQ.)
+
+ If you are linking with Sun's OpenWindows libraries in SunOS 4.1.x,
+you may get undefined symbols `_get_wmShellWidgetClass' and
+`_get_applicationShellWidgetClass' when linking. This problem does not
+arise using the standard MIT X libraries under SunOS.
+
+ The cause is bugs in the `Xmu' shared library as shipped from Sun.
+There are several fixes:
+
+ * Install the free MIT distribution from `ftp.x.org' and mirrors.
+
+ * Get the OpenWindows patches listed below.
+
+ * Statically link the `Xmu' library into the executable.
+
+ * Avoid using `Xmu' at all. If you are compiling Metafont, see *note
+ Online Metafont graphics: (web2c)Online Metafont graphics. If you
+ are compiling Xdvi, see the `-DNOTOOL' option in `xdvik/INSTALL'.
+
+ * Ignore the errors. The binary runs fine regardless.
+
+
+ Here is the information for getting the two patches:
+
+ Patch ID: 100512-02
+ Bug ID's: 1086793, 1086912, 1074766
+ Description: 4.1.x OpenWindows 3.0 `libXt' jumbo patch
+
+ Patch ID: 100573-03
+ Bug ID: 1087332
+ Description: 4.1.x OpenWindows 3.0 undefined symbols when using shared `libXmu'.
+
+ The way to statically link with `libXmu' depends on whether you are
+using a Sun compiler (e.g., `cc') or `gcc'. If the latter, alter the
+`x_libs' Make variable to include
+
+ -static -lXmu -dynamic
+
+ If you are using the Sun compiler, use `-Bstatic' and `-Bdynamic'.
+
+
+File: kpathsea.info, Node: Pointer combination warnings, Prev: ShellWidgetClass, Up: Common problems
+
+2.6.5.9 Pointer combination warnings
+....................................
+
+When compiling with old C compilers, you may get some warnings about
+"illegal pointer combinations". These are spurious; just ignore them.
+I decline to clutter up the source with casts to get rid of them.
+
+
+File: kpathsea.info, Node: Path searching, Next: TeX support, Prev: Installation, Up: Top
+
+3 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.
+
+
+File: kpathsea.info, Node: Searching overview, Next: Path sources, Up: Path searching
+
+3.1 Searching overview
+======================
+
+A "search path" is a colon-separated list of "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 `foo'
+along a path `.:/dir', Kpathsea checks each element of the path in
+turn: first `./foo', then `/dir/foo', returning the first match (or
+possibly all matches).
+
+ The "colon" and "slash" mentioned here aren't necessarily `:' and
+`/' on non-Unix systems. Kpathsea tries to adapt to other operating
+systems' conventions.
+
+ To check a particular path element E, Kpathsea first sees if a
+prebuilt database (*note Filename database::) applies to E, i.e., if
+the database is in a directory that is a prefix of E. If so, the path
+specification is matched against the contents of the database.
+
+ 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 `!!' 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.)
+
+ The "file must exist" condition comes into play with VF files and
+input files read by the TeX `\openin' command. These files might very
+well not exist (consider `cmr10.vf'), and so it would be wrong to
+search the disk for them. Therefore, if you fail to update `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.)
+
+ 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 "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.
+
+ Exception to all of the above: If the filename being searched for is
+absolute or explicitly relative, i.e., starts with `/' or `./' or
+`../', Kpathsea simply checks if that file exists.
+
+ 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 `lost+found' directory). If you prefer not to see these
+warnings, include the value `readable' in the `TEX_HUSH' environment
+variable or config file value.
+
+ This generic path searching algorithm is implemented in
+`kpathsea/pathsearch.c'. It is employed by a higher-level algorithm
+when searching for a file of a particular type (*note File lookup::,
+and *note Glyph lookup::).
+
+
+File: kpathsea.info, Node: Path sources, Next: Path expansion, Prev: Searching overview, Up: Path searching
+
+3.2 Path sources
+================
+
+A search path can come from many sources. In the order in which
+Kpathsea uses them:
+
+ 1. A user-set environment variable, e.g., `TEXINPUTS'. Environment
+ variables with an underscore and the program name appended
+ override; for example, `TEXINPUTS_latex' overrides `TEXINPUTS' if
+ the program being run is named `latex'.
+
+ 2. A program-specific configuration file, e.g., an `S /a:/b' line in
+ Dvips' `config.ps' (*note Config files: (dvips)Config files.).
+
+ 3. A line in a Kpathsea configuration file `texmf.cnf', e.g.,
+ `TEXINPUTS=/c:/d' (see below).
+
+ 4. The compile-time default (specified in `kpathsea/paths.h').
+
+ You can see each of these values for a given search path by using the
+debugging options (*note Debugging::).
+
+ These sources may be combined via default expansion (*note Default
+expansion::).
+
+* Menu:
+
+* Config files:: Kpathsea's runtime config files (texmf.cnf).
+
+
+File: kpathsea.info, Node: Config files, Up: Path sources
+
+3.2.1 Config files
+------------------
+
+As mentioned above, Kpathsea reads "runtime configuration files" named
+`texmf.cnf' for search path and other definitions. The search path
+used to look for these configuration files is named `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 `ls-R' database is not used to search for them.
+
+ Kpathsea reads _all_ `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 `.:$TEXMF', values from
+`./texmf.cnf' override those from `$TEXMF/texmf.cnf'.
+
+ If Kpathsea cannot find any `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 `KPATHSEA_WARNING' to the
+single character `0' (zero, not oh).
+
+ While (or instead of) reading this description, you may find it
+helpful to look at the distributed `texmf.cnf', which uses or at least
+mentions most features. The format of `texmf.cnf' files follows:
+
+ * Comments start with `%', either at the beginning of a line or
+ preceded by whitespace, and continue to the end of the line. That
+ is, as with most shells, a `%' in the "middle" of a value does not
+ start a comment. Examples:
+
+ % this is a comment
+ var = a%b % but the value of var will be "a%b".
+
+ * Blank lines are ignored.
+
+ * A `\' 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.
+
+ * Each remaining line must look like
+
+ VARIABLE [. PROGNAME] [=] VALUE
+
+ where the `=' and surrounding whitespace is optional.
+
+ * The VARIABLE name may contain any character other than whitespace,
+ `=', or `.', but sticking to `A-Za-z_' is safest.
+
+ * If `.PROGNAME' is present, the definition only applies if the
+ program that is running is named (i.e., the last component of
+ `argv[0]' is) PROGNAME or `PROGNAME.{exe,bat,cmd,...}'. Most
+ notably, this allows different flavors of TeX to have different
+ search paths.
+
+ * VALUE may contain any characters except `%' and `@'. (These
+ restrictions are only necessary because of the processing done on
+ `texmf.cnf' at build time, so you can stick those characters in
+ after installation if you have to.) The `$VAR.PROG' feature is
+ not available on the right-hand side; instead, you must use an
+ additional variable (see below for example). A `;' in VALUE is
+ translated to `:' if running under Unix; this is useful to write a
+ single `texmf.cnf' which can be used under both Unix and Windows.
+
+ * All definitions are read before anything is expanded, so you can
+ use variables before they are defined (like Make, unlike most other
+ programs).
+
+Here is a configuration file fragment illustrating most of these points:
+
+ % 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
+
+ This format has obvious similarities to Bourne shell scripts--change
+the comment character to `#', disallow spaces around the `=', and get
+rid of the `.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 `sh' process couldn't affect its parent's environment.
+
+ The implementation of all this is in `kpathsea/cnf.c'.
+
+
+File: kpathsea.info, Node: Path expansion, Next: Filename database, Prev: Path sources, Up: Path searching
+
+3.3 Path expansion
+==================
+
+Kpathsea recognizes certain special characters and constructions in
+search paths, similar to that in shells. As a general example:
+`~$USER/{foo,bar}//baz' expands to all subdirectories under directories
+`foo' and `bar' in $USER's home directory that contain a directory or
+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.
+
+
+File: kpathsea.info, Node: Default expansion, Next: Variable expansion, Up: Path expansion
+
+3.3.1 Default expansion
+-----------------------
+
+If the highest-priority search path (*note Path sources::) contains an
+"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
+
+ setenv TEXINPUTS /home/karl:
+
+and a `TEXINPUTS' value from `texmf.cnf' of
+
+ .:$TEXMF//tex
+
+then the final value used for searching will be:
+
+ /home/karl:.:$TEXMF//tex
+
+ Put another way, default expansion works on "formats" (search
+paths), and not directly on environment variables. Example, showing
+the trailing `:' ignored in the first case and expanded in the second:
+
+ $ env TTFONTS=/tmp: kpsewhich --expand-path '$TTFONTS'
+ /tmp
+ $ env TTFONTS=/tmp: kpsewhich --show-path=.ttf
+ /tmp:.:/home/olaf/texmf/fonts/truetype//:...
+
+ Since Kpathsea looks for multiple configuration files, it would be
+natural to expect that (for example) an extra colon in `./texmf.cnf'
+would expand to the path in `$TEXMF/texmf.cnf'. Or, with Dvips'
+configuration files, that an extra colon in `config.$PRINTER' would
+expand to the path in `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.
+
+ Technicality: Since it would be useless to insert the default value
+in more than one place, Kpathsea changes only one extra `:' and leaves
+any others in place (they will eventually be ignored). Kpathsea checks
+first for a leading `:', then a trailing `:', then a doubled `:'.
+
+ You can trace this by debugging "paths" (*note Debugging::).
+Default expansion is implemented in the source file
+`kpathsea/kdefault.c'.
+
+
+File: kpathsea.info, Node: Variable expansion, Next: Tilde expansion, Prev: Default expansion, Up: Path expansion
+
+3.3.2 Variable expansion
+------------------------
+
+`$foo' or `${foo}' in a path element is replaced by (1) the value of an
+environment variable `foo' (if defined); (2) the value of `foo' from
+`texmf.cnf' (if defined); (3) the empty string.
+
+ If the character after the `$' is alphanumeric or `_', the variable
+name consists of all consecutive such characters. If the character
+after the `$' is a `{', the variable name consists of everything up to
+the next `}' (braces may not be nested around variable names).
+Otherwise, Kpathsea gives a warning and ignores the `$' and its
+following character.
+
+ You must quote the $'s and braces as necessary for your shell.
+_Shell_ variable values cannot be seen by Kpathsea, i.e., ones defined
+by `set' in C shells and without `export' in Bourne shells.
+
+ For example, given
+ setenv tex /home/texmf
+ setenv TEXINPUTS .:$tex:${tex}prev
+ the final `TEXINPUTS' path is the three directories:
+ .:/home/texmf:/home/texmfprev
+
+ The `.PROGNAME' suffix on variables and `_PROGNAME' on environment
+variable names are not implemented for general variable expansions.
+These are only recognized when search paths are initialized (*note Path
+sources::).
+
+ Variable expansion is implemented in the source file
+`kpathsea/variable.c'.
+
+
+File: kpathsea.info, Node: Tilde expansion, Next: Brace expansion, Prev: Variable expansion, Up: Path expansion
+
+3.3.3 Tilde expansion
+---------------------
+
+A leading `~' in a path element is replaced by the value of the
+environment variable `HOME', or `.' if `HOME' is not set. On Windows,
+the environment variable `USERPROFILE' is checked instead of `HOME'.
+
+ A leading `~USER' in a path element is replaced by USER's home
+directory from the system `passwd' database.
+
+ For example,
+ setenv TEXINPUTS ~/mymacros:
+
+will prepend a directory `mymacros' in your home directory to the
+default path.
+
+ As a special case, if a home directory ends in `/', the trailing
+slash is dropped, to avoid inadvertently creating a `//' construct in
+the path. For example, if the home directory of the user `root' is
+`/', the path element `~root/mymacros' expands to just `/mymacros', not
+`//mymacros'.
+
+ Tilde expansion is implemented in the source file `kpathsea/tilde.c'.
+
+
+File: kpathsea.info, Node: Brace expansion, Next: KPSE_DOT expansion, Prev: Tilde expansion, Up: Path expansion
+
+3.3.4 Brace expansion
+---------------------
+
+`x{A,B}y' expands to `xAy:xBy'. For example:
+
+ foo/{1,2}/baz
+
+expands to `foo/1/baz:foo/2/baz'. `:' is the path separator on the
+current system; e.g., on a DOS system, it's `;'.
+
+ Braces can be nested; for example, `x{A,B{1,2}}y' expands to
+`xAy:xB1y:xB2y'.
+
+ Multiple non-nested braces are expanded from right to left; for
+example, `x{A,B}{1,2}y' expands to `x{A,B}1y:x{A,B}2y', which expands
+to `xA1y:xB1y:xA2y:xB2y'.
+
+ This feature can be used to implement multiple TeX hierarchies, by
+assigning a brace list to `$TEXMF', as mentioned in `texmf.in'.
+
+ You can also use the path separator instead of the comma. The last
+example could have been written `x{A:B}{1:2}y'.
+
+ Brace expansion is implemented in the source file
+`kpathsea/expand.c'.
+
+
+File: kpathsea.info, Node: KPSE_DOT expansion, Next: Subdirectory expansion, Prev: Brace expansion, Up: Path expansion
+
+3.3.5 `KPSE_DOT' expansion
+--------------------------
+
+When `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
+`mktex...' scripts *note mktex scripts::, because these change the
+working directory. You should not ever define it yourself.
+
+
+File: kpathsea.info, Node: Subdirectory expansion, Prev: KPSE_DOT expansion, Up: Path expansion
+
+3.3.6 Subdirectory expansion
+----------------------------
+
+Two or more consecutive slashes in a path element following a directory
+D is replaced by all subdirectories of D: first those subdirectories
+directly under 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 `//', only
+subdirectories which match those components are included. For example,
+`/a//b' would expand into directories `/a/1/b', `/a/2/b', `/a/1/1/b',
+and so on, but not `/a/b/c' or `/a/1'.
+
+ You can include multiple `//' constructs in the path.
+
+ `//' at the beginning of a path is ignored; you didn't really want
+to search every directory on the system, did you?
+
+ I should mention one related implementation trick, which I took from
+GNU find. Matthew Farwell suggested it, and David MacKenzie
+implemented it.
+
+ 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 `.' and one for `..').
+That is to say, the `st_nlink' field in the `stat' structure will be
+two. Thus, we don't have to stat everything in the bottom-level (leaf)
+directories--we can just check `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, `st_nlink' will be 3, and Kpathsea has to stat every
+one of those 501 entries. Therein lies slowness.
+
+ You can disable the trick by undefining `ST_NLINK_TRICK' in
+`kpathsea/config.h'. (It is undefined by default except under Unix.)
+
+ Unfortunately, in some cases files in leaf directories are `stat''d:
+if the path specification is, say, `$TEXMF/fonts//pk//', then files in
+a subdirectory `.../pk', even if it is a leaf, are checked. The reason
+cannot be explained without reference to the implementation, so read
+`kpathsea/elt-dirs.c' (search for `may descend') if you are curious.
+And if you can find a way to _solve_ the problem, please let me know.
+
+ Subdirectory expansion is implemented in the source file
+`kpathsea/elt-dirs.c'.
+
+
+File: kpathsea.info, Node: Filename database, Next: Invoking kpsewhich, Prev: Path expansion, Up: Path searching
+
+3.4 Filename database (`ls-R')
+==============================
+
+Kpathsea goes to some lengths to minimize disk accesses for searches
+(*note 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 "filename database"
+file named `ls-R' that maps files to directories, thus avoiding the
+need to exhaustively search the disk.
+
+ A second database file `aliases' allows you to give additional names
+to the files listed in `ls-R'. This can be helpful to adapt to "8.3"
+filename conventions in source files.
+
+ The `ls-R' and `aliases' features are implemented in the source 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.
+
+
+File: kpathsea.info, Node: ls-R, Next: Filename aliases, Up: Filename database
+
+3.4.1 `ls-R'
+------------
+
+As mentioned above, you must name the main filename database `ls-R'.
+You can put one at the root of each TeX installation hierarchy you wish
+to search (`$TEXMF' by default); most sites have only one hierarchy.
+Kpathsea looks for `ls-R' files along the `TEXMFDBS' path, so that
+should presumably match the list of hierarchies.
+
+ The recommended way to create and maintain `ls-R' is to run the
+`mktexlsr' script, which is installed in `$(bindir)' (`/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 `mktex...'
+scripts.
+
+ At its simplest, though, you can build `ls-R' with the command
+ cd /YOUR/TEXMF/ROOT && ls -LAR ./ >ls-R
+
+presuming your `ls' produces the right output format (see the section
+below). GNU `ls', for example, outputs in this format. Also presuming
+your `ls' hasn't been aliased in a system file (e.g., `/etc/profile')
+to something problematic, e.g., `ls --color=tty'. In that case, you
+will have to disable the alias before generating `ls-R'. For the
+precise definition of the file format, see *note Database format::.
+
+ Regardless of whether you use the supplied script or your own, you
+will almost certainly want to invoke it via `cron', so when you make
+changes in the installed files (say if you install a new LaTeX
+package), `ls-R' will be automatically updated.
+
+ The `-A' option to `ls' includes files beginning with `.' (except
+for `.' and `..'), such as the file `.tex' included with the LaTeX
+tools package. (On the other hand, _directories_ whose names begin
+with `.' are always ignored.)
+
+ If your system does not support symbolic links, omit the `-L'.
+
+ `ls -LAR /YOUR/TEXMF/ROOT' will also work. But using `./' avoids
+embedding absolute pathnames, so the hierarchy can be easily
+transported. It also avoids possible trouble with automounters or
+other network filesystem conventions.
+
+ Kpathsea warns you if it finds an `ls-R' file, but the file does not
+contain any usable entries. The usual culprit is running plain `ls -R'
+instead of `ls -LR ./' or `ls -R /YOUR/TEXMF/ROOT'. Another
+possibility is some system directory name starting with a `.' (perhaps
+if you are using AFS); Kpathsea ignores everything under such
+directories.
+
+ 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 `!!',
+however, _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 `foo.tfm' when I do an
+`ls'; why can't Dvips find it?"), it is not in any of the default
+search paths.
+
+
+File: kpathsea.info, Node: Filename aliases, Next: Database format, Prev: ls-R, Up: Filename database
+
+3.4.2 Filename aliases
+----------------------
+
+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 `longtabl.sty'. But now it's being run on a Unix system,
+and the file has its original name, `longtable.sty'. The file won't be
+found. You need to give the actual file `longtable.sty' an alias
+`longtabl.sty'.
+
+ You can handle this by creating a file `aliases' as a companion to
+the `ls-R' for the hierarchy containing the file in question. (You
+must have an `ls-R' for the alias feature to work.)
+
+ The format of `aliases' is simple: two whitespace-separated words
+per line; the first is the real name `longtable.sty', and second is the
+alias (`longtabl.sty'). These must be base filenames, with no
+directory components. `longtable.sty' must be in the sibling `ls-R'.
+
+ Also, blank lines and lines starting with `%' or `#' are ignored in
+`aliases', to allow for comments.
+
+ If a real file `longtabl.sty' exists, it is used regardless of any
+aliases.
+
+
+File: kpathsea.info, Node: Database format, Prev: Filename aliases, Up: Filename database
+
+3.4.3 Database format
+---------------------
+
+The "database" read by Kpathsea is a line-oriented file of plain text.
+The format is that generated by GNU (and most other) `ls' programs
+given the `-R' option, as follows.
+
+ * Blank lines are ignored.
+
+ * If a line begins with `/' or `./' or `../' and ends with a colon,
+ it's the name of a directory. (`../' lines aren't useful,
+ however, and should not be generated.)
+
+ * All other lines define entries in the most recently seen directory.
+ /'s in such lines will produce possibly-strange results.
+
+ * Files with no preceding directory line are ignored.
+
+ For example, here's the first few lines of `ls-R' (which totals
+about 30K bytes) on my system:
+
+ bibtex
+ dvips
+ fonts
+ ls-R
+ metafont
+ metapost
+ tex
+ web2c
+
+ ./bibtex:
+ bib
+ bst
+ doc
+
+ ./bibtex/bib:
+ asi.bib
+ btxdoc.bib
+ ...
+
+
+File: kpathsea.info, Node: Invoking kpsewhich, Prev: Filename database, Up: Path searching
+
+3.5 `kpsewhich': 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 `find' program to locate files in your TeX hierarchies, perhaps
+in administrative scripts. It is used heavily in the distributed
+`mktex...' scripts.
+
+ Synopsis:
+
+ kpsewhich OPTION... FILENAME...
+
+ The options and filename(s) to look up can be intermixed. Options
+can start with either `-' or `--', 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.
+
+
+File: kpathsea.info, Node: Path searching options, Next: Specially-recognized files, Up: Invoking kpsewhich
+
+3.5.1 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:
+
+`--all'
+ 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).
+
+`--dpi=NUM'
+ Set the resolution to NUM; this only affects `gf' and `pk'
+ lookups. `-D' is a synonym, for compatibility with Dvips.
+ Default is 600.
+
+`--engine=NAME'
+ Set the engine name to 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 (`.fmt'/`.base'/`.mem')
+ are now stored in subdirectories named for the engine (`tex',
+ `pdftex', `xetex', etc.), you must specify an engine name in order
+ to find them. For example, `cont-en.fmt' typically exists for both
+ `pdftex' and `xetex'. With the default path settings, you can use
+ `--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 `/' ends up specifying a normal
+ recursive search along the path where the dumps are stored, namely
+ `$TEXMF/web2c{/$engine,}'.)
+
+`--format=NAME'
+ Set the format for lookup to NAME. By default, the format is
+ guessed from the filename, with `tex' being used if nothing else
+ fits. The recognized filename extensions (including any leading
+ `.') are also allowable NAMEs.
+
+ 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 `--format="dvips config"'. (The
+ quotes are for the sake of the shell.)
+
+ Here's the current list of recognized names and the associated
+ suffixes. *Note Supported file formats::, for more information on
+ each of these.
+
+ The strings in parentheses are abbreviations recognized only by
+ `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.
+
+ 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: .luc .luctex .texluc .lua .luatex .texlua
+ font feature files: .fea
+ cid maps: .cid .cidmap
+ mlbib: .mlbib .bib
+ mlbst: .mlbst .bst
+ clua: .dll .so
+ ris: .ris
+ bltxml: .bltxml
+
+ This option and `--path' are mutually exclusive.
+
+`--interactive'
+ After processing the command line, read additional filenames to
+ look up from standard input.
+
+`--mktex=FILETYPE'
+`--no-mktex=FILETYPE'
+ Turn on or off the `mktex' script associated with FILETYPE. Usual
+ values for FILETYPE are `pk', `mf', `tex', and `tfm'. By default,
+ all are off in Kpsewhich, even if they are enabled for TeX. This
+ option implies setting `--must-exist'. *Note mktex scripts::.
+
+`--mode=STRING'
+ Set the mode name to STRING; this also only affects `gf' and `pk'
+ lookups. No default: any mode will be found. *Note mktex script
+ arguments::.
+
+`--must-exist'
+ Do everything possible to find the files, notably including
+ searching the disk and running the `mktex' scripts. By default,
+ only the `ls-R' database is checked, in the interest of efficiency.
+
+`--path=STRING'
+ Search along the path STRING (colon-separated as usual), instead
+ of guessing the search path from the filename. `//' and all the
+ usual expansions are supported (*note Path expansion::). This
+ option and `--format' are mutually exclusive. To output the
+ complete directory expansion of a path, instead of doing a
+ one-shot lookup, see `--expand-path' and `--show-path' in the
+ following section.
+
+`--progname=NAME'
+ Set the program name to NAME; default is `kpsewhich'. This can
+ affect the search paths via the `.PROGNAM' feature in
+ configuration files (*note Config files::).
+
+`--safe-in-name=NAME'
+`--safe-out-name=NAME'
+ Exit successfully if NAME is safe to open for reading or writing,
+ respectively, else unsuccessfully. No output is written. These
+ tests take account of the related Kpathsea configuration settings
+ (*note Calling sequence::).
+
+`--subdir=STRING'
+ Report only those matches whose directory part _ends_ with STRING
+ (compared literally, except case is ignored on a case-insensitive
+ operating system). For example, suppose there are two matches for
+ a given name:
+
+ kpsewhich foo.sty
+ => /some/where/foo.sty
+ /another/place/foo.sty
+
+ Then we can narrow the result to what we are interested in with
+ `--subdir':
+
+ kpsewhich --subdir=where foo.sty
+ => /some/where/foo.sty
+
+ kpsewhich --subdir=place foo.sty
+ => /another/place/foo.sty
+
+ 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:
+
+ kpsewhich --subdir=another foo.sty
+ =>
+
+ The string to match may cross directory components:
+
+ kpsewhich --subdir=some/where foo.sty
+ => /some/where/foo.sty
+
+ `--subdir' implies `--all'; if there is more than one match, they
+ will all be reported (in our example, both `where' and `place' end
+ in `e'):
+
+ kpsewhich --subdir=e
+ => /some/where/foo.sty
+ /another/place/foo.sty
+
+ Because of the above rules, the presence of a leading `/' is
+ important, since it "anchors" the match to a full component name:
+
+ kpsewhich --subdir=/lace foo.sty
+ =>
+
+ However, a trailing `/' is immaterial (and ignored), since the
+ match always takes place at the end of the directory part:
+
+ kpsewhich --subdir=lace/ foo.sty
+ => /another/place/foo.sty
+
+ 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 `foo.lua' might exist within both
+ `texmf-dist/scripts/pkg1/' and `texmf-dist/scripts/pkg2/'. By
+ specifying, say, `--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 `/some/coincidental/pkg1/path/', and we wouldn't want to match
+ `texmf-dist/scripts/pkg2/' that when searching for `/pkg1'.
+
+
+
+File: kpathsea.info, Node: Specially-recognized files, Next: Auxiliary tasks, Prev: Path searching options, Up: Invoking kpsewhich
+
+3.5.2 Specially-recognized files for `kpsewhich'
+------------------------------------------------
+
+`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
+`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 `kpsewhich', along with
+their corresponding format:
+
+`config.ps'
+ `dvips config'
+
+`dvipdfmx.cfg'
+ `other text files'
+
+`fmtutil.cnf'
+ `web2c files'
+
+`glyphlist.txt'
+ `map'
+
+`mktex.cnf'
+ `web2c files'
+
+`pdfglyphlist.txt'
+ `map'
+
+`pdftex.cfg'
+ `pdftex config' (although `pdftex.cfg' is not used any more; look
+ for the file `pdftexconfig.tex' instead.)
+
+`texmf.cnf'
+ `cnf'
+
+`XDvi'
+ `other text files'
+
+
+ A user-specified format will override the above defaults.
+
+ Another useful configuration file in this regard is `tcfmgr.map',
+found in `texmf/texconfig/tcfmgr.map', which records various
+information about the above configuration files (among others).
+
+
+File: kpathsea.info, Node: Auxiliary tasks, Next: Standard options, Prev: Specially-recognized files, Up: Invoking kpsewhich
+
+3.5.3 Auxiliary tasks
+---------------------
+
+Kpsewhich provides some additional features not strictly related to path
+lookup:
+
+ * `--debug=NUM' sets the debugging options to NUM. *Note
+ Debugging::.
+
+ * `--var-value=VARIABLE' outputs the value of VARIABLE, expanding
+ `$' (*note Variable expansion:: and `~' (*note Tilde expansion::)
+ constructs, but not performing other expansions.
+
+ * `--expand-braces=STRING' outputs the variable and brace expansion
+ of STRING. *Note Path expansion::.
+
+ * `--expand-var=STRING' outputs the variable and tilde expansion of
+ STRING. For example, the `mktex...' scripts run `kpsewhich
+ --expand-var='$TEXMF'' to find the root of the TeX system
+ hierarchy. *Note Path expansion::.
+
+ * `--expand-path=STRING' outputs the complete expansion of STRING,
+ with each element separated by the usual path separator on the
+ current system (`;' on Windows, `:' otherwise). This may be
+ useful to construct a custom search path for a format not
+ otherwise supported. To retrieve the search path for a format
+ that is already supported, see `--show-path', next.
+
+ Nonexistent directories are culled from the output:
+
+ $ kpsewhich --expand-path '/tmp'
+ => /tmp
+ $ kpsewhich --expand-path '/nonesuch'
+ =>
+
+ For one-shot uses of an arbitrary (not built in to Kpathsea) path,
+ see `--path' in the previous section.
+
+ * `--show-path=NAME' shows the path that would be used for file
+ lookups of file type NAME. Either a filename extension (`pk',
+ `.vf', etc.) or an integer can be used, just as with `--format',
+ described in the previous section.
+
+
+
+File: kpathsea.info, Node: Standard options, Prev: Auxiliary tasks, Up: Invoking kpsewhich
+
+3.5.4 Standard options
+----------------------
+
+Kpsewhich accepts the standard GNU options:
+
+ * `--help' prints a help message on standard output and exits
+ successfully.
+
+ * `--version' prints the Kpathsea version number and exits
+ successfully.
+
+
+File: kpathsea.info, Node: TeX support, Next: Programming, Prev: Path searching, Up: Top
+
+4 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 conTeXt (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 `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.
+
+
+File: kpathsea.info, Node: Supported file formats, Next: File lookup, Up: TeX support
+
+4.1 Supported file formats
+==========================
+
+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.
+
+ Since environment variables containing periods, such as
+`TEXINPUTS.latex', are not allowed on some systems, Kpathsea looks for
+environment variables with an underscore, e.g., `TEXINPUTS_latex'
+(*note Config files::).
+
+ The following table lists the above information.
+
+`afm'
+ (Adobe font metrics, *note Metric files: (dvips)Metric files.)
+ `AFMFONTS'; suffix `.afm'.
+
+`base'
+ (Metafont memory dump, *note Memory dumps: (web2c)Memory dumps.)
+ `MFBASES', `TEXMFINI'; suffix `.base'.
+
+`bib'
+ (BibTeX bibliography source, *note bibtex invocation:
+ (web2c)bibtex invocation.) `BIBINPUTS', `TEXBIB'; suffix `.bib'.
+
+`bst'
+ (BibTeX style, *note Basic BibTeX style files: (web2c)Basic BibTeX
+ style files.) `BSTINPUTS'; suffix `.bst'.
+
+`cmap'
+ (character map files) `CMAPFONTS'; suffix `.cmap'.
+
+`cnf'
+ (Runtime configuration files, *note Config files::) `TEXMFCNF';
+ suffix `.cnf'.
+
+`cweb'
+ (CWEB input files) `CWEBINPUTS'; suffixes `.w', `.web'; additional
+ suffix `.ch'.
+
+`dvips config'
+ (Dvips `config.*' files, such as `config.ps', *note Config files:
+ (dvips)Config files.) `TEXCONFIG'.
+
+`enc files'
+ (encoding vectors) `ENCFONTS'; suffix `.enc'.
+
+`fmt'
+ (TeX memory dump, *note Memory dumps: (web2c)Memory dumps.)
+ `TEXFORMATS', `TEXMFINI'; suffix `.fmt'.
+
+`font cid map'
+ (CJK mapping) `FONTCIDMAPS' suffix `.cid'.
+
+`font feature files'
+ (primarily for OpenType font features) `FONTFEATURES' suffix
+ `.fea'.
+
+`gf'
+ (generic font bitmap, *note Glyph files: (dvips)Glyph files.)
+ `PROGRAMFONTS', `GFFONTS', `GLYPHFONTS', `TEXFONTS'; suffix `gf'.
+
+`graphic/figure'
+ (Encapsulated PostScript figures, *note PostScript figures:
+ (dvips)PostScript figures.) `TEXPICTS', `TEXINPUTS'; additional
+ suffixes: `.eps', `.epsi'.
+
+`ist'
+ (makeindex style files) `TEXINDEXSTYLE', `INDEXSTYLE'; suffix
+ `.ist'.
+
+`lig files'
+ (ligature definition files) `LIGFONTS'; suffix `.lig'.
+
+`ls-R'
+ (Filename databases, *note Filename database::) `TEXMFDBS'.
+
+`map'
+ (Fontmaps, *note Fontmap::) `TEXFONTMAPS'; suffix `.map'.
+
+`mem'
+ (MetaPost memory dump, *note Memory dumps: (web2c)Memory dumps.)
+ `MPMEMS', `TEXMFINI'; suffix `.mem'.
+
+`MetaPost support'
+ (MetaPost support files, used by DMP; *note dmp invocation:
+ (web2c)dmp invocation.) `MPSUPPORT'.
+
+`mf'
+ (Metafont source, *note mf invocation: (web2c)mf invocation.)
+ `MFINPUTS'; suffix `.mf'; dynamic creation program: `mktexmf'.
+
+`mfpool'
+ (Metafont program strings, *note pooltype invocation:
+ (web2c)pooltype invocation.) `MFPOOL', `TEXMFINI'; suffix `.pool'.
+
+`mft'
+ (`MFT' style file, *note mft invocation: (web2c)mft invocation.)
+ `MFTINPUTS'; suffix `.mft'.
+
+`misc fonts'
+ (font-related files that don't fit the other categories)
+ `MISCFONTS'
+
+`mlbib'
+ (MlBibTeX bibliography source) `MLBIBINPUTS', `BIBINPUTS',
+ `TEXBIB'; suffixes `.mlbib', `.mlbib'.
+
+`mlbst'
+ (MlBibTeX style) `MLBSTINPUTS', `BSTINPUTS'; suffixes `.mlbst',
+ `.bst'.
+
+`mp'
+ (MetaPost source, *note mpost invocation: (web2c)mpost invocation.)
+ `MPINPUTS'; suffix `.mp'.
+
+`mppool'
+ (MetaPost program strings, *note pooltype invocation:
+ (web2c)pooltype invocation.) `MPPOOL', `TEXMFINI'; suffix `.pool'.
+
+`ocp'
+ (Omega compiled process files) `OCPINPUTS';
+ suffix `.ocp'; dynamic creation program: `MakeOmegaOCP'.
+
+`ofm'
+ (Omega font metrics) `OFMFONTS', `TEXFONTS';
+ suffixes `.ofm', `.tfm'; dynamic creation program: `MakeOmegaOFM'.
+
+`opentype fonts'
+ (OpenType fonts) `OPENTYPEFONTS'.
+
+`opl'
+ (Omega property lists) `OPLFONTS', `TEXFONTS'; suffix `.opl'.
+
+`otp'
+ (Omega translation process files) `OTPINPUTS'; suffix `.otp'.
+
+`ovf'
+ (Omega virtual fonts) `OVFFONTS', `TEXFONTS'; suffix `.ovf'.
+
+`ovp'
+ (Omega virtual property lists) `OVPFONTS', `TEXFONTS'; suffix
+ `.ovp'.
+
+`pdftex config'
+ (PDFTeX-specific configuration files) `PDFTEXCONFIG'.
+
+`pk'
+ (packed bitmap fonts, *note Glyph files: (dvips)Glyph files.)
+ `PROGRAMFONTS' (PROGRAM being `XDVI', etc.), `PKFONTS', `TEXPKS',
+ `GLYPHFONTS', `TEXFONTS'; suffix `pk'; dynamic creation program:
+ `mktexpk'.
+
+`PostScript header'
+ (downloadable PostScript, *note Header files: (dvips)Header files.)
+ `TEXPSHEADERS', `PSHEADERS'; additional suffix `.pro'.
+
+`subfont definition files'
+ (subfont definition files) `SFDFONTS' suffix `.sfd'.
+
+`tex'
+ (TeX source, *note tex invocation: (web2c)tex invocation.)
+ `TEXINPUTS'; suffix `.tex'; additional suffixes: none, because
+ such a list cannot be complete; dynamic creation program:
+ `mktextex'.
+
+`TeX system documentation'
+ (Documentation files for the TeX system) `TEXDOCS'.
+
+`TeX system sources'
+ (Source files for the TeX system) `TEXSOURCES'.
+
+`texmfscripts'
+ (Architecture-independent executables distributed in the texmf
+ trees) `TEXMFSCRIPTS'.
+
+`texpool'
+ (TeX program strings, *note pooltype invocation: (web2c)pooltype
+ invocation.) `TEXPOOL', `TEXMFINI'; suffix `.pool'.
+
+`tfm'
+ (TeX font metrics, *note Metric files: (dvips)Metric files.)
+ `TFMFONTS', `TEXFONTS'; suffix `.tfm'; dynamic creation program:
+ `mktextfm'.
+
+`Troff fonts'
+ (Troff fonts, used by DMP; *note DMP invocation: (web2c)DMP
+ invocation.) `TRFONTS'.
+
+`truetype fonts'
+ (TrueType outline fonts) `TTFONTS'; suffixes `.ttf' and `.TTF',
+ `.ttc' and `.TTC', `.dfont'.
+
+`type1 fonts'
+ (Type 1 PostScript outline fonts, *note Glyph files: (dvips)Glyph
+ files.) `T1FONTS', `T1INPUTS', `TEXPSHEADERS', `DVIPSHEADERS';
+ suffixes `.pfa', `.pfb'.
+
+`type42 fonts'
+ (Type 42 PostScript outline fonts) `T42FONTS'.
+
+`vf'
+ (virtual fonts, *note Virtual fonts: (dvips)Virtual fonts.)
+ `VFFONTS', `TEXFONTS'; suffix `.vf'.
+
+`web'
+ (WEB input files) `WEBINPUTS'; suffix `.web'; additional suffix
+ `.ch'.
+
+`web2c files'
+ (files specific to the web2c implementation) `WEB2C'.
+
+ 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 `INPUTS'. Assuming the program is called `foo', this gives
+us the following table.
+
+`other text files'
+ (text files used by `foo') `FOOINPUTS'.
+
+`other binary files'
+ (binary files used by `foo') `FOOINPUTS'.
+
+ If an environment variable by these names are set, the corresponding
+`texmf.cnf' definition won't be looked at (unless, as usual, the
+environment variable value has an extra `:'). *Note Default
+expansion::.
+
+ For the font variables, the intent is that:
+ * `TEXFONTS' is the default for everything.
+
+ * `GLYPHFONTS' is the default for bitmap (or, more precisely,
+ non-metric) files.
+
+ * Each font format has a variable of its own.
+
+ * Each program has its own font override path as well; e.g.,
+ `DVIPSFONTS' for Dvipsk. Again, this is for bitmaps, not metrics.
+
+
+
+File: kpathsea.info, Node: File lookup, Next: Glyph lookup, Prev: Supported file formats, Up: TeX support
+
+4.2 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 NAME:
+
+ 1. If the file format defines default suffixes, and the suffix of
+ 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 `foo.bar', look for
+ `foo.bar.tex'.
+
+ 2. Search for NAME, and if necessary for alternative names found in
+ the fontmaps. Example: given `foo.bar', we also look for
+ `foo.bar'.
+
+ 3. If the file format defines a program to invoke to create missing
+ files, run it (*note mktex scripts::).
+
+ The order in which we search for "suffixed" name (item 1) or the
+"as-is" name (item 2) is controlled by the `try_std_extension_first'
+configuration value. The default set in `texmf.cnf' is true, since
+common suffixes are already recognized: `babel.sty' will only look for
+`babel.sty', not `babel.sty.tex', regardless of this setting.
+
+ When the suffix is unknown (e.g., `foo.bar'), both names are always
+tried; the difference is the order in which they are tried.
+
+ `try_std_extension_first' only affects names being looked up which
+*already* have an extension. A name without an extension (e.g., `tex
+story') will always have an extension added first.
+
+ This algorithm is implemented in the function `kpathsea_find_file'
+in the source file `kpathsea/tex-file.c'. You can watch it in action
+with the debugging options (*note Debugging::).
+
+
+File: kpathsea.info, Node: Glyph lookup, Next: Suppressing warnings, Prev: File lookup, Up: TeX support
+
+4.3 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., `cmr10') and a
+resolution (e.g., 600).
+
+ Here is an outline of the search strategy (details in the sections
+below) for a file NAME at resolution DPI. The search stops at the
+first successful lookup.
+
+ 1. Look for an existing file NAME.DPIFORMAT in the specified
+ format(s).
+
+ 2. If NAME is an alias for a file F in the fontmap file
+ `texfonts.map', look for F.DPI.
+
+ 3. Run an external program (typically named `mktexpk') to generate
+ the font (*note mktex scripts::)
+
+ 4. Look for FALLBACK.DPI, where FALLBACK is some last-resort font
+ (typically `cmr10').
+
+ This is implemented in `kpathsea_find_glyph' in
+`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.
+
+
+File: kpathsea.info, Node: Basic glyph lookup, Next: Fontmap, Up: Glyph lookup
+
+4.3.1 Basic glyph lookup
+------------------------
+
+When Kpathsea looks for a bitmap font NAME at resolution DPI in a
+format FORMAT, it first checks each directory in the search path for a
+file `NAME.DPIFORMAT'; for example, `cmr10.600pk'. Kpathsea looks for
+a PK file first, then a GF file.
+
+ If that fails, Kpathsea looks for `dpiDPI/NAME.FORMAT'; for example,
+`dpi600/cmr10.pk'. This is how fonts are typically stored on
+filesystems (such as DOS) that permit only three-character extensions.
+
+ If that fails, Kpathsea looks for a font with a close-enough DPI.
+"Close enough" is defined by the macro `KPSE_BITMAP_TOLERANCE' in
+`kpathsea/tex-glyph.h' to be `DPI / 500 + 1'. This is slightly more
+than the 0.2% minimum allowed by the DVI standard
+(`CTAN:/dviware/driv-standard/level-0').
+
+
+File: kpathsea.info, Node: Fontmap, Next: Fallback font, Prev: Basic glyph lookup, Up: Glyph lookup
+
+4.3.2 Fontmap
+-------------
+
+If a bitmap font or metric file is not found with the original name (see
+the previous section), Kpathsea looks through any "fontmap" files for
+an "alias" for the original font name. These files are named
+`texfonts.map' and searched for along the `TEXFONTMAPS'
+environment/config file variable. All `texfonts.map' files that are
+found are read; earlier definitions override later ones.
+
+ This feature is intended to help in two respects:
+
+ 1. An alias name is limited in length only by available memory, not
+ by your filesystem. Therefore, if you want to ask for
+ `Times-Roman' instead of `ptmr', you can (you get `ptmr8r').
+
+ 2. A few fonts have historically had multiple names: specifically,
+ LaTeX's "circle font" has variously been known as `circle10',
+ `lcircle10', and `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.
+
+
+ The format of fontmap files is straightforward:
+
+ * Comments start with `%' and continue to the end of the line.
+
+ * Blank lines are ignored.
+
+ * Each nonblank line is broken up into a series of "words": a
+ sequence of non-whitespace characters.
+
+ * If the first word is `include', the second word is used as a
+ filename, and it is searched for and read.
+
+ * Otherwise, the first word on each line is the true filename;
+
+ * the second word is the alias;
+
+ * subsequent words are ignored.
+
+ 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 `foo.tfm' matches only when
+`foo.tfm' is being searched for; but an alias `foo' matches `foo.vf',
+`foo.600pk', etc.
+
+ As an example, here is an excerpt from the `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.
+
+ circle10 lcircle10
+ circle10 lcirc10
+ lcircle10 circle10
+ lcircle10 lcirc10
+ lcirc10 circle10
+ lcirc10 lcircle10
+ ...
+ include adobe.map
+ include apple.map
+ include bitstrea.map
+ ...
+
+ Fontmaps are implemented in the file `kpathsea/fontmap.c'. The
+Fontname distribution has much more information on font naming (*note
+Introduction: (fontname)Introduction.).
+
+
+File: kpathsea.info, Node: Fallback font, Prev: Fontmap, Up: Glyph lookup
+
+4.3.3 Fallback font
+-------------------
+
+If a bitmap font cannot be found or created at the requested size,
+Kpathsea looks for the font at a set of "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.,
+`DVIPSSIZES' for Dvipsk), then the environment variable `TEXSIZES',
+then a default specified at compilation time (the Make variable
+`default_texsizes'). You can set this list to be empty if you prefer
+to find fonts at their stated size or not at all.
+
+ Finally, if the font cannot be found even at the fallback
+resolutions, Kpathsea looks for a fallback font, typically `cmr10'.
+Programs must enable this feature by calling `kpathsea_init_prog'
+(*note Calling sequence::); the default is no fallback font.
+
+
+File: kpathsea.info, Node: Suppressing warnings, Prev: Glyph lookup, Up: TeX support
+
+4.4 Suppressing warnings
+========================
+
+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
+`TEX_HUSH' to a colon-separated list of values. Here are the
+possibilities:
+
+`all'
+ Suppress everything possible.
+
+`checksum'
+ Suppress mismatched font checksum warnings.
+
+`lostchar'
+ Suppress warnings when a character is missing from a font that a
+ DVI or VF file tries to typeset.
+
+`none'
+ Don't suppress any warnings.
+
+`readable'
+ Suppress warnings about attempts to access a file whose permissions
+ render it unreadable.
+
+`special'
+ Suppresses warnings about an unimplemented or unparsable
+ `\special' command.
+
+`tex-hush.c' defines the function that checks the variable value. Each
+driver implements its own checks where appropriate.
+
+
+File: kpathsea.info, Node: Programming, Next: Index, Prev: TeX support, Up: Top
+
+5 Programming
+*************
+
+This chapter is for programmers who wish to use Kpathsea. *Note
+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.
+
+
+File: kpathsea.info, Node: Programming overview, Next: Calling sequence, Up: Programming
+
+5.1 Programming overview
+========================
+
+Aside from this manual, your best source of information is the source
+to the programs that use Kpathsea (*note 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.
+
+ When looking at these program sources, you should know that previous
+versions of the library had a different programming interface, to
+support re-entrancy. In that interface the library function names were
+prefixed with `kpse_' instead of `kpathsea_', and they did not need an
+instance variable as first argument. This change was made in 2009.
+Some of the programs mentioned above may still be using the previous
+interface.
+
+ Beyond these examples, the `.h' files in the Kpathsea source
+describe the interfaces and functionality (and of course the `.c' files
+define the actual routines, which are the ultimate documentation).
+`pathsearch.h' declares the basic searching routine. `tex-file.h' and
+`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 `#include <kpathsea/kpathsea.h>', which includes
+every Kpathsea header.
+
+ If you want to include only specific headers, you should still
+consider including `kpathsea/config.h' before including any other
+Kpathsea header, as it provides symbols used in the other headers.
+Note that `kpathsea/config.h' includes `kpathsea/c-auto.h', which is
+generated by Autoconf.
+
+ The library provides no way for an external program to register new
+file types: `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 `texmf.cnf' (and its descendant `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.
+
+
+File: kpathsea.info, Node: Calling sequence, Next: Program-specific files, Prev: Programming overview, Up: Programming
+
+5.2 Calling sequence
+====================
+
+The typical way to use Kpathsea in your program goes something like
+this:
+
+ 1. Call `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 `kpse' as a
+ placeholder for the name of this variable.
+
+ 2. Call `kpathsea_set_program_name' with `argv[0]' as the second
+ argument; the third argument is a string or `NULL'. The third
+ argument is used by Kpathsea as the program name for the
+ `.PROGRAM' feature of config files (*note Config files::). If the
+ third argument is `NULL', the value of the second argument is
+ used. This function must be called before any other use of the
+ Kpathsea library.
+
+ `kpathsea_set_program_name' always sets the variables
+ `kpse->invocation_name' and `kpse->invocation_short_name'. These
+ variables are used in the error message macros defined in
+ `kpathsea/lib.h'. It sets the variable `kpse->program_name' to
+ the program name it uses.
+
+ It also initializes debugging options based on the environment
+ variable `KPATHSEA_DEBUG' (if that is set).
+
+ Finally, it sets the environment variables `SELFAUTOLOC',
+ `SELFAUTODIR' and `SELFAUTOPARENT' to the location, parent and
+ grandparent directory of the executable, removing `.' and `..' 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 `kpsewhich --expand-var=\$SELFAUTOLOC',
+ etc., to see the values.
+
+ 3. Set debugging options. *Note Debugging::. If your program doesn't
+ have a debugging option already, you can define one and set
+ `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 `KPATHSEA_DEBUG'). If you do have runtime debugging
+ already, you need to merge Kpathsea's options with yours (as in
+ Dvipsk and Xdvik).
+
+ 4. If your program has its own configuration files that can define
+ search paths, you should assign those paths to the `client_path'
+ member in the appropriate element of the `kpse->format_info'
+ array. (This array is indexed by file type; see `tex-file.h'.)
+ See `resident.c' in Dvipsk for an example.
+
+ 5. Call `kpathsea_init_prog' (see `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 BibTeX search paths in a DVI driver.)
+
+ 6. The routine to actually find a file of type FORMAT is
+ `kpathsea_find_file'. You can call `kpathsea_find_file' after
+ doing only the first and second of the initialization steps
+ above--Kpathsea automatically reads the `texmf.cnf' generic config
+ files, looks for environment variables, and does expansions at the
+ first lookup.
+
+ 7. To find PK and/or GF bitmap fonts, the routine is
+ `kpathsea_find_glyph', defined in `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.
+
+ 8. To actually open a file, not just return a filename, call
+ `kpathsea_open_file'. This function takes the name to look up and
+ a Kpathsea file format as arguments, and returns the usual `FILE
+ *'. It always assumes the file must exist, and thus will search
+ the disk if necessary (unless the search path specified `!!',
+ etc.). In other words, if you are looking up a VF or some other
+ file that need not exist, don't use this.
+
+ 9. TeX can write output files, via the `\openout' primitive; this
+ opens a security hole vulnerable to Trojan horse attack: an
+ unwitting user could run a TeX program that overwrites, say,
+ `~/.rhosts'. Analogous security holes exist for many other
+ programs. To alleviate this, there is a configuration variable
+ `openout_any', which selects one of three levels of security.
+ When it is set to `a' (for "any"), no restrictions are imposed.
+ When it is set to `r' (for "restricted"), filenames beginning with
+ `.' are disallowed (except `.tex' because LaTeX needs it). When
+ it is set to `p' (for "paranoid") additional restrictions are
+ imposed: an absolute filename must refer to a file in (a
+ subdirectory) of `TEXMFOUTPUT', and any attempt to go up a
+ directory level is forbidden (that is, paths may not contain a
+ `..' component). The paranoid setting is the default. (For
+ backwards compatibility, `y' and `1' are synonyms of `a', while
+ `n' and `0' are synonyms for `r'.) The function
+ `kpathsea_out_name_ok', with a filename as second argument,
+ returns `true' if that filename is acceptable to be opend for
+ output or `false' otherwise.
+
+ 10. Similarly, the function `kpathsea_in_name_ok', with a filename as
+ second argument, returns `true' if that filename is acceptable to
+ be opend for input or `false' otherwise, depending on the value of
+ the configuration variable `openin_any' (with `a' as default).
+
+ 11. To close the kpathsea library instance you are using, call
+ `kpathsea_finish'. This function closes any open log files and
+ frees the memory used by the instance.
+
+
+ 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, `stat'
+calls, etc. (Perhaps someday I'll move the former to a separate
+library.)
+
+ The `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 `ftp://ftp.gnu.og/pub/gnu/'.
+
+
+File: kpathsea.info, Node: Program-specific files, Next: Programming with config files, Prev: Calling sequence, Up: Programming
+
+5.3 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 (*note Introduction:
+(tds)Top.), specifies that such files should go into a subdirectory
+named after the program, like `texmf/ttf2pk'.
+
+ Two formats, `kpse_program_text_format' and
+`kpse_program_binary_format', use `.:$TEXMF/PROGRAM//' as their
+compiled-in search path. To override this default, you can use the
+variable `PROGRAMINPUTS' in the environment and/or `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 `INPUTS'.
+
+ The only difference between these two formats is whether
+`kpathsea_open_file' will open the files it finds in text or binary
+mode.
+
+
+File: kpathsea.info, Node: Programming with config files, Prev: Program-specific files, Up: Programming
+
+5.4 Programming with config files
+=================================
+
+You can (and probably should) use the same `texmf.cnf' configuration
+file that Kpathsea uses for your program. This helps installers by
+keeping all configuration in one place.
+
+ To retrieve a value VAR from config files, the best way is to call
+`kpathsea_var_value' on the string `VAR'. This will look first for an
+environment variable VAR, then a config file value. The result will be
+the value found or `NULL'. This function is declared in
+`kpathsea/variable.h'. For an example, see the `shell_escape' code in
+`web2c/lib/texmfmp.c'.
+
+ The routine to do variable expansion in the context of a search path
+(as opposed to simply retrieving a value) is `kpathsea_var_expand', also
+declared in `kpathsea/variable.h'. It's generally only necessary to
+set the search path structure components as explained in the previous
+section, rather than using this yourself.
+
+ If for some reason you want to retrieve a value _only_ from a config
+file, not automatically looking for a corresponding environment
+variable, call `kpathsea_cnf_get' (declared in `kpathsea/cnf.h') with
+the string VAR.
+
+ No initialization calls are needed.
+
+
+File: kpathsea.info, Node: Index, Prev: Programming, Up: Top
+
+Index
+*****
+
+
+* Menu:
+
+* !! in path specifications: ls-R. (line 52)
+* $ expansion: Variable expansion. (line 6)
+* --all: Path searching options.
+ (line 12)
+* --color=tty: ls-R. (line 21)
+* --debug=NUM: Auxiliary tasks. (line 9)
+* --disable-static: configure options. (line 31)
+* --dpi=NUM: Path searching options.
+ (line 17)
+* --enable options: configure options. (line 16)
+* --enable-maintainer-mode: configure options. (line 34)
+* --enable-shared <1>: Shared library. (line 6)
+* --enable-shared: configure options. (line 27)
+* --engine=NAME: Path searching options.
+ (line 22)
+* --expand-braces=STRING: Auxiliary tasks. (line 16)
+* --expand-path=STRING: Auxiliary tasks. (line 24)
+* --expand-var=STRING: Auxiliary tasks. (line 19)
+* --format=NAME: Path searching options.
+ (line 38)
+* --help: Standard options. (line 8)
+* --interactive: Path searching options.
+ (line 120)
+* --mktex=FILETYPE: Path searching options.
+ (line 125)
+* --mode=STRING: Path searching options.
+ (line 131)
+* --must-exist: Path searching options.
+ (line 136)
+* --no-mktex=FILETYPE: Path searching options.
+ (line 125)
+* --path=STRING: Path searching options.
+ (line 141)
+* --progname=NAME: Path searching options.
+ (line 150)
+* --safe-in-name=NAME: Path searching options.
+ (line 156)
+* --safe-out-name=NAME: Path searching options.
+ (line 156)
+* --show-path=NAME: Auxiliary tasks. (line 41)
+* --srcdir, for building multiple architectures: configure scenarios.
+ (line 18)
+* --subdir=STRING: Path searching options.
+ (line 162)
+* --var-value=VARIABLE: Auxiliary tasks. (line 12)
+* --version: Standard options. (line 11)
+* --with options: configure options. (line 16)
+* --with-mktextex-default: mktex configuration. (line 12)
+* --without-mktexfmt-default: mktex configuration. (line 12)
+* --without-mktexmf-default: mktex configuration. (line 12)
+* --without-mktexocp-default: mktex configuration. (line 12)
+* --without-mktexofm-default: mktex configuration. (line 12)
+* --without-mktexpk-default: mktex configuration. (line 12)
+* --without-mktextfm-default: mktex configuration. (line 12)
+* -1 debugging value: Debugging. (line 23)
+* -A option to ls: ls-R. (line 33)
+* -Bdynamic: ShellWidgetClass. (line 45)
+* -Bstatic: ShellWidgetClass. (line 45)
+* -D NUM: Path searching options.
+ (line 17)
+* -dynamic: ShellWidgetClass. (line 43)
+* -g, compiling without: configure scenarios. (line 32)
+* -L option to ls: ls-R. (line 38)
+* -O, compiling with: configure scenarios. (line 32)
+* -static: ShellWidgetClass. (line 43)
+* . directories, ignored: ls-R. (line 33)
+* . files: ls-R. (line 33)
+* .2602gf: Unable to generate fonts.
+ (line 36)
+* .afm: Supported file formats.
+ (line 20)
+* .base: Supported file formats.
+ (line 24)
+* .bib: Supported file formats.
+ (line 28)
+* .bst: Supported file formats.
+ (line 32)
+* .cid: Supported file formats.
+ (line 58)
+* .cmap: Supported file formats.
+ (line 36)
+* .cnf: Supported file formats.
+ (line 39)
+* .enc: Supported file formats.
+ (line 51)
+* .eps: Supported file formats.
+ (line 69)
+* .epsi: Supported file formats.
+ (line 69)
+* .fea: Supported file formats.
+ (line 61)
+* .fmt: Supported file formats.
+ (line 54)
+* .ist: Supported file formats.
+ (line 74)
+* .lig: Supported file formats.
+ (line 78)
+* .map: Supported file formats.
+ (line 84)
+* .mem: Supported file formats.
+ (line 87)
+* .mf: Supported file formats.
+ (line 95)
+* .mft: Supported file formats.
+ (line 103)
+* .mlbib: Supported file formats.
+ (line 111)
+* .mlbst: Supported file formats.
+ (line 115)
+* .mp: Supported file formats.
+ (line 119)
+* .ocp: Supported file formats.
+ (line 127)
+* .ofm: Supported file formats.
+ (line 131)
+* .opl: Supported file formats.
+ (line 138)
+* .otp: Supported file formats.
+ (line 141)
+* .ovf: Supported file formats.
+ (line 144)
+* .ovp: Supported file formats.
+ (line 147)
+* .pfa: Supported file formats.
+ (line 200)
+* .pfb: Supported file formats.
+ (line 200)
+* .pk: Supported file formats.
+ (line 154)
+* .pool: Supported file formats.
+ (line 99)
+* .pro: Supported file formats.
+ (line 160)
+* .rhosts, writable by TeX: Security. (line 10)
+* .sfd: Supported file formats.
+ (line 164)
+* .tex: Supported file formats.
+ (line 167)
+* .tex file, included in ls-R: ls-R. (line 33)
+* .tfm: Supported file formats.
+ (line 187)
+* .ttc: Supported file formats.
+ (line 196)
+* .ttf: Supported file formats.
+ (line 196)
+* .vf: Supported file formats.
+ (line 208)
+* .w: Supported file formats.
+ (line 43)
+* .web: Supported file formats.
+ (line 43)
+* / may not be /: Searching overview. (line 13)
+* /, trailing in home directory: Tilde expansion. (line 19)
+* //: Subdirectory expansion.
+ (line 6)
+* /afs/... , installing into: Installing files. (line 32)
+* /etc/profile: Unable to find files.
+ (line 14)
+* /etc/profile and aliases: ls-R. (line 21)
+* /var/tmp/texfonts: mktex configuration. (line 114)
+* 2602gf: Unable to generate fonts.
+ (line 36)
+* 8.3 filenames, using: mktex configuration. (line 69)
+* : may not be :: Searching overview. (line 13)
+* :: expansion: Default expansion. (line 6)
+* @VAR@ substitutions: Running configure. (line 6)
+* \, line continuation in texmf.cnf: Config files. (line 37)
+* \openin: Searching overview. (line 31)
+* \special, suppressing warnings about: Suppressing warnings.
+ (line 31)
+* absolute filenames: Searching overview. (line 52)
+* ac_include, Autoconf extension: Running configure. (line 6)
+* access warnings: Searching overview. (line 56)
+* AFMFONTS: Supported file formats.
+ (line 20)
+* AFS: Installing files. (line 32)
+* AIX 4.1 configure error: Empty Makefiles. (line 6)
+* AIX shells and configure: configure shells. (line 14)
+* aliases for fonts: Fontmap. (line 6)
+* aliases, for filenames: Filename aliases. (line 6)
+* all: Suppressing warnings.
+ (line 13)
+* all matches, finding: Path searching options.
+ (line 12)
+* alphabetical order, not: Subdirectory expansion.
+ (line 6)
+* Amiga support: Custom installation. (line 19)
+* Andrew File System, installing with: Installing files. (line 32)
+* announcement mailing list: Mailing lists. (line 6)
+* ANSI C: TeX or Metafont failing.
+ (line 30)
+* API, re-entrant: Programming overview.
+ (line 16)
+* append-only directories and mktexpk: Security. (line 36)
+* appendonlydir: mktex configuration. (line 61)
+* architecture-(in)dependent files, installing only: Installing files.
+ (line 21)
+* architectures, compiling multiple: configure scenarios. (line 18)
+* arguments to mktex: mktex script arguments.
+ (line 6)
+* argv[0]: Calling sequence. (line 14)
+* ash, losing with configure: configure shells. (line 19)
+* autoconf, recommended: Calling sequence. (line 119)
+* automounter, and configuration: configure scenarios. (line 29)
+* automounter, and ls-R: ls-R. (line 40)
+* auxiliary tasks: Auxiliary tasks. (line 6)
+* Babel <1>: Running make. (line 51)
+* Babel: Kpathsea application distributions.
+ (line 28)
+* Bach, Johann Sebastian: Default expansion. (line 41)
+* backslash-newline: Config files. (line 37)
+* bash, recommended for running configure: configure shells. (line 6)
+* basic glyph lookup: Basic glyph lookup. (line 6)
+* Berry, Karl: History. (line 12)
+* BIBINPUTS: Supported file formats.
+ (line 28)
+* blank lines, in texmf.cnf: Config files. (line 35)
+* brace expansion: Brace expansion. (line 6)
+* BSD universe: Running make. (line 44)
+* bsh, ok with configure: configure shells. (line 14)
+* BSTINPUTS: Supported file formats.
+ (line 32)
+* bug address: Reporting bugs. (line 8)
+* bug checklist: Bug checklist. (line 6)
+* bug mailing list: Mailing lists. (line 6)
+* bugs, reporting: Reporting bugs. (line 6)
+* c-*.h: Calling sequence. (line 119)
+* c-auto.h: Programming overview.
+ (line 33)
+* c-auto.in: Running configure. (line 6)
+* cache of fonts, local: Security. (line 22)
+* calling sequence: Calling sequence. (line 6)
+* CC: configure environment.
+ (line 10)
+* cc warnings: Pointer combination warnings.
+ (line 6)
+* cc, compiling with: configure environment.
+ (line 11)
+* CFLAGS: configure environment.
+ (line 14)
+* ChangeLog entry: Bug checklist. (line 55)
+* checklist for bug reports: Bug checklist. (line 6)
+* checksum: Suppressing warnings.
+ (line 16)
+* circle fonts: Fontmap. (line 19)
+* clean Make target: Cleaning up. (line 15)
+* client_path in kpse->format_info: Calling sequence. (line 47)
+* CMAPFONTS: Supported file formats.
+ (line 36)
+* cmr10, as fallback font: Fallback font. (line 15)
+* cmr10.vf: Searching overview. (line 31)
+* cnf.c: Config files. (line 86)
+* cnf.h: Programming with config files.
+ (line 23)
+* code sharing: Shared library. (line 9)
+* color printers, configuring: Simple installation. (line 60)
+* comments, in fontmap files: Fontmap. (line 28)
+* comments, in texmf.cnf: Config files. (line 27)
+* comments, making: Introduction. (line 27)
+* common features in glyph lookup: Basic glyph lookup. (line 6)
+* common problems: Common problems. (line 6)
+* comp.sys.sun.admin FAQ: ShellWidgetClass. (line 6)
+* comp.text.tex: Mailing lists. (line 25)
+* compilation: Installation. (line 6)
+* compilation value, source for path: Path sources. (line 20)
+* compiler bugs: TeX or Metafont failing.
+ (line 6)
+* compiler bugs, finding: TeX or Metafont failing.
+ (line 24)
+* compiler options, additional: Running make. (line 27)
+* compiler options, specifying: configure environment.
+ (line 15)
+* compiler, changing: Running make. (line 40)
+* compiling on HP-UX: TeX or Metafont failing.
+ (line 30)
+* conditions for use: Introduction. (line 31)
+* config files: Config files. (line 6)
+* config files, for Kpathsea-using programs: Calling sequence.
+ (line 47)
+* config files, programming with: Programming with config files.
+ (line 6)
+* config.h: Programming overview.
+ (line 33)
+* config.log: Bug checklist. (line 27)
+* config.ps: Specially-recognized files.
+ (line 16)
+* config.ps, search path for: Supported file formats.
+ (line 47)
+* config.status: Bug checklist. (line 30)
+* configuration: Installation. (line 6)
+* configuration bugs: Bug checklist. (line 30)
+* configuration compiler options: configure environment.
+ (line 23)
+* configuration file, source for path: Path sources. (line 17)
+* configuration files as shell scripts.: Config files. (line 79)
+* configuration of mktex scripts: mktex configuration. (line 6)
+* configuration of optional features: configure options. (line 16)
+* configure error from sed: Empty Makefiles. (line 6)
+* configure options: configure options. (line 6)
+* configure options for mktex scripts: mktex configuration. (line 12)
+* configure, running: Running configure. (line 6)
+* context diff: Bug checklist. (line 55)
+* continuation character: Config files. (line 37)
+* core dumps, reporting: Bug checklist. (line 61)
+* CPPFLAGS: configure environment.
+ (line 22)
+* crashes, reporting: Bug checklist. (line 61)
+* custom installation: Custom installation. (line 6)
+* CWEBINPUTS: Supported file formats.
+ (line 43)
+* database search: Searching overview. (line 17)
+* database, for filenames: Filename database. (line 6)
+* database, format of: Database format. (line 6)
+* debug.h: Debugging. (line 6)
+* debugger: Bug checklist. (line 61)
+* debugging: Debugging. (line 6)
+* debugging options, in Kpathsea-using program: Calling sequence.
+ (line 39)
+* debugging output: Debugging. (line 27)
+* debugging with -g, disabling: configure scenarios. (line 32)
+* DEC shells and configure: configure shells. (line 25)
+* default expansion: Default expansion. (line 6)
+* default path features: Default path features.
+ (line 6)
+* default paths, changing: Default path generation.
+ (line 6)
+* default paths, how they're made: Default path generation.
+ (line 12)
+* default_texsizes: Fallback font. (line 6)
+* DEFS: configure environment.
+ (line 31)
+* depot: configure scenarios. (line 29)
+* device, wrong: Unable to generate fonts.
+ (line 29)
+* directories, changing default installation: Default path generation.
+ (line 6)
+* directories, making append-only: mktex configuration. (line 62)
+* directory permissions: Security. (line 51)
+* directory structure, for TeX files: TeX directory structure.
+ (line 6)
+* disabling mktex scripts: mktex configuration. (line 6)
+* disk search: Searching overview. (line 22)
+* disk searching, avoiding: ls-R. (line 52)
+* disk space, needed: Disk space. (line 6)
+* disk usage, reducing: Logging. (line 6)
+* distclean Make target: Cleaning up. (line 6)
+* distributions, compiling simultaneously: Kpathsea application distributions.
+ (line 6)
+* distributions, not compiling: Kpathsea application distributions.
+ (line 6)
+* dlclose: dlopen. (line 6)
+* dlopen: dlopen. (line 6)
+* dlsym: dlopen. (line 6)
+* dlsym.c: dlopen. (line 21)
+* doc files: Supported file formats.
+ (line 173)
+* DOS compatible names: mktex configuration. (line 69)
+* DOS support: Custom installation. (line 19)
+* dosnames: mktex configuration. (line 68)
+* dot files: ls-R. (line 33)
+* doubled colons: Default expansion. (line 6)
+* dpiNNN directories: mktex configuration. (line 69)
+* DVI drivers: Kpathsea application distributions.
+ (line 12)
+* DVILJMAKEPK: mktex script names. (line 32)
+* DVILJSIZES: Fallback font. (line 6)
+* dvipdfmx.cfg: Specially-recognized files.
+ (line 19)
+* DVIPSFONTS: Supported file formats.
+ (line 243)
+* DVIPSHEADERS: Supported file formats.
+ (line 200)
+* DVIPSMAKEPK: mktex script names. (line 32)
+* DVIPSSIZES: Fallback font. (line 6)
+* dynamic creation of files: mktex scripts. (line 6)
+* dynamic linking problems with OpenWin libraries: ShellWidgetClass.
+ (line 6)
+* EC fonts, and dynamic source creation: mktex scripts. (line 6)
+* elt-dirs.c: Subdirectory expansion.
+ (line 41)
+* enabling mktex scripts: mktex configuration. (line 6)
+* ENCFONTS: Supported file formats.
+ (line 51)
+* engine name: Path searching options.
+ (line 22)
+* environment variable, source for path: Path sources. (line 9)
+* environment variables for TeX: Supported file formats.
+ (line 6)
+* environment variables in paths: Variable expansion. (line 6)
+* environment variables, old: Unable to find files.
+ (line 14)
+* epoch, seconds since: Logging. (line 15)
+* error message macros: Calling sequence. (line 22)
+* excessive startup time: Slow path searching. (line 6)
+* expand.c: Brace expansion. (line 26)
+* expanding symlinks: Calling sequence. (line 31)
+* expansion, default: Default expansion. (line 6)
+* expansion, path element: Searching overview. (line 43)
+* expansion, search path: Path expansion. (line 6)
+* expansion, subdirectory: Subdirectory expansion.
+ (line 6)
+* expansion, tilde: Tilde expansion. (line 6)
+* expansion, variable: Variable expansion. (line 6)
+* explicitly relative filenames: Searching overview. (line 52)
+* extensions, filename: File lookup. (line 24)
+* externally-built filename database: Filename database. (line 6)
+* extra colons: Default expansion. (line 6)
+* extraclean Make target: Cleaning up. (line 23)
+* failed mktex... script invocation: mktex script names. (line 35)
+* fallback font: Fallback font. (line 6)
+* fallback resolutions: Fallback font. (line 6)
+* fallback resolutions, overriding: Running make. (line 10)
+* FAQ, comp.sys.sun.admin: ShellWidgetClass. (line 6)
+* FAQ, Kpathsea: Common problems. (line 6)
+* Farwell, Matthew: Subdirectory expansion.
+ (line 22)
+* features, of default paths: Default path features.
+ (line 6)
+* file formats, supported: Supported file formats.
+ (line 6)
+* file lookup: File lookup. (line 6)
+* file permissions: Security. (line 47)
+* file types, registering new: Programming overview.
+ (line 39)
+* filename aliases: Filename aliases. (line 6)
+* filename database: Filename database. (line 6)
+* filename database generation: Filename database generation.
+ (line 6)
+* filenames, absolute or explicitly relative: Searching overview.
+ (line 52)
+* files, unable to find: Unable to find files.
+ (line 6)
+* filesystem search: Searching overview. (line 22)
+* floating directories: Searching overview. (line 22)
+* fmtutil: mktex script names. (line 10)
+* fmtutil.cnf: Specially-recognized files.
+ (line 22)
+* fmtutils.cnf: mktex configuration. (line 24)
+* font alias files: Fontmap. (line 6)
+* font generation failures: Unable to generate fonts.
+ (line 6)
+* font of last resort: Fallback font. (line 6)
+* font set, infinite: mktex scripts. (line 6)
+* FONTCIDMAPS: Supported file formats.
+ (line 58)
+* FONTFEATURES: Supported file formats.
+ (line 61)
+* fontmap files: Fontmap. (line 6)
+* fontmaps: mktex configuration. (line 87)
+* fontname: mktex configuration. (line 88)
+* fontnames, arbitrary length: Fontmap. (line 15)
+* fonts, being created: Simple installation. (line 79)
+* FOOINPUTS: Supported file formats.
+ (line 225)
+* fopen, redefined: Debugging. (line 54)
+* format of external database: Database format. (line 6)
+* FreeBSD configure error: Empty Makefiles. (line 6)
+* FreeBSD shells and configure: configure shells. (line 19)
+* ftp.cs.stanford.edu: unixtex.ftp. (line 20)
+* ftp.tug.org: unixtex.ftp. (line 6)
+* fundamental purpose of Kpathsea: Introduction. (line 6)
+* gcc, compiling with: configure environment.
+ (line 11)
+* gdb, recommended: Bug checklist. (line 61)
+* generation of filename database: Filename database generation.
+ (line 6)
+* get_applicationShellWidgetClass: ShellWidgetClass. (line 6)
+* get_wmShellWidgetClass: ShellWidgetClass. (line 6)
+* gf: Supported file formats.
+ (line 65)
+* GFFONTS: Supported file formats.
+ (line 65)
+* globally writable directories: Security. (line 30)
+* glyph lookup: Glyph lookup. (line 6)
+* glyph lookup bitmap tolerance: Basic glyph lookup. (line 15)
+* GLYPHFONTS: Supported file formats.
+ (line 65)
+* glyphlist.txt: Specially-recognized files.
+ (line 25)
+* GNU C compiler bugs: TeX or Metafont failing.
+ (line 19)
+* GNU General Public License: Introduction. (line 31)
+* group-writable directories: Security. (line 40)
+* GSFTOPK_DEBUG (128): Debugging. (line 88)
+* hash table buckets, printing: Debugging. (line 105)
+* hash table routines: Calling sequence. (line 112)
+* hash_summary_only variable for debugging: Debugging. (line 105)
+* help, mailing list for general TeX: Mailing lists. (line 25)
+* history of Kpathsea: History. (line 6)
+* home directories in paths: Tilde expansion. (line 6)
+* HOME, as ~ expansion: Tilde expansion. (line 6)
+* HP-UX, compiling on: TeX or Metafont failing.
+ (line 30)
+* identifiers, characters valid in: Config files. (line 47)
+* illegal pointer combination warnings: Pointer combination warnings.
+ (line 6)
+* include fontmap directive: Fontmap. (line 33)
+* INDEXSTYLE: Supported file formats.
+ (line 74)
+* info-tex@shsu.edu: Mailing lists. (line 25)
+* input lines, reading: Calling sequence. (line 112)
+* install-data Make target: Installing files. (line 28)
+* install-exec Make target: Installing files. (line 23)
+* installation: Installation. (line 6)
+* installation testing: Installation testing.
+ (line 6)
+* installation, architecture-(in)dependent files only: Installing files.
+ (line 21)
+* installation, changing default directories: Default path generation.
+ (line 6)
+* installation, customized: Custom installation. (line 6)
+* installation, getting executables instead of: Simple installation.
+ (line 6)
+* installation, simple: Simple installation. (line 6)
+* installing files: Installing files. (line 6)
+* interactive query: Path searching options.
+ (line 120)
+* interface, not frozen: Introduction. (line 27)
+* introduction: Introduction. (line 6)
+* kdebug:: Debugging. (line 105)
+* kdefault.c: Default expansion. (line 48)
+* Knuth, Donald E.: History. (line 6)
+* Knuth, Donald E., archive of programs by: unixtex.ftp. (line 20)
+* Korn shell, losing with configure: configure shells. (line 14)
+* kpathsae_var_value: Programming with config files.
+ (line 10)
+* Kpathsea config file, source for path: Path sources. (line 17)
+* Kpathsea version number: Kpathsea application distributions.
+ (line 6)
+* kpathsea.h: Programming overview.
+ (line 24)
+* kpathsea/README.CONFIGURE: Running configure. (line 15)
+* kpathsea_cnf_get: Programming with config files.
+ (line 23)
+* KPATHSEA_DEBUG <1>: Calling sequence. (line 28)
+* KPATHSEA_DEBUG: Debugging. (line 18)
+* kpathsea_find_file <1>: Calling sequence. (line 62)
+* kpathsea_find_file: File lookup. (line 37)
+* kpathsea_find_glyph: Glyph lookup. (line 26)
+* kpathsea_finish: Calling sequence. (line 107)
+* kpathsea_in_name_ok: Calling sequence. (line 102)
+* kpathsea_init_prog <1>: Calling sequence. (line 53)
+* kpathsea_init_prog: Fallback font. (line 15)
+* kpathsea_new: Calling sequence. (line 9)
+* kpathsea_open_file: Calling sequence. (line 74)
+* kpathsea_out_name_ok: Calling sequence. (line 82)
+* kpathsea_set_program_name: Calling sequence. (line 14)
+* KPATHSEA_WARNING: Config files. (line 18)
+* kpse->debug: Debugging. (line 6)
+* kpse->debug variable: Calling sequence. (line 39)
+* kpse->format_info: Calling sequence. (line 47)
+* kpse->invocation_name: Calling sequence. (line 22)
+* kpse->invocation_short_name: Calling sequence. (line 22)
+* kpse->program_name: Calling sequence. (line 22)
+* KPSE_BITMAP_TOLERANCE: Basic glyph lookup. (line 15)
+* KPSE_DEBUG_EXPAND (16): Debugging. (line 68)
+* KPSE_DEBUG_FOPEN (4): Debugging. (line 53)
+* KPSE_DEBUG_HASH (2): Debugging. (line 46)
+* KPSE_DEBUG_PATHS (8): Debugging. (line 60)
+* KPSE_DEBUG_SEARCH (32): Debugging. (line 74)
+* KPSE_DEBUG_STAT (1): Debugging. (line 38)
+* KPSE_DEBUG_VARS (64): Debugging. (line 83)
+* KPSE_DOT expansion: KPSE_DOT expansion. (line 6)
+* kpse_format_info_type: Debugging. (line 61)
+* kpse_init_prog, and MAKETEX_MODE: Default path features.
+ (line 25)
+* kpsewhich: Invoking kpsewhich. (line 6)
+* Kpsewhich, and debugging: Debugging. (line 31)
+* ksh, losing with configure: configure shells. (line 14)
+* LaserJet drive: Kpathsea application distributions.
+ (line 13)
+* last-resort font: Fallback font. (line 6)
+* LaTeX help mailing list: Mailing lists. (line 25)
+* lcircle10: Fontmap. (line 19)
+* LDFLAGS: configure environment.
+ (line 38)
+* leading colons: Default expansion. (line 6)
+* leaf directories wrongly guessed: Unable to find files.
+ (line 21)
+* leaf directory trick: Subdirectory expansion.
+ (line 22)
+* libdl.a: dlopen. (line 6)
+* libraries, changing: Running make. (line 40)
+* libraries, specifying additional: configure environment.
+ (line 43)
+* LIBS: configure environment.
+ (line 42)
+* libucb, avoiding: Running make. (line 44)
+* license for using the library: Introduction. (line 31)
+* LIGFONTS: Supported file formats.
+ (line 78)
+* lines, reading arbitrary-length: Calling sequence. (line 112)
+* Linux File System Standard: mktex configuration. (line 114)
+* Linux shells and configure: configure shells. (line 19)
+* lndir for building symlink trees: configure scenarios. (line 18)
+* loader options: configure environment.
+ (line 39)
+* loader options, final: Running make. (line 33)
+* loader options, initial: Running make. (line 30)
+* local cache of fonts: Security. (line 22)
+* log file: Logging. (line 6)
+* logging successful searches: Logging. (line 6)
+* lost+found directory: Searching overview. (line 56)
+* lostchar: Suppressing warnings.
+ (line 19)
+* ls-R: Supported file formats.
+ (line 81)
+* ls-R and AFS: Installing files. (line 40)
+* ls-R database file: ls-R. (line 6)
+* ls-R, simplest build: ls-R. (line 18)
+* Mach10 configure error: Empty Makefiles. (line 6)
+* MacKenzie, David <1>: Subdirectory expansion.
+ (line 22)
+* MacKenzie, David: History. (line 45)
+* magic characters: Searching overview. (line 13)
+* mailing lists: Mailing lists. (line 6)
+* maintainer-clean Make target: Cleaning up. (line 18)
+* Make arguments, additional: Running make. (line 36)
+* make, running: Running make. (line 6)
+* Makefile.in: Running configure. (line 6)
+* Makefiles, empty: Empty Makefiles. (line 6)
+* MAKETEX_DEBUG (512): Debugging. (line 91)
+* MAKETEX_FINE_DEBUG (1024): Debugging. (line 100)
+* MAKETEX_MODE: Default path features.
+ (line 19)
+* memory allocation routines: Calling sequence. (line 112)
+* metafont driver files: mktex configuration. (line 94)
+* Metafont failures: TeX or Metafont failing.
+ (line 6)
+* Metafont installation: Unable to generate fonts.
+ (line 52)
+* Metafont making too-large fonts: Unable to generate fonts.
+ (line 36)
+* Metafont using the wrong device: Unable to generate fonts.
+ (line 29)
+* MFBASES: Supported file formats.
+ (line 24)
+* MFINPUTS: Supported file formats.
+ (line 95)
+* MFPOOL: Supported file formats.
+ (line 99)
+* MFTINPUTS: Supported file formats.
+ (line 103)
+* MISCFONTS: Supported file formats.
+ (line 107)
+* mismatched checksum warnings: Suppressing warnings.
+ (line 17)
+* missfont.log: mktex script names. (line 35)
+* MISSFONT_LOG: mktex script names. (line 40)
+* missing character warnings: Suppressing warnings.
+ (line 20)
+* mkocp: mktex script names. (line 18)
+* mkofm: mktex script names. (line 21)
+* mktex script configuration: mktex configuration. (line 6)
+* mktex script names: mktex script names. (line 6)
+* mktex scripts: mktex scripts. (line 6)
+* mktex.cnf <1>: Specially-recognized files.
+ (line 28)
+* mktex.cnf: mktex configuration. (line 29)
+* mktex.opt: mktex configuration. (line 29)
+* mktexdir: mktex configuration. (line 62)
+* mktexfmt: mktex script names. (line 10)
+* mktexmf: mktex script names. (line 15)
+* mktexpk: mktex script names. (line 24)
+* mktexpk , initial runs: Simple installation. (line 79)
+* mktexpk can't guess mode: Unable to generate fonts.
+ (line 12)
+* mktextex: mktex script names. (line 27)
+* mktextfm: mktex script names. (line 30)
+* MLBIBINPUTS: Supported file formats.
+ (line 111)
+* MLBSTINPUTS: Supported file formats.
+ (line 115)
+* mode directory, omitting: mktex configuration. (line 99)
+* Morgan, Tim: History. (line 12)
+* mostlyclean Make target: Cleaning up. (line 10)
+* MPINPUTS: Supported file formats.
+ (line 119)
+* MPMEMS: Supported file formats.
+ (line 87)
+* MPPOOL: Supported file formats.
+ (line 123)
+* MPSUPPORT: Supported file formats.
+ (line 91)
+* MT_FEATURES: mktex configuration. (line 40)
+* multiple architectures, compiling on: configure scenarios. (line 18)
+* multiple architectures, directories for: configure scenarios.
+ (line 23)
+* multiple architectures, installing on: Installing files. (line 21)
+* multiple TeX hierarchies: Brace expansion. (line 20)
+* must exist: Searching overview. (line 31)
+* names for mktex scripts: mktex script names. (line 6)
+* NetBSD configure error: Empty Makefiles. (line 6)
+* NetBSD shells and configure: configure shells. (line 19)
+* Neumann, Gustaf: History. (line 57)
+* newsgroup for TeX: Mailing lists. (line 25)
+* NeXT sed error: Empty Makefiles. (line 6)
+* NeXT, lacking X11: Kpathsea application distributions.
+ (line 6)
+* NFS and ls-R: ls-R. (line 40)
+* nomfdrivers: mktex configuration. (line 93)
+* nomode: mktex configuration. (line 98)
+* non-English typesetting: Kpathsea application distributions.
+ (line 28)
+* non-Unix operating systems: Custom installation. (line 19)
+* none: Suppressing warnings.
+ (line 23)
+* null pointers, dereferencing: Bug checklist. (line 61)
+* numeric debugging values: Debugging. (line 34)
+* obtaining TeX: unixtex.ftp. (line 6)
+* OCPINPUTS: Supported file formats.
+ (line 127)
+* OFMFONTS: Supported file formats.
+ (line 131)
+* online Metafont display, spurious: Unable to generate fonts.
+ (line 36)
+* OPENTYPEFONTS: Supported file formats.
+ (line 135)
+* OpenWin libraries, dynamic linking problems: ShellWidgetClass.
+ (line 6)
+* optimization caveat: TeX or Metafont failing.
+ (line 15)
+* optimization, enabling: configure scenarios. (line 32)
+* options for debugging: Debugging. (line 6)
+* options to configure: configure options. (line 16)
+* OS/2 support: Custom installation. (line 19)
+* OTPINPUTS: Supported file formats.
+ (line 141)
+* overview of path searching: Searching overview. (line 6)
+* overview of programming with Kpathsea: Programming overview.
+ (line 6)
+* OVFFONTS: Supported file formats.
+ (line 144)
+* OVPFONTS: Supported file formats.
+ (line 147)
+* patches, Sun OpenWin: ShellWidgetClass. (line 29)
+* path expansion: Path expansion. (line 6)
+* path searching: Path searching. (line 6)
+* path searching options: Path searching options.
+ (line 6)
+* path searching, overview: Searching overview. (line 6)
+* path searching, standalone: Invoking kpsewhich. (line 6)
+* path sources: Path sources. (line 6)
+* paths, changing default <1>: Default path generation.
+ (line 6)
+* paths, changing default: Changing search paths.
+ (line 6)
+* paths, device name included in: Default path features.
+ (line 19)
+* paths.h: Default path generation.
+ (line 27)
+* paths.h, creating: Running make. (line 6)
+* pathsearch.h: Programming overview.
+ (line 24)
+* pc Pascal compiler: History. (line 12)
+* PCL driver: Kpathsea application distributions.
+ (line 13)
+* PDF generation: Kpathsea application distributions.
+ (line 16)
+* pdfglyphlist.txt: Specially-recognized files.
+ (line 31)
+* pdftex.cfg: Specially-recognized files.
+ (line 34)
+* PDFTEXCONFIG: Supported file formats.
+ (line 151)
+* pdftexconfig.tex: Specially-recognized files.
+ (line 34)
+* permission denied: Searching overview. (line 56)
+* permissions, directory: Security. (line 51)
+* permissions, file: Security. (line 47)
+* PKFONTS: Supported file formats.
+ (line 154)
+* plain.base: Unable to generate fonts.
+ (line 46)
+* pointer combination warnings: Pointer combination warnings.
+ (line 6)
+* PostScript driver: Kpathsea application distributions.
+ (line 16)
+* PostScript fonts, additional: Simple installation. (line 60)
+* precompiled executables, instead of installation: Simple installation.
+ (line 6)
+* preprocessor options: configure environment.
+ (line 32)
+* preprocessor options, additional: Running make. (line 24)
+* printer configuration files: Simple installation. (line 60)
+* privacy, semblance of: Logging. (line 32)
+* problems, common: Common problems. (line 6)
+* proginit.c: Default path features.
+ (line 25)
+* proginit.h: Calling sequence. (line 53)
+* program-varying paths: Supported file formats.
+ (line 12)
+* programming overview: Programming overview.
+ (line 6)
+* programming with config files: Programming with config files.
+ (line 6)
+* programming with Kpathsea: Calling sequence. (line 6)
+* programs using the library: Introduction. (line 13)
+* proof mode: Unable to generate fonts.
+ (line 36)
+* PSHEADERS: Supported file formats.
+ (line 160)
+* pxp Pascal preprocessor: History. (line 12)
+* quoting variable values: Variable expansion. (line 17)
+* re-entrant API: Programming overview.
+ (line 16)
+* readable: Suppressing warnings.
+ (line 26)
+* reading arbitrary-length lines: Calling sequence. (line 112)
+* README.CONFIGURE: Running configure. (line 15)
+* recording successful searches: Logging. (line 6)
+* relative filenames: Searching overview. (line 52)
+* relative filenames in ls-R: Installing files. (line 40)
+* reporting bugs: Reporting bugs. (line 6)
+* resident.c: Calling sequence. (line 47)
+* resolution, setting: Path searching options.
+ (line 17)
+* resolutions, last-resort: Fallback font. (line 6)
+* retrieving TeX: unixtex.ftp. (line 6)
+* right-hand side of variable assignments: Config files. (line 56)
+* Rokicki, Tom: History. (line 12)
+* root user: Tilde expansion. (line 19)
+* runtime configuration files: Config files. (line 6)
+* runtime debugging: Debugging. (line 6)
+* Sauter fonts, and dynamic source creation: mktex scripts. (line 6)
+* scripts for file creation: mktex scripts. (line 6)
+* search path, defined: Searching overview. (line 6)
+* search paths, changing default: Changing search paths.
+ (line 6)
+* searching for files: File lookup. (line 6)
+* searching for glyphs: Glyph lookup. (line 6)
+* searching overview: Searching overview. (line 6)
+* searching the database: Searching overview. (line 17)
+* searching the disk: Searching overview. (line 22)
+* security considerations: Security. (line 6)
+* sed error from configure: Empty Makefiles. (line 6)
+* SELFAUTODIR: Calling sequence. (line 31)
+* SELFAUTOLOC: Calling sequence. (line 31)
+* SELFAUTOPARENT: Calling sequence. (line 31)
+* sending patches: Bug checklist. (line 55)
+* setgid scripts: Security. (line 40)
+* SFDFONTS: Supported file formats.
+ (line 164)
+* sh5, ok with configure: configure shells. (line 25)
+* shared library, making: Shared library. (line 6)
+* shell scripts as configuration files: Config files. (line 79)
+* shell variables: Variable expansion. (line 17)
+* shell_escape, example for code: Programming with config files.
+ (line 10)
+* shells and configure: configure shells. (line 6)
+* simple installation: Simple installation. (line 6)
+* site overrides for mktex...: mktex configuration. (line 29)
+* size of distribution archives: Disk space. (line 6)
+* skeleton TeX directory: TeX directory structure.
+ (line 6)
+* slow startup time: Slow path searching. (line 6)
+* Solaris BSD compatibility, not: Running make. (line 44)
+* source files: Supported file formats.
+ (line 176)
+* sources for search paths: Path sources. (line 6)
+* special: Suppressing warnings.
+ (line 30)
+* st_nlink: Subdirectory expansion.
+ (line 26)
+* ST_NLINK_TRICK: Subdirectory expansion.
+ (line 38)
+* stack trace: Bug checklist. (line 61)
+* standalone path searching: Invoking kpsewhich. (line 6)
+* standard error and debugging output: Debugging. (line 27)
+* standard options: Standard options. (line 6)
+* startup time, excessive: Slow path searching. (line 6)
+* static linking: ShellWidgetClass. (line 39)
+* static linking and dlsym: dlopen. (line 6)
+* string routines: Calling sequence. (line 112)
+* strip: mktex configuration. (line 108)
+* stripsupplier: mktex configuration. (line 102)
+* striptypeface: mktex configuration. (line 105)
+* subdirectory searching: Subdirectory expansion.
+ (line 6)
+* suffixes, filename: File lookup. (line 24)
+* suggestions, making: Introduction. (line 27)
+* Sun 2: History. (line 12)
+* Sun OpenWin patches: ShellWidgetClass. (line 29)
+* supplier directory, omitting: mktex configuration. (line 103)
+* supported file formats: Supported file formats.
+ (line 6)
+* suppressing warnings: Suppressing warnings.
+ (line 6)
+* symbolic link trees, for multiple architectures: configure scenarios.
+ (line 18)
+* symbolic links not found: Unable to find files.
+ (line 21)
+* symbolic links, and ls-R: ls-R. (line 38)
+* symlinks, resolving: Calling sequence. (line 31)
+* system C compiler bugs: TeX or Metafont failing.
+ (line 19)
+* system dependencies: Running configure. (line 6)
+* system V universe: Running make. (line 44)
+* T1FONTS: Supported file formats.
+ (line 200)
+* T1INPUTS: Supported file formats.
+ (line 200)
+* T42FONTS: Supported file formats.
+ (line 205)
+* tcfmgr.map: Specially-recognized files.
+ (line 47)
+* TDS <1>: TeX directory structure.
+ (line 6)
+* TDS: Default path features.
+ (line 41)
+* testing, post-installation: Installation testing.
+ (line 6)
+* tests, simple: Simple installation. (line 79)
+* TeX directory structure <1>: TeX directory structure.
+ (line 6)
+* TeX directory structure: Default path features.
+ (line 41)
+* TeX environment variables: Supported file formats.
+ (line 6)
+* TeX failures: TeX or Metafont failing.
+ (line 6)
+* TeX file lookup: File lookup. (line 6)
+* TeX glyph lookup: Glyph lookup. (line 6)
+* TeX help mailing list: Mailing lists. (line 25)
+* TeX hierarchy, one: configure scenarios. (line 13)
+* TeX support: TeX support. (line 6)
+* TeX Users Group: Introduction. (line 39)
+* tex-file.c: File lookup. (line 37)
+* tex-file.h: Programming overview.
+ (line 24)
+* tex-glyph.c: Glyph lookup. (line 26)
+* tex-glyph.h: Programming overview.
+ (line 24)
+* tex-k-request@tug.org: Mailing lists. (line 7)
+* tex-k@tug.org (bug address): Reporting bugs. (line 8)
+* tex.web: unixtex.ftp. (line 20)
+* TEX_HUSH <1>: Suppressing warnings.
+ (line 6)
+* TEX_HUSH: Searching overview. (line 56)
+* TEXBIB: Supported file formats.
+ (line 28)
+* TEXCONFIG: Supported file formats.
+ (line 47)
+* TEXDOCS: Supported file formats.
+ (line 173)
+* TEXFONTMAPS: Supported file formats.
+ (line 84)
+* TEXFONTS: Supported file formats.
+ (line 65)
+* texfonts.map: Fontmap. (line 6)
+* TEXFORMATS: Supported file formats.
+ (line 54)
+* TEXINDEXSTYLE: Supported file formats.
+ (line 74)
+* TEXINPUTS: Supported file formats.
+ (line 69)
+* TEXMF: TeX directory structure.
+ (line 6)
+* texmf.cnf: Specially-recognized files.
+ (line 38)
+* texmf.cnf missing, warning about: Config files. (line 18)
+* texmf.cnf, and variable expansion: Variable expansion. (line 6)
+* texmf.cnf, creating: Running make. (line 6)
+* texmf.cnf, definition for: Config files. (line 6)
+* texmf.cnf, generated: Default path generation.
+ (line 22)
+* texmf.cnf, source for path: Path sources. (line 17)
+* texmf.in: Default path generation.
+ (line 22)
+* texmf.in, editing: Changing search paths.
+ (line 6)
+* texmf.sed: Default path generation.
+ (line 17)
+* TEXMFCNF <1>: Supported file formats.
+ (line 39)
+* TEXMFCNF: Config files. (line 6)
+* TEXMFDBS <1>: Supported file formats.
+ (line 81)
+* TEXMFDBS: ls-R. (line 6)
+* TEXMFINI: Supported file formats.
+ (line 24)
+* TEXMFLOG: Logging. (line 10)
+* TEXMFOUTPUT: mktex script names. (line 40)
+* TEXMFSCRIPTS: Supported file formats.
+ (line 179)
+* TEXMFVAR: mktex configuration. (line 124)
+* texmfvar: mktex configuration. (line 123)
+* TEXPICTS: Supported file formats.
+ (line 69)
+* TEXPKS: Supported file formats.
+ (line 154)
+* TEXPOOL: Supported file formats.
+ (line 183)
+* TEXPSHEADERS: Supported file formats.
+ (line 160)
+* TEXSIZES: Fallback font. (line 6)
+* TEXSOURCES: Supported file formats.
+ (line 176)
+* TFMFONTS: Supported file formats.
+ (line 187)
+* tilde expansion: Tilde expansion. (line 6)
+* tilde.c: Tilde expansion. (line 25)
+* time system call: Logging. (line 15)
+* tolerance for glyph lookup: Basic glyph lookup. (line 15)
+* total disk space: Disk space. (line 6)
+* trailing / in home directory: Tilde expansion. (line 19)
+* trailing colons: Default expansion. (line 6)
+* TRFONTS: Supported file formats.
+ (line 192)
+* trick for detecting leaf directories: Subdirectory expansion.
+ (line 22)
+* trojan horse attack: Security. (line 10)
+* try_std_extension_first: File lookup. (line 24)
+* TTFONTS: Supported file formats.
+ (line 196)
+* tug.org: unixtex.ftp. (line 6)
+* typeface directory, omitting: mktex configuration. (line 106)
+* ucbinclude, avoiding: Running make. (line 44)
+* Ultrix shells and configure: configure shells. (line 25)
+* unable to find files: Unable to find files.
+ (line 6)
+* unable to generate fonts: Unable to generate fonts.
+ (line 6)
+* uname: Bug checklist. (line 20)
+* universe, BSD vs. system V: Running make. (line 44)
+* unixtex.ftp: unixtex.ftp. (line 6)
+* unknown special warnings: Suppressing warnings.
+ (line 31)
+* unreadable file warnings: Suppressing warnings.
+ (line 27)
+* unreadable files: Searching overview. (line 56)
+* unusable ls-R warning: ls-R. (line 45)
+* usage patterns, finding: Logging. (line 6)
+* USE_TEXMFVAR: mktex configuration. (line 129)
+* USE_VARTEXFONTS: mktex configuration. (line 119)
+* Usenet TeX newsgroup: Mailing lists. (line 25)
+* USERPROFILE, as ~ expansion: Tilde expansion. (line 6)
+* varfonts: mktex configuration. (line 113)
+* variable expansion: Variable expansion. (line 6)
+* variable.c: Variable expansion. (line 32)
+* variable.h: Programming with config files.
+ (line 10)
+* VARTEXFONTS: mktex configuration. (line 114)
+* VAX 11/750: History. (line 12)
+* version number, of Kpathsea: Kpathsea application distributions.
+ (line 6)
+* version numbers, determining: Bug checklist. (line 15)
+* VF files, not found: Searching overview. (line 31)
+* VFFONTS: Supported file formats.
+ (line 208)
+* VMS support: Custom installation. (line 19)
+* Vojta, Paul: History. (line 30)
+* Walsh, Norman: History. (line 57)
+* warning about unusable ls-R: ls-R. (line 45)
+* warning, about missing texmf.cnf: Config files. (line 18)
+* warnings, file access: Searching overview. (line 56)
+* warnings, pointer combinations: Pointer combination warnings.
+ (line 6)
+* warnings, suppressing: Suppressing warnings.
+ (line 6)
+* wcstombs: dlopen. (line 6)
+* WEB2C: Supported file formats.
+ (line 216)
+* Weber, Olaf: History. (line 74)
+* WEBINPUTS: Supported file formats.
+ (line 212)
+* whitespace, in fontmap files: Fontmap. (line 28)
+* whitespace, not ignored on continuation lines: Config files.
+ (line 37)
+* www.tug.org: unixtex.ftp. (line 6)
+* X11 previewer: Kpathsea application distributions.
+ (line 25)
+* X11, lacking on NeXT: Kpathsea application distributions.
+ (line 6)
+* XCFLAGS: Running make. (line 26)
+* XCPPFLAGS: Running make. (line 22)
+* XDEFS: Running make. (line 23)
+* XDvi: Specially-recognized files.
+ (line 41)
+* XDVIFONTS: Supported file formats.
+ (line 243)
+* XDVIMAKEPK: mktex script names. (line 32)
+* XDVISIZES: Fallback font. (line 6)
+* XLDFLAGS: Running make. (line 29)
+* XLOADLIBES: Running make. (line 32)
+* XMAKEARGS: Running make. (line 35)
+* Xmu library problems: ShellWidgetClass. (line 13)
+* XtStrings: XtStrings. (line 6)
+* zuhn, david: History. (line 51)
+* { expansion: Brace expansion. (line 6)
+* ~ expansion: Tilde expansion. (line 6)
+
+
+
+Tag Table:
+Node: Top1627
+Node: Introduction2269
+Node: History4090
+Node: Installation8182
+Node: Simple installation8972
+Node: Custom installation12555
+Node: Disk space13729
+Node: Kpathsea application distributions14613
+Node: Changing search paths15728
+Node: Default path features16910
+Node: Default path generation18993
+Node: Running configure20436
+Node: configure shells21487
+Node: configure options22539
+Node: configure environment24046
+Node: configure scenarios25848
+Node: Shared library27434
+Node: Running make28448
+Node: Installing files30495
+Node: Cleaning up32442
+Node: Filename database generation33490
+Node: mktex scripts34057
+Node: mktex configuration35334
+Node: mktex script names41153
+Node: mktex script arguments42544
+Node: Installation testing43430
+Node: Security43794
+Node: TeX directory structure46361
+Node: unixtex.ftp50783
+Node: Reporting bugs52117
+Node: Bug checklist52852
+Node: Mailing lists56549
+Node: Debugging57758
+Node: Logging62836
+Node: Common problems64706
+Node: Unable to find files65537
+Node: Slow path searching67948
+Node: Unable to generate fonts69325
+Node: TeX or Metafont failing71834
+Node: Empty Makefiles73713
+Node: XtStrings74950
+Node: dlopen75786
+Node: ShellWidgetClass76604
+Node: Pointer combination warnings78236
+Node: Path searching78625
+Node: Searching overview79272
+Node: Path sources82668
+Node: Config files83739
+Node: Path expansion87666
+Node: Default expansion88615
+Node: Variable expansion90685
+Node: Tilde expansion92088
+Node: Brace expansion93068
+Node: KPSE_DOT expansion93993
+Node: Subdirectory expansion94506
+Node: Filename database96857
+Node: ls-R97911
+Node: Filename aliases100805
+Node: Database format101983
+Node: Invoking kpsewhich102996
+Node: Path searching options103942
+Node: Specially-recognized files112159
+Node: Auxiliary tasks113515
+Node: Standard options115340
+Node: TeX support115696
+Node: Supported file formats116987
+Node: File lookup124541
+Node: Glyph lookup126290
+Node: Basic glyph lookup127414
+Node: Fontmap128293
+Node: Fallback font130910
+Node: Suppressing warnings131823
+Node: Programming132928
+Node: Programming overview133441
+Node: Calling sequence136135
+Node: Program-specific files142658
+Node: Programming with config files143681
+Node: Index144993
+
+End Tag Table