home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-dist / unixtex-6.1b-bin0.lha / info / kpathsea.info-1 < prev    next >
Encoding:
GNU Info File  |  1996-10-12  |  49.6 KB  |  1,278 lines
  1. This is Info file kpathsea.info, produced by Makeinfo-1.64 from the
  2. input file /ade-src/contrib/unixtex/kpathsea/kpathsea.texi.
  3.  
  4. START-INFO-DIR-ENTRY
  5. * Kpathsea: (kpathsea).        File lookup along search paths.
  6. END-INFO-DIR-ENTRY
  7.  
  8.   This file documents the Kpathsea library for path searching.
  9.  
  10.   Copyright (C) 1993, 94, 95 Karl Berry.
  11.  
  12.   Permission is granted to make and distribute verbatim copies of this
  13. manual provided the copyright notice and this permission notice are
  14. preserved on all copies.
  15.  
  16.   Permission is granted to copy and distribute modified versions of this
  17. manual under the conditions for verbatim copying, provided also that the
  18. sections entitled "Freedom" and "GNU General Public License" are
  19. included exactly as in the original, and provided that the entire
  20. resulting derived work is distributed under the terms of a permission
  21. notice identical to this one.
  22.  
  23.   Permission is granted to copy and distribute translations of this
  24. manual into another language, under the above conditions for modified
  25. versions, except that the sections entitled "Freedom" and "GNU General
  26. Public License" may be included in a translation approved by the Free
  27. Software Foundation instead of in the original English.
  28.  
  29. 
  30. File: kpathsea.info,  Node: Top,  Next: Introduction,  Up: (dir)
  31.  
  32. Kpathsea library
  33. ****************
  34.  
  35.   This manual documents how to install and use the Kpathsea library for
  36. filename lookup.  It corresponds to version 2.6 (released in January
  37. 1995).
  38.  
  39. * Menu:
  40.  
  41. * Introduction::                Overview.
  42. * Installation::                Compilation, installation, and bug reporting.
  43. * Debugging::            Analyzing runtime problems.
  44.  
  45. * Path searching::        How filename lookups work.
  46. * TeX searching::        Special support for TeX lookups.
  47.  
  48. * TeX directory structure::    Ways to manage the many input files.
  49.  
  50. * Programming::            How to use the library in your program.
  51.  
  52. * Copying::                     Conditions for copying, modifying and sharing.
  53. * Freedom::                     Regain your programming freedom.
  54. * Index::                       General index.
  55.  
  56. 
  57. File: kpathsea.info,  Node: Introduction,  Next: Installation,  Prev: Top,  Up: Top
  58.  
  59. Introduction
  60. ************
  61.  
  62.   This manual corresponds to version 2.6 of the Kpathsea library,
  63. released in January 1995.
  64.  
  65.   The library's fundamental purpose is to look up a file in a list of
  66. directories specified by the user, similar to what shells do when
  67. looking up program names to execute.
  68.  
  69.   The following software, all of which I maintain, uses this library:
  70.  
  71.    * Dviljk
  72.  
  73.    * Dvipsk (*note Introduction: (dvipsk)Top.)
  74.  
  75.    * GNU font utilities (*note Introduction: (fontu)Top.)
  76.  
  77.    * Web2c (*note Introduction: (web2c)Top.)
  78.  
  79.    * Xdvik
  80.  
  81.   The library is still under development (and probably always will be,
  82. despite my hopes). I do not promise to keep the interface unchanged.  If
  83. you have comments or suggestions, please send them to me (*note
  84. Reporting bugs::.).
  85.  
  86.   Currently, I distribute the library under the GNU General Public
  87. License (*note Copying::.).  In short, this means if you write a
  88. program using the library, you must (offer to) distribute the source,
  89. and allow anyone to modify the source and distribute their
  90. modifications.
  91.  
  92.   If you have a problem with this, contact me. I would consider putting
  93. the library under the GNU Library General Public License, which would
  94. permit you to distribute the source only to the library, not to your
  95. program using it.  But I will only do this if someone actually says they
  96. will not use the library under the GPL conditions, and would use it
  97. under the LGPL.
  98.  
  99.   If you know enough about TeX to be reading this manual, then you (or
  100. perhaps your institution) should consider joining the TeX Users Group
  101. (if you're already a member, great!).  TUG produces a periodical called
  102. `TUGboat', sponsors an annual meeting (the proceedings of which are
  103. published in `TUGboat'), and arranges courses on TeX for all levels of
  104. users.  Given sufficient funding (which your joining will help) TUG
  105. could sponsor more projects that will benefit the TeX community, such as
  106. a successor to TeX pi .  Anyway, here is the address:
  107.  
  108.      TeX Users Group
  109.      P.O. Box 869
  110.      Santa Barbara, CA 93102 USA
  111.      phone: (805) 899-4673
  112.      email: `tug@tug.org'
  113.  
  114. * Menu:
  115.  
  116. * History::
  117.  
  118. 
  119. File: kpathsea.info,  Node: History,  Up: Introduction
  120.  
  121. History
  122. =======
  123.  
  124.   (This section is for those people who are curious about how this came
  125. about.) (If you like to read historical accounts of software, I urge
  126. you to seek out the GNU Autoconf manual and, even more fun, the "Errors
  127. of TeX" paper that Don Knuth published in `Software--Practice and
  128. Experience'.)
  129.  
  130.   My first ChangeLog entry for Web2c seems to be February 1990, but I
  131. may have done some stuff before then.  In any case, Tim Morgan and I
  132. were sort of jointly maintaining it for a time.  (I should say that Tim
  133. had made Web2c into a real distribution long before I had ever used it
  134. or even heard of it, and Tom Rokicki did the original implementation.)
  135.  
  136.   It must have been later in 1990 and 1991 that I started working on
  137. `TeX for the Impatient' and Dvips, Xdvi, Web2c, and the GNU fontutils
  138. (which I was also writing at the time) using different environment
  139. variables, and, even more importantly, having different bugs in their
  140. path searching became extremely painful.  I also desperately wanted to
  141. implement subdirectory searching, since I couldn't stand putting
  142. everything in one big directory, and also couldn't stand having to
  143. explicitly specify `pandora', `cm' in a path.
  144.  
  145.   In the first incarnation, I just hacked separately on each program--
  146. that was the original subdirectory searching code in both Xdvi and
  147. Dvips, though I think Paul Vojta has completely rewritten Xdvi's support
  148. by now.  That is, I tried to go with the flow in each program, rather
  149. than changing the program's calling sequences to conform to common
  150. routines.
  151.  
  152.   Then, as bugs inevitably appeared, I found I was fixing the same thing
  153. in each of three (Web2c and fontutils were always sharing code, since I
  154. maintained those--there was no Dvipsk or Xdvik or Dviljk at this
  155. point).  After a while, I finally started sharing source files.  They
  156. weren't a library, though.  I just kept things up to date with shell
  157. scripts.  (I was developing on a 386 running ISC 2.2 at the time, and so
  158. didn't have symbolic links.  An awful experience.)
  159.  
  160.   Things kept on like this for quite a while.  The `ChangeLog's for
  161. Xdvik and Dvipsk record initial releases of those distributions in May
  162. and June 1992.  I think it was because I was tired of the different
  163. configuration strategies of each program, not so much because of the
  164. path searching.  (Autoconf was being developed by David MacKenzie and
  165. others, and I was adapting it to TeX and friends.)
  166.  
  167.   I starting to make it a separate library that other programs could
  168. link with on my birthday in April 1993, according to the ChangeLog.  I
  169. don't remember exactly why I finally took the time to make it a separate
  170. library; I think it was a conversation with david zuhn that led to doing
  171. it.  Just seemed like it was time.
  172.  
  173.   Dviljk got started in March 1994 after I bought a Laserjet 4.
  174. (Kpathsea work got suspended while Norm Walsh and I, with Gustaf
  175. Neumann's help, implemented a way for TeX to get at all those neat
  176. builtin LJ4 fonts ... such a treat to have something to typeset in
  177. besides Palatino!)
  178.  
  179.   At this point (October 1994), I've implemented just about all the
  180. path-searching features in Kpathsea that I ever intended to (and some I
  181. didn't intend ...). After the next stable release of Web2c, I figure
  182. I'll be able to stop development, and turn most of my attention back to
  183. making fonts for GNU.  (Always assuming Microsoft hasn't completely
  184. obliterated Unix by then, or that software patents haven't stopped
  185. software development by anybody smaller than a company with a
  186. million-dollar-a-year legal budget.  Which is actually what I think is
  187. likely to happen, but that's another story...)
  188.  
  189. 
  190. File: kpathsea.info,  Node: Installation,  Next: Debugging,  Prev: Introduction,  Up: Top
  191.  
  192. Installation
  193. ************
  194.  
  195.   Here are the basic steps for configuration and installation:
  196.  
  197.   1. Edit the file `make/paths.make' if you want to make changes to the
  198.      installation directories or paths that will have effect across
  199.      different runs of `configure'.  Alternatively, override the Make
  200.      variables on the command line when you run Make.
  201.  
  202.      Exception: to reliably change the top-level `prefix', you must give
  203.      `configure' the option `-prefix=PREFIX', instead of changing the
  204.      value in `paths.make'.
  205.  
  206.   2. Edit `kpathsea/texmf.cnf.in' to change the local paths to match
  207.      your local setup.  *Note Default paths: (kpathsea)Default paths,
  208.      for more details on changing the paths. A copy is in
  209.      `kpathsea/INSTALL'.  See `kpathsea/HIER' for an explanation of the
  210.      default setup.
  211.  
  212.      If the paths do not match where the files actually are, the
  213.      programs will probably start up Very, Very, Slowly, and/or not be
  214.      able to find the fonts or other input files.
  215.  
  216.   3. `sh configure' (in the top-level directory).  This makes
  217.      system-dependent `#define's' in `*/c-auto.h' (from the
  218.      corresponding `c-auto.h.in') and creates a `Makefile' (from the
  219.      corresponding `Makefile.in', by doing `@VAR@' and `ac_include'
  220.      substitutions).
  221.  
  222.      Perhaps the most common desire is to compile with optimization
  223.      instead of or as well as debugging.  You can change the options
  224.      passed to the compiler by changing `CFLAGS', either for
  225.      `configure' or `make'.  For example:
  226.  
  227.           prompt$ env CFLAGS="-g -O" configure
  228.           prompt$ make
  229.      or
  230.           prompt$ configure
  231.           prompt$ make CFLAGS="-g -O"
  232.  
  233.      *Note Running `configure' scripts: (autoconf)Invoking configure,
  234.      for detailed `configure' options.  (A copy is in
  235.      `kpathsea/CONFIGURE'.)
  236.  
  237.   4. `make' (still in the top-level directory). Barring configuration
  238.      and compiler bugs, this will compile all the programs.  *Note
  239.      Common problems: (kpathsea)Common problems, for system-dependent
  240.      problems (this section is also in `kpathsea/INSTALL').
  241.  
  242.      This also creates the `texmf.cnf' and `paths.h' files that define
  243.      the default search paths.
  244.  
  245.   5. `make install'. This installs the library, header files, and
  246.      documentation. Or `make install-data' to just install the
  247.      architecture-independent files. Or `make install-exec' to just
  248.      install the (binary) archive library file.
  249.  
  250.      Since I only distribute Kpathsea as part of another package, you
  251.      will probably be doing the above in a top-level directory that
  252.      contains a `Makefile', `kpathsea', and the other package.  But you
  253.      can do the installation in `kpathsea' itself, if you only want to
  254.      install the library, not the other package.
  255.  
  256.   6. The first time you install any manual in Info, you have to add a
  257.      line (you choose where) to the `dir' file in your `$(infodir)'
  258.      directory.  A sample line to add is given near the top of the
  259.      Texinfo source files (`kpathsea/kpathsea.texi' and
  260.      `dvipsk/dvips.texi').
  261.  
  262.   7. `make distclean'.  This removes all files created by the build.
  263.  
  264.  
  265.   *Note Filename database::, for a description of an
  266. externally-generated database that can help speed searches.
  267.  
  268.   *Note Debugging::, for runtime debugging support that may help track
  269. down problems.
  270.  
  271.   Do not attempt to use any version of Kpathsea with any program except
  272. the version that the program came with, unless you are a glutton for
  273. punishment.
  274.  
  275. * Menu:
  276.  
  277. * Default paths::    Changing default installation directories and paths.
  278. * Common problems::    When things go wrong.
  279. * Shared library::    Making Kpathsea a shared library.
  280. * Reporting bugs::    Where and how to report bugs.
  281.  
  282. 
  283. File: kpathsea.info,  Node: Default paths,  Next: Common problems,  Up: Installation
  284.  
  285. Default paths
  286. =============
  287.  
  288.   To summarize the chain of events that go into defining the default
  289. paths:
  290.  
  291.   1. `configure' creates a `Makefile' from each `Makefile.in'.
  292.  
  293.   2. When Make runs in the `kpathsea' directory, it creates a file
  294.      `texmf.sed' that substitutes the Make value of `$(var)' for a
  295.      string `@var@'. The variables in question are the one that define
  296.      the installation directories.
  297.  
  298.   3. `texmf.sed' (and a little extra magic--see `kpathsea/Makefile') is
  299.      applied to `texmf.cnf.in' to generate `texmf.cnf'. This is the
  300.      file that will eventually be installed and used by the programs to
  301.      look up programs.
  302.  
  303.   4. The definitions in `texmf.cnf' are changed into the form of C
  304.      `#define''s, producing `paths.h'. These values will be the
  305.      compile-time defaults; they are not used unless no `texmf.cnf' file
  306.      can be found at runtime.
  307.  
  308.      (That's a partial lie: the compile-time defaults are what extra
  309.      `:''s in `texmf.cnf' expand into; but the paths as distributed
  310.      have no extra `:''s, and there's no particular reason for them to.)
  311.  
  312.  
  313.   The purpose of this elaborate sequence is to avoid having the same
  314. information in more than one place. If you change the installation
  315. directories or top-level prefix before running `configure', those
  316. changes will propagate through the whole sequence. If you change the
  317. default paths in `texmf.cnf.in', those changes are propagated to the
  318. compile-time defaults.
  319.  
  320.   Alternatively, you can ignore the whole mess and edit `texmf.cnf'
  321. after it is installed. Maybe even copying it into place beforehand so
  322. you can complete the installation, if TeX or Metafont is having trouble
  323. finding their input files.
  324.  
  325.   Unfortunately, editing `Makefile.in' *does not work* in one common
  326. case--changing the `prefix' or `exec_prefix' variables. For these, you
  327. must use the `-prefix' or `-exec-prefix' options to `configure'.  *Note
  328. Running `configure' scripts: (autoconf)Running configure Scripts.
  329. (That's another partial lie: editing does work, as long as a program
  330. named `tex' is not in your `PATH'.)
  331.  
  332.   *Note TeX directory structure: TeX directory structure, for a
  333. description of some ways to arrange the TeX library files, and some
  334. features of the distributed paths that may not be obvious.  The file
  335. `kpathsea/HIER' is a copy of that section.
  336.  
  337.   The Make definitions are all repeated in several `Makefile''s; but
  338. changing the top-level `Makefile' should suffice, as it passes down all
  339. the variable definitions, thus overriding the submakes. (The
  340. definitions are repeated so you can potentially run Make in the
  341. subdirectories.)
  342.  
  343. 
  344. File: kpathsea.info,  Node: Common problems,  Next: Shared library,  Prev: Default paths,  Up: Installation
  345.  
  346. Common problems
  347. ===============
  348.  
  349.   Some common problems with compilation, linking, or execution are
  350. described below.
  351.  
  352. * Menu:
  353.  
  354. * Unable to find files:: If your program can't find fonts or anything else.
  355. * Slow path searching::  If it takes forever to find anything.
  356.  
  357. * XtInherit::        For XtInherit link problems on OSF/1 1.x.
  358. * wchar_t::        For wchar_t difficulties.
  359. * ShellWidgetClass::    For dynamic linking with Sun's openwin libraries.
  360. * Pointer combination warnings:: For old compilers that don't grok char *.
  361.  
  362. 
  363. File: kpathsea.info,  Node: Unable to find files,  Next: Slow path searching,  Up: Common problems
  364.  
  365. Unable to find files
  366. --------------------
  367.  
  368.   If a program complains it cannot find fonts (or other input files),
  369. any of several things might be wrong:
  370.  
  371.    * You don't have the fonts (or whatever) installed. Nothing will
  372.      automatically generate TFM files or TeX and Metafont sources for
  373.      you (by default). *Note Obtaining Web2c: (web2c)Obtaining Web2c.
  374.  
  375.      You can, however, configure TeX and Metafont to run a script to
  376.      generate these input files, if you have (or write) such scripts.
  377.      *Note `MakeTeX'... invocation: (web2c)MakeTeX... invocation.
  378.  
  379.    * You have (perhaps unknowingly) told Kpathsea to use search paths
  380.      that don't reflect where the files actually are. One common cause
  381.      is having environment variables set, thus overriding what you
  382.      carefully set in `texmf.cnf'. *Note TeX environment variables: TeX
  383.      environment variables.
  384.  
  385.    * Your files reside in a directory that is only pointed to via a
  386.      symbolic link, in a leaf directory.
  387.  
  388.      Unfortunately, Kpathsea's subdirectory searching has a (congenital)
  389.      deficiency: If a directory D being searched for subdirectories
  390.      contains plain files and symbolic links to other directories, but
  391.      no true subdirectories, D will be considered a leaf directory,
  392.      i.e., the symbolic links will not be followed.  *Note Subdirectory
  393.      expansion::, for an explanation of why this happens.
  394.  
  395.      You can work around this problem by creating an empty dummy
  396.      subdirectory in D. Then D will no longer be a leaf, and the
  397.      symlinks will be followed.
  398.  
  399.      The directory immediately followed by the `//' in the path
  400.      specification, however, is always searched for subdirectories,
  401.      even if it is a leaf.  This is since presumably you would not have
  402.      asked for the directory to be searched for subdirectories if you
  403.      didn't want it to be.
  404.  
  405.    * There is a bug in the library. *Note Reporting bugs::.
  406.  
  407.   In any case, you may find the debugging options helpful in determining
  408. precisely where the fonts (or whatever) are being looked for. See the
  409. program's documentation for its debugging options, and also *note
  410. Debugging::..
  411.  
  412. 
  413. File: kpathsea.info,  Node: Slow path searching,  Next: XtInherit,  Prev: Unable to find files,  Up: Common problems
  414.  
  415. Slow path searching
  416. -------------------
  417.  
  418.   If your program takes an excessively long time to find fonts or other
  419. input files, but does eventually succeed, here are some possible
  420. culprits:
  421.  
  422.    * Most likely, you just have a lot of directories to search, and that
  423.      takes a noticeable time. The solution is to create and maintain a
  424.      separate `ls-R' file that lists all the files in your main TeX
  425.      hierarchy. *Note Filename database::.  (Kpathsea always uses `ls-R'
  426.      if it's present; there's no need to recompile or reinstall any of
  427.      the programs.)
  428.  
  429.    * Your recursively-searched directories (e.g.,
  430.      `/usr/local/lib/tex/fonts//'), contain a mixture of files and
  431.      directories. This prevents Kpathsea from using a useful
  432.      optimization (*note Subdirectory expansion::.).
  433.  
  434.      It is best to have only directories (and perhaps a `README') in the
  435.      upper levels of the directory structure, and it's very important
  436.      to have *only* files, and no subdirectories, in the directories
  437.      where the dozens of TFM, PK, or whatever files reside.
  438.  
  439.    * Finally, one simple-to-fix (but unlikely) cause: If you recursively
  440.      search `$HOME' or `~', and you are running as `root', you will
  441.      search every directory on the system.  This typically takes quite
  442.      some time!
  443.  
  444.   In any case, you may find the debugging options helpful in determining
  445. precisely when the disk or network is being pounded. *Note Debugging::,
  446. and also see the program's documentation.
  447.  
  448. 
  449. File: kpathsea.info,  Node: XtInherit,  Next: wchar_t,  Prev: Slow path searching,  Up: Common problems
  450.  
  451. `XtInherit'
  452. -----------
  453.  
  454.   On DEC OSF/1 1.x systems, the loader has a bug that manifests itself
  455. in the following error (all on one line, but for the sake of the paper
  456. width it's broken here):
  457.  
  458.      xdvik/xdvi: /sbin/loader: Fatal Error: search_for_undefineds:
  459.           symbol _XtInherit should not have any relocation entry
  460.  
  461. According to Michael Rickabaugh `<mjr@quarry.enet.dec.com>':
  462.  
  463.      This is a bug fixed in DEC OSF/1 2.0.
  464.      
  465.      If you know how, installing `/sbin/loader' from a 2.0 system onto a
  466.      1.3 system will work.  Make sure that `/usr' is *not* mounted
  467.      when you do this.  (If you forget about umounting `/usr', it is
  468.      possible most of your filesystems will become corrupted.)
  469.      
  470.      Otherwise, I suggest getting a hold of a 2.0 CD and running
  471.      `/usr/sbin/installupdate'.
  472.  
  473.   Alternatively, you may be able to use the freely available X11
  474. libraries that come with the MIT distribution (on `ftp.x.org', for
  475. example).
  476.  
  477.   Linking statically, perhaps only with some of the X libraries, may
  478. also work.  (if you find the definitive workaround, please let me know.)
  479.  
  480. 
  481. File: kpathsea.info,  Node: wchar_t,  Next: ShellWidgetClass,  Prev: XtInherit,  Up: Common problems
  482.  
  483. `wchar_t'
  484. ---------
  485.  
  486.   The upshot of all the following is that if you get error messages
  487. regarding `wchar_t', try defining `NO_FOIL_X_WCHAR_T' (for Web2c) or
  488. `FOIL_X_WCHAR_T' (for everything else).
  489.  
  490.   `wchar_t' has caused infinite trouble. None of my code ever uses
  491. `wchar_t'; all I want to do is include X header files and various
  492. system header files, possibly compiling with GCC. This seems an
  493. impossible task!
  494.  
  495.   The X11 header `<Xlib.h>' and GCC's `<stddef.h>' have conflicting
  496. definitions for wchar_t.
  497.  
  498.   The particulars: `<X11/Xlib.h>' from MIT X11R5 defines `wchar_t' if
  499. `X_WCHAR' is defined, which is defined if `X_NOT_STDC_ENV' is defined,
  500. and we define *that* if `STDC_HEADERS' is not defined (`configure'
  501. decides if STDC_HEADERS gets defined).  But when compiling with gcc on
  502. SunOS 4.1.x, `STDC_HEADERS' is not defined (`string.h' doesn't declare
  503. the `mem'* functions), so we do get X's `wchar_t'--and we also get
  504. gcc's `wchar_t' from its `<stddef.h>'.  Conflict.
  505.  
  506.   On the other hand, SunOS 4.1.1 with some other X configurations
  507. actually needs GCC to define `wchar_t', and fails otherwise.
  508.  
  509.   My current theory is to define `wchar_t' to a nonsense symbol before
  510. the X include files are read; that way its definition (if any) will be
  511. ignored by other system include files.  Going along with that, define
  512. `X_WCHAR' to tell X not to use `<stddef.h>', that we've already
  513. included, but instead to make its own definition.
  514.  
  515.   But this is not the end of the story. The X11 include files
  516. distributed with DG/UX 5.4.2 for the Aviion have been modified to
  517. include `<_int_wchar_t.h>' if `X_WCHAR', so our `#define' will not have
  518. any typedef to change--but the uses of `wchar_t' in the X include files
  519. will be changed to reference this undefined symbol. So there's nothing
  520. to foil in this case. I don't know how to detect this automatically, so
  521. it's up to you to define `NO_FOIL_X_WCHAR_T' yourself.
  522.  
  523. 
  524. File: kpathsea.info,  Node: ShellWidgetClass,  Next: Pointer combination warnings,  Prev: wchar_t,  Up: Common problems
  525.  
  526. `ShellWidgetClass'
  527. ------------------
  528.  
  529.   This section is adapted from question 47 from the
  530. `comp.sys.sun.admin' FAQ.
  531.  
  532.   If you are linking with Sun's OpenWindows libraries in SunOS 4.1.x,
  533. you may get undefined symbols `_get_wmShellWidgetClass' and
  534. `_get_applicationShellWidgetClass'. This problem does not arise with
  535. the standard MIT libraries under SunOS.
  536.  
  537.   The cause is bugs in the `Xmu' shared library as shipped from Sun.
  538. There are several fixes:
  539.  
  540.    * Get the Openwindows patches that apply to this problem.
  541.  
  542.    * Statically link the `Xmu' library into the executable.
  543.  
  544.    * Avoid using `Xmu' at all. For this last, if you are compiling
  545.      Metafont, *note Online Metafont graphics: (Web2c)Online Metafont
  546.      graphics.. If you are compiling Xdvi, see the `-DNOTOOL' option in
  547.      `xdvik/INSTALL'.
  548.  
  549.    * Ignore the errors. The binary runs fine regardless.
  550.  
  551.   Here is the information for getting the two patches:
  552.  
  553.      Patch ID: 100512-02
  554.      Bug ID's: 1086793, 1086912, 1074766
  555.      Description: 4.1.x OpenWindows 3.0 `libXt' jumbo patch
  556.      
  557.      Patch ID: 100573-03
  558.      Bug ID: 1087332
  559.      Description: 4.1.x OpenWindows 3.0 undefined symbols when using shared
  560.      `libXmu'.
  561.  
  562.   The way to statically link with `libXmu' depends on whether you are
  563. using a Sun compiler (e.g., `cc') or `gcc'. If the format, alter the
  564. `x_libs' make variable to include
  565.  
  566.      -Bstatic -lXmu -Bdynamic
  567.  
  568.   If you are using `gcc', include `-static' in `LDFLAGS'; this will
  569. link all libraries statically. If you want to link only `Xmu'
  570. statically and everything else dynamically, you have to do it by hand:
  571. run `gcc -v', grab the `ld' line, and add the `-B''s given above around
  572. `-lXmu'.
  573.  
  574.   The reason is that gcc moves all linker options to the front of the
  575. `ld' command line.  So you can't specify different options for
  576. different libraries.  When I reported this to the GCC maintainers, the
  577. reply was that they would happily merge in the changes, but they didn't
  578. want to take the time to do it themselves.
  579.  
  580. 
  581. File: kpathsea.info,  Node: Pointer combination warnings,  Prev: ShellWidgetClass,  Up: Common problems
  582.  
  583. Pointer combination warnings
  584. ----------------------------
  585.  
  586.   When compiling with old C compilers, you may get some warnings about
  587. "illegal pointer combinations".  These are spurious; just ignore them.
  588. I decline to clutter up the source with casts to get rid of them.
  589.  
  590.   In general, if you have trouble with a system C compiler, I advise
  591. trying the GNU C compiler. (And vice versa, unfortunately; but in that
  592. case I also recommend reporting a bug to the GCC bug list.)
  593.  
  594. 
  595. File: kpathsea.info,  Node: Shared library,  Next: Reporting bugs,  Prev: Common problems,  Up: Installation
  596.  
  597. Shared library
  598. ==============
  599.  
  600.   You can compile Kpathsea as a shared library.  The advantage in doing
  601. this is that the different executables can then share the code,
  602. decreasing memory usage.  (The other advantage in general of shared
  603. libraries is that it's possible to update the library and programs
  604. independently.  But since the Kpathsea interface is not and can not be
  605. frozen, that doesn't apply here.)
  606.  
  607.   Under Solaris, use `-K pic -xstrconst' if you compile with a Sun
  608. compiler, `-fpic' if you use GCC.  Also add `-L$(LIBDIR) -R$(LIBDIR)'
  609. to `LDFLAGS' when you link the binaries, so that the library can be
  610. found, and users do not have set `LD_LIBRARY_PATH'.
  611.  
  612.   (If you know how to make Kpathsea shared on other systems, please
  613. send a message to the bug address in the next section.)
  614.  
  615. 
  616. File: kpathsea.info,  Node: Reporting bugs,  Prev: Shared library,  Up: Installation
  617.  
  618. Reporting bugs
  619. ==============
  620.  
  621.   If you encounter problems, please report them to `tex-k@cs.umb.edu'.
  622. Include the version number of the library, the system you are using, and
  623. enough information to reproduce the bug in your report.  To get on this
  624. mailing list yourself, email `tex-k-request@cs.umb.edu' with a message
  625. whose body contains a line
  626.      subscribe YOU@YOUR.PREFERRED.ADDRESS
  627.  
  628.   To avoid wasted effort and time (both mine and yours), I strongly
  629. advise applying the principles given in the GNU C manual (*note
  630. Reporting Bugs: (gcc)Bugs.) to your bug reports.
  631.  
  632.   Please also report bugs in this documentation--not only factual
  633. errors, but unclear explanations, typos, wrong fonts, ...
  634.  
  635. 
  636. File: kpathsea.info,  Node: Debugging,  Next: Path searching,  Prev: Installation,  Up: Top
  637.  
  638. Debugging
  639. *********
  640.  
  641.   Kpathsea provides a number of runtime debugging options, detailed
  642. below by their names (and corresponding numeric values).  You can set
  643. these with some runtime argument (e.g., `-d') to the program; in that
  644. case, you should use the numeric values described in the program's
  645. documentation (which, except for Dviljk, are different from those
  646. below).
  647.  
  648.   You can also set the environment variable `KPATHSEA_DEBUG'.  In this
  649. case, you should use the numbers below.  Also use the numbers below if
  650. you run the program under a debugger and set the the variable
  651. `kpathsea_debug' yourself.
  652.  
  653.   In any case, you can *not* use the *names* below; you must always use
  654. somebody's numbers. (Sorry.)  And to set more than option, just sum the
  655. corresponding numbers.
  656.  
  657. `KPSE_DEBUG_STAT'
  658.      (1). Reports `stat'(2) calls. This is useful for verifying that
  659.      your directory structure is not forcing Kpathsea to do many
  660.      additional file tests (*note Slow path searching::. and *note
  661.      Subdirectory expansion::.). If you are using an up-to-date `ls-R'
  662.      database (*note Filename database::.), this should produce no
  663.      output unless a nonexistent file is searched for.
  664.  
  665. `KPSE_DEBUG_HASH'
  666.      (2). Reports lookups in all hash tables, including `ls-R' (*note
  667.      Filename database::.), font aliases (*note Fontmap::.), and config
  668.      file values (*note Config files::.).  Useful when expected values
  669.      are not being found, e.g.., file searches are looking at the disk
  670.      instead of using `ls-R'.
  671.  
  672. `KPSE_DEBUG_FOPEN'
  673.      (4). Reports file openings and closings. Especially useful when
  674.      your system's file table is full, for seeing if some files have
  675.      been opened but never closed. In case you want to set breakpoints:
  676.      this works by redefining `fopen' (`fclose') to be
  677.      `kpse_fopen_trace' (`kpse_fclose_trace').
  678.  
  679. `KPSE_DEBUG_PATHS'
  680.      (8). Reports general path information for each file type Kpathsea
  681.      is asked to search. This is useful when you are trying to track
  682.      down how a particular path got defined--from `texmf.cnf',
  683.      `config.ps', the compile-time default, an environment variable,
  684.      etc.  This is the contents of a structure defined in `tex-file.h'.
  685.  
  686. `KPSE_DEBUG_EXPAND'
  687.      (16). Reports the directory list corresponding to each path element
  688.      Kpathsea searches in. This is only relevant when Kpathsea is
  689.      searching the disk, since `ls-R' searches don't look through
  690.      directory lists in this way (they go straight to the file using
  691.      the hash table).
  692.  
  693. `KPSE_DEBUG_SEARCH'
  694.      (32). Reports on each file search Kpathsea attempts: the name of
  695.      the file searched for, the path searched in, whether or not the
  696.      file must exist (when drivers search for `cmr10.vf', it need not
  697.      exist), and whether or not we are collecting all occurrences of
  698.      the file in the path (as with, e.g., `texmf.cnf' and
  699.      `texfonts.map'), or just the first (as with most lookups).  This
  700.      can help you correlate what Kpathsea is doing with what is in your
  701.      input file.
  702.  
  703.   Debugging output from Kpathsea is always written to standard error,
  704. and begins with `kdebug:'. (Except for hash table buckets, which just
  705. start with the number.)
  706.  
  707. * Menu:
  708.  
  709. * Logging::            Recording successful searches.
  710.  
  711. 
  712. File: kpathsea.info,  Node: Logging,  Up: Debugging
  713.  
  714. Logging
  715. =======
  716.  
  717.   Kpathsea can record the time and filename found for each successful
  718. search. This may be useful in finding good candidates for deletion when
  719. your disk is full.
  720.  
  721.   To do this, define the environment or config file variable
  722. `TEXMFLOG'. The value is the name of the file to append the information
  723. to. The file is created if it doesn't exist.
  724.  
  725.   Each successful search turns into one line in the log file, with two
  726. words separated by a space. The first word is the time of the search, as
  727. the integer number of seconds since "the epoch", i.e., UTC midnight 1
  728. January 1970 (more precisely, the result of the `time' system call).
  729. The second word is the filename.
  730.  
  731.   For example, after `setenv TEXMFLOG /tmp/log', running Dvips on
  732. `story.dvi' appends the following lines:
  733.  
  734.      774455887 /usr/local/lib/texmf/dvips/config.ps
  735.      774455887 /usr/local/lib/texmf/dvips/psfonts.map
  736.      774455888 /usr/local/lib/texmf/dvips/texc.pro
  737.      774455888 /usr/local/lib/texmf/fonts/public/cm/pk/ljfour/cmbx10.600pk
  738.      774455889 /usr/local/lib/texmf/fonts/public/cm/pk/ljfour/cmsl10.600pk
  739.      774455889 /usr/local/lib/texmf/fonts/public/cm/pk/ljfour/cmr10.600pk
  740.      774455889 /usr/local/lib/texmf/dvips/texc.pro
  741.  
  742. Only filenames that are absolute are recorded, to preserve some
  743. semblance of privacy.
  744.  
  745. 
  746. File: kpathsea.info,  Node: Path searching,  Next: TeX searching,  Prev: Debugging,  Up: Top
  747.  
  748. Path searching
  749. **************
  750.  
  751.   This chapter describes the generic path searching mechanism Kpathsea
  752. provides. For information about searching for particular file types
  753. (e.g., TeX fonts), see the next chapter.
  754.  
  755. * Menu:
  756.  
  757. * Searching overview::        Basic scheme for searching.
  758. * Path sources::        Constructing the search path.
  759.  
  760. * Default expansion::           a: or :a or a::b expands to a default.
  761. * Variable expansion::          $foo and ${foo} expand to environment values.
  762. * Tilde expansion::             ~ and ~user expand to home directories.
  763. * Subdirectory expansion::    a// and a//b recursively expand to subdirs.
  764.  
  765. * Filename database::        Using an externally-built list to search.
  766.  
  767. 
  768. File: kpathsea.info,  Node: Searching overview,  Next: Path sources,  Up: Path searching
  769.  
  770. Searching overview
  771. ==================
  772.  
  773.   A "search path" is a colon-separated list of path elements, which are
  774. directory names with some extra frills. A search path can come from (a
  775. combination of) many sources; see below.  To look up a file `foo' along
  776. a path `.:/dir', Kpathsea checks each element of the path in turn:
  777. first `./foo', then `/dir/foo', (typically) returning the first one
  778. that exists.
  779.  
  780.   The "colon" and "slash" mentioned here aren't necessarily `:' and `/'
  781. on non-Unix systems. Kpathsea tries to adapt to other operating
  782. systems' conventions.
  783.  
  784.   To check a path element E, Kpathsea first sees if a prebuilt database
  785. (see below) applies to E, i.e., if the database is in a directory that
  786. is a prefix of E. If so, the path specification is matched against the
  787. contents of the database.
  788.  
  789.   If the database does not exist, or does not apply to this path
  790. element, contains no matches, the filesystem is searched. Kpathsea
  791. constructs the list of directories that correspond to this path
  792. element, and then checks in them for the file being searched for. (To
  793. help speed future lookups of files in the same directory, the directory
  794. in which a file is found is floated to the top of the directory list.)
  795.  
  796.   Each path element is checked in turn: first the database, then the
  797. disk. Once a match is found, the searching stops and the result is
  798. returned. This avoids possibly-expensive processing of path
  799. specifications that are never needed on a particular run.
  800.  
  801.   Although the simplest and most common path element is a directory
  802. name, Kpathsea supports additional features in search paths: layers of
  803. default values, environment variable names, config file values, users'
  804. home directories, and recursive subdirectory searching. Thus, we say
  805. that Kpathsea "expands" a path element, meaning getting rid of all the
  806. magic specifications and getting down to the basic directory name or
  807. names. This process is described in the sections below. It happens in
  808. the same order as the sections.
  809.  
  810.   Exception to the above: If the filename being searched for is absolute
  811. or explicitly relative, i.e., starts with `/' or `./' or `../',
  812. Kpathsea simply checks if that file exists; it is not looked for along
  813. any paths.
  814.  
  815. 
  816. File: kpathsea.info,  Node: Path sources,  Next: Default expansion,  Prev: Searching overview,  Up: Path searching
  817.  
  818. Path sources
  819. ============
  820.  
  821.   A search path can come from many sources.  In priority order (meaning
  822. Kpathsea will use whichever it finds first):
  823.  
  824.   1. A user-set environment variable, e.g., `TEXINPUTS'.
  825.  
  826.   2. A program-specific configuration file, e.g., an `S /a:/b' line in
  827.      Dvips' `config.ps'.
  828.  
  829.   3. A line in a Kpathsea configuration file `texmf.cnf', e.g.,
  830.      `TEXINPUTS=/c:/d'. See section below.
  831.  
  832.   4. The compile-time default (specified in `kpathsea/paths.h').
  833.  
  834.  
  835. In any case, once the path specification to use is determined, its
  836. evaluation is independent of its source.  These sources may also be
  837. combined via default expansion. See the next section.
  838.  
  839.   You can see each of these values for a given search path by using the
  840. debugging options of Kpathsea or your program. *Note Debugging::.
  841.  
  842. * Menu:
  843.  
  844. * Config files::        Kpathsea's runtime config files (texmf.cnf).
  845.  
  846. 
  847. File: kpathsea.info,  Node: Config files,  Up: Path sources
  848.  
  849. Config files
  850. ------------
  851.  
  852.   As mentioned above, Kpathsea reads "runtime configuration files"
  853. named `texmf.cnf' for search path definitions. The path used to search
  854. for them is constructed in the usual way, as described above (except
  855. that configuration files cannot be used to define the path, naturally;
  856. also, an `ls-R' database is not used to search for them, for technical
  857. reasons).
  858.  
  859.   The environment variable used is `TEXMFCNF'.
  860.  
  861.   Kpathsea reads *all* `texmf.cnf' files in the search path, not just
  862. the first one found; it uses the first definition of each variable
  863. encountered. Thus, with the (default) search path of `.:$TEXMF', values
  864. from `./texmf.cnf' override those from `$TEXMF/texmf.cnf'.
  865.  
  866.   Here is the format for `texmf.cnf' files:
  867.  
  868.    * Anything after a `%' or `#' is ignored; this is for comments.
  869.  
  870.    * Blank lines are ignored.
  871.  
  872.    * Each remaining nonblank line must look like
  873.  
  874.           VARIABLE [. PROGNAME] [=] VALUE
  875.  
  876.      where the `=' and surrounding whitespace is optional.
  877.  
  878.    * The VARIABLE name may contain any characters except whitespace,
  879.      `=', or `.' characters, but sticking to `A-Za-z_' is safest.
  880.  
  881.    * If the `.PROGNAME' is present, the definition only applies if the
  882.      program that is running is named (i.e., the last component of
  883.      `argv[0]') PROGNAME.  This allows (for example) different flavors
  884.      of TeX to have different search paths.
  885.  
  886.    * The VALUE may contain any characters except whitespace, `%', and
  887.      `@'.  (These restrictions are necessary because of the various
  888.      `sed' and other processing done on `texmf.cnf' at build time.)
  889.  
  890.    * All definitions are read before anything is expanded, so you can
  891.      use variables before they are defined (like `make', unlike most
  892.      everything else).
  893.  
  894. Here is the fragment from the distributed file illustrating most of
  895. these points:
  896.  
  897.      % TeX input files -- i.e., anything to be found by \input or \openin [...]
  898.      latex209_inputs = .:$TEXMF/tex/latex209//:$TEXMF/tex//
  899.      latex2e_inputs = .:$TEXMF/tex/latex2e//:$TEXMF/tex//
  900.      TEXINPUTS = .:$TEXMF/tex//
  901.      TEXINPUTS.latex209 = $latex209_inputs
  902.      TEXINPUTS.latex2e = $latex2e_inputs
  903.      TEXINPUTS.latex = $latex2e_inputs
  904.  
  905.   Although this format has obvious similarities to Bourne shell
  906. scripts--change the comment character to `#', disallow spaces around
  907. the `=', and get rid of the `.PROGRAM' convention, and it could be run
  908. through the shell. But there seemed little advantage to doing this,
  909. since all the information would have to passed back (with `echo''s,
  910. presumably) to Kpathsea and parsed there anyway, since the `sh' process
  911. couldn't affect its parent's environment.
  912.  
  913.   The implementation of all this is in `kpathsea/cnf.c'.
  914.  
  915. 
  916. File: kpathsea.info,  Node: Default expansion,  Next: Variable expansion,  Prev: Path sources,  Up: Path searching
  917.  
  918. Default expansion
  919. =================
  920.  
  921.   If the highest-priority search path (in the list in the previous
  922. section) contains an "extra colon" (i.e., leading, trailing, or
  923. doubled), Kpathsea inserts the next-highest-priority search path that is
  924. set at that point. If that search path has an extra colon, the same
  925. happens with the next-highest. (An extra colon in the compile-time
  926. default value has unpredictable results, and may cause the program to
  927. crash, so installers beware.)
  928.  
  929.   For example, given
  930.  
  931.      setenv TEXINPUTS /home/karl:
  932.  
  933. and a `TEXINPUTS' value from `texmf.cnf' of
  934.  
  935.      .:$TEXMF//tex
  936.  
  937. then the final value used for searching will be:
  938.  
  939.      /home/karl:.:$TEXMF//tex
  940.  
  941. You can trace this by debugging "paths" (*note Debugging::.).
  942.  
  943.   Minor technical point: Since it would be useless to insert the default
  944. value in more than one place, Kpathsea changes only one extra `:' and
  945. leaves any others in place (where they will eventually be effectively
  946. equivalent to `.', i.e., the current directory). It checks first for a
  947. leading `:', then a trailing `:', then a doubled `:'.
  948.  
  949. 
  950. File: kpathsea.info,  Node: Variable expansion,  Next: Tilde expansion,  Prev: Default expansion,  Up: Path searching
  951.  
  952. Variable expansion
  953. ==================
  954.  
  955.   `$foo' or `${foo}' in a path element is replaced by (1) the value of
  956. an environment variable `foo' (if it is set); (2) the value of `foo'
  957. from `texmf.cnf' (if any such exists); (3) the empty string.
  958.  
  959.   If the character after the `$' is alphanumeric or `_', the variable
  960. name consists of all consecutive such characters. If the character
  961. after the `$' is a `{', the variable name consists of everything up to
  962. the next `}' (braces are not balanced!).  Otherwise, Kpathsea gives a
  963. warning and ignores the `$' and its following character.
  964.  
  965.   Remember to quote the `$''s and braces as necessary for your shell.
  966.  
  967.   *Shell* variable values cannot be seen by Kpathsea.
  968.  
  969.   For example, given
  970.  
  971.      setenv TEXMF /home/tex
  972.      setenv TEXINPUTS .:$TEXMF:${TEXMF}new
  973.  
  974. the final `TEXINPUTS' path is the three directories:
  975.  
  976.      .:/home/tex:/home/texnew
  977.  
  978. You can trace this by debugging "paths" (*note Debugging::.).
  979.  
  980. 
  981. File: kpathsea.info,  Node: Tilde expansion,  Next: Subdirectory expansion,  Prev: Variable expansion,  Up: Path searching
  982.  
  983. Tilde expansion
  984. ===============
  985.  
  986.   A leading `~' or `~USER' in a path element is replaced by the current
  987. or USER's home directory, respectively.
  988.  
  989.   If USER is invalid, or the home directory cannot be determined,
  990. Kpathsea uses `.' instead.
  991.  
  992.   For example,
  993.  
  994.      setenv TEXINPUTS ~/mymacros:
  995.  
  996. will prepend a directory `mymacros' in your home directory to the
  997. default path.
  998.  
  999. 
  1000. File: kpathsea.info,  Node: Subdirectory expansion,  Next: Filename database,  Prev: Tilde expansion,  Up: Path searching
  1001.  
  1002. Subdirectory expansion
  1003. ======================
  1004.  
  1005.   A `//' in a path element following a directory D is replaced by all
  1006. subdirectories of D: first those subdirectories directly under D, then
  1007. the subsubdirectories under those, and so on.  At each level, the order
  1008. in which the directories are searched is unspecified. (It's "directory
  1009. order", and definitely not alphabetical.)
  1010.  
  1011.   If you specify any filename components after the `//', only
  1012. subdirectories which contain those components are included.  For
  1013. example, `/a//b' would expand into directories `/a/1/b', `/a/2/b',
  1014. `/a/1/1/b', and so on, but not `/a/b/c' or `/a/1'.
  1015.  
  1016.   I should mention one related implementation trick, which I stole from
  1017. GNU find.  Matthew Farwell `<dylan@ibmpcug.co.uk>' suggested it, and
  1018. David MacKenzie `<djm@gnu.ai.mit.edu>' implemented it (as far as I
  1019. know).
  1020.  
  1021.   The trick is that in every real Unix implementation (as opposed to the
  1022. POSIX specification), a directory which contains no subdirectories will
  1023. have exactly two links (namely, one for `.' and one for `..').  That is
  1024. to say, the `st_nlink' field in the `stat' structure will be two.
  1025. Thus, we don't have to stat everything in the bottom-level (leaf)
  1026. directories--we can just check `st_nlink', notice it's two, and do no
  1027. more work.
  1028.  
  1029.   But if you have a directory that contains *one* subdirectory and five
  1030. hundred files, `st_nlink' will be 3, and Kpathsea has to stat every one
  1031. of those 501 entries.  Therein lies slowness.
  1032.  
  1033.   You can disable the trick by undefining `UNIX_ST_LINK' in
  1034. `kpathsea/config.h'. (It is undefined by default except under Unix.)
  1035.  
  1036.   Unfortunately, in some cases files in leaf directories are `stat''d:
  1037. if the path specification is, say, `$TEXMF/fonts//pk//', then files in
  1038. a subdirectory `.../pk', even if it is a leaf, are checked. The reason
  1039. cannot be explained without reference to the implementation, so read
  1040. `kpathsea/elt-dirs.c' (search for `may descend') if you are curious.
  1041. (And if you can find a way to *solve* the problem, please let me know.)
  1042.  
  1043. 
  1044. File: kpathsea.info,  Node: Filename database,  Prev: Subdirectory expansion,  Up: Path searching
  1045.  
  1046. Filename database (`ls-R')
  1047. ==========================
  1048.  
  1049.   Kpathsea goes to some lengths to minimize disk accesses for searches
  1050. (*note Subdirectory expansion::.).  Nevertheless, at installations with
  1051. enough directories, doing a linear search of each possible directory for
  1052. a given file can take an excessively long time ("excessive" depending
  1053. on the speed of the disk, whether it's NFS-mounted, how patient you are,
  1054. etc.). In practice, the union of font directories from the Dvips(k) and
  1055. Dviljk distributions is large enough for searching to be noticeably slow
  1056. on typical machines these days.
  1057.  
  1058.   Therefore, Kpathsea can use an externally-built "database" that maps
  1059. files to directories, thus avoiding the need to exhaustively search the
  1060. disk.  By fiat, you must name the file `ls-R', and put it at the root
  1061. of the TeX installation hierarchy (`$TEXMF' by default).  Kpathsea does
  1062. variable expansion on the `$TEXMF', naturally, so you can use different
  1063. `ls-R''s for different trees, if you are testing new ones.  However,
  1064. one and only one `ls-R' is read; it is not searched for along any paths.
  1065.  
  1066.   You can build `ls-R' with the command
  1067.      ls -R /YOUR/ROOT/DIR >ls-R
  1068.    if your `ls' produces the right output format (see the section
  1069. below). GNU `ls', for example, outputs in this format.  It is probably
  1070. best to do this via `cron', so changes in the installed files will be
  1071. automatically reflected (albeit with some delay) in the database.
  1072.  
  1073. If your system uses symbolic links, the command `ls -LR' will be more
  1074. reliable than plain `ls -R'.  The former follows the symbolic links to
  1075. the real files, which is what Kpathsea needs.
  1076.  
  1077.   Kpathsea warns you if it finds an `ls-R' file, but the file does not
  1078. contain any usable entries. The usual culprit is using just `ls -R' to
  1079. generate the `ls-R' file instead of `ls -R /YOUR/DIR'.  Kpathsea looks
  1080. for lines starting with `/', to improve reliability with unusual
  1081. filenames (specifically, those ending with a `:').
  1082.  
  1083.   Because the database may be out-of-date for a particular run (e.g.,
  1084. if a font was just built with `MakeTeXPK'), if a file is not found in
  1085. the database, by default Kpathsea goes ahead and searches the disk. If a
  1086. particular path element begins with `!!', however, *only* the database
  1087. will be searched for that element, never the disk. If the database does
  1088. not exist, nothing will be searched. Because this can greatly surprise
  1089. users ("I see the font `foo.tfm' when I do an `ls'; why can't Dvips
  1090. find it?"), I do not recommend using this feature.
  1091.  
  1092. * Menu:
  1093.  
  1094. * Database format::        Syntax details of the database file.
  1095.  
  1096. 
  1097. File: kpathsea.info,  Node: Database format,  Up: Filename database
  1098.  
  1099. Database format
  1100. ---------------
  1101.  
  1102.   The "database" read by Kpathsea is a line-oriented file of plain
  1103. text. The format is that generated by GNU (and perhaps other) `ls'
  1104. programs given the `-R' option, as follows.
  1105.  
  1106.    * Blank lines are ignored.
  1107.  
  1108.    * If a line begins with `/' and ends with a colon, it's the name of a
  1109.      directory.
  1110.  
  1111.    * All other lines name entries in the most recently seen directory.
  1112.      `/''s in such lines will produce possibly-strange results.
  1113.  
  1114.    * Files with no preceding directory line are ignored.
  1115.  
  1116.   For example, here's the first few lines of `ls-R' on my system:
  1117.  
  1118.      bibtex
  1119.      dvips
  1120.      fonts
  1121.      ini
  1122.      ls-R
  1123.      mf
  1124.      tex
  1125.      
  1126.      /usr/local/lib/texmf/bibtex:
  1127.      bib
  1128.      bst
  1129.      doc
  1130.      
  1131.      /usr/local/lib/texmf/bibtex/bib:
  1132.      asi.bib
  1133.      bibshare
  1134.      btxdoc.bib
  1135.  
  1136. On my system, `ls-R' is about 30K bytes.
  1137.  
  1138. 
  1139. File: kpathsea.info,  Node: TeX searching,  Next: TeX directory structure,  Prev: Path searching,  Up: Top
  1140.  
  1141. TeX searching
  1142. *************
  1143.  
  1144.   Although the basic features in Kpathsea can be used for any type of
  1145. path searching, it came about (like all libraries) with a specific
  1146. application in mind: I wrote Kpathsea specifically for TeX system
  1147. programs.  I had been struggling with the programs I was using (Dvips,
  1148. Xdvi, and TeX itself) having slightly different notions of how to
  1149. specify paths; and debugging was painful, since no code was shared.
  1150.  
  1151.   Therefore, Kpathsea provides some TeX-specific features.  Indeed,
  1152. many of the supposedly generic path searching features were provided
  1153. because they seemed useful in that conTeXt (font lookup, particularly).
  1154.  
  1155. * Menu:
  1156.  
  1157. * Envvars: TeX environment variables.    Overriding compiled-in paths.
  1158. * Glyph lookup::            Searching for bitmap fonts.
  1159.  
  1160. 
  1161. File: kpathsea.info,  Node: TeX environment variables,  Next: Glyph lookup,  Up: TeX searching
  1162.  
  1163. TeX environment variables
  1164. =========================
  1165.  
  1166.   Kpathsea defines a sequence of environment variables to search for
  1167. each file type it supports.  This makes it easy for different programs
  1168. to check the same environment variables, in the same order.
  1169.  
  1170.   The following table lists the environment variables searched for each
  1171. file type in the order they are searched (and a brief description of the
  1172. file type).  That is, only if the first variable is unset is the second
  1173. variable checked, and so on.  If none are set, various other things are
  1174. checked; *note Path sources::..
  1175.  
  1176. `.base'
  1177.      (Metafont memory dump) `MFBASES'
  1178.  
  1179. `.bib'
  1180.      (BibTeX bibliography source) `BIBINPUTS'
  1181.  
  1182. `.bst'
  1183.      (BibTeX style file) `BSTINPUTS', `TEXINPUTS'
  1184.  
  1185. `.cnf'
  1186.      (Kpathsea runtime configuration files) `TEXMFCNF'
  1187.  
  1188. `.eps'
  1189.      (Encapsulated PostScript figures) `TEXPICTS', `TEXINPUTS'
  1190.  
  1191. `.fmt'
  1192.      (TeX memory dump) `TEXFORMATS'
  1193.  
  1194. `gf'
  1195.      (generic font bitmap) `PROGRAMFONTS', `GFFONTS', `GLYPHFONTS',
  1196.      `TEXFONTS'
  1197.  
  1198. `.mf'
  1199.      (Metafont source) `MFINPUTS'
  1200.  
  1201. `mf.pool'
  1202.      (Metafont program strings) `MFPOOL'
  1203.  
  1204. `.pict'
  1205.      (Other kinds of figures) Same as `.eps'.
  1206.  
  1207. `pk'
  1208.      (packed bitmap font) `PROGRAMFONTS', `PKFONTS', `TEXPKS',
  1209.      `GLYPHFONTS', `TEXFONTS'
  1210.  
  1211. `.tex'
  1212.      (TeX source) `TEXINPUTS'
  1213.  
  1214. `tex.pool'
  1215.      (TeX program strings) `TEXPOOL'
  1216.  
  1217. `.tfm'
  1218.      (TeX font metrics) `TFMFONTS', `TEXFONTS'
  1219.  
  1220. `.vf'
  1221.      (virtual font) `VFFONTS', `TEXFONTS'
  1222.  
  1223.   For the font variables, the intent is that:
  1224.  
  1225.   1. `TEXFONTS' is the default for everything.
  1226.  
  1227.   2. `GLYPHFONTS' is the default for bitmap (or, more precisely,
  1228.      non-metric) files.
  1229.  
  1230.   3. Each format has its own variable.
  1231.  
  1232.   4. Each program can and should have its own font override path as
  1233.      well; e.g., `DVIPSFONTS' for Dvipsk. Again, this is for bitmaps,
  1234.      not metrics.
  1235.  
  1236.  
  1237.   If these environment variables are set, the corresponding `texmf.cnf'
  1238. definition won't be looked at (unless, as usual, the environment
  1239. variable has an extra `:'). *Note Default expansion::.
  1240.  
  1241. 
  1242. File: kpathsea.info,  Node: Glyph lookup,  Prev: TeX environment variables,  Up: TeX searching
  1243.  
  1244. Glyph lookup
  1245. ============
  1246.  
  1247.   Kpathsea provides a routine (`kpse_find_glyph_format' in
  1248. `kpathsea/tex-glyph.c') which searches for a bitmap font in GF or PK
  1249. format (or either) given a font name (e.g., `cmr10') and a resolution
  1250. (e.g., 300).
  1251.  
  1252.   The search is based solely on filenames, not file contents--if a PK
  1253. file is named `cmr10.300gf', it will be found as a GF file.
  1254.  
  1255.   Here is an outline of the search strategy (details in the sections
  1256. below) for a file NAME at resolution DPI.  The search stops at the
  1257. first successful lookup.
  1258.  
  1259.   1. Look for an existing file NAME.DPI in the specified format(s).
  1260.  
  1261.   2. If NAME is an alias for a file F in the fontmap file
  1262.      `texfonts.map', look for F.DPI.
  1263.  
  1264.   3. Run an external script (typically named `MakeTeXPK') to generate
  1265.      the font.
  1266.  
  1267.   4. Look for FALLBACK.DPI, where FALLBACK is some last-resort font
  1268.      (typically `cmr10').
  1269.  
  1270.  
  1271. * Menu:
  1272.  
  1273. * Basic glyph lookup::        Features common to all glyph lookups.
  1274. * Fontmap::            Aliases for fonts.
  1275. * MakeTeX... scripts::        Creating files on the fly.
  1276. * Fallback font::        Resolutions and fonts of last resort.
  1277.  
  1278.