home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / texlatex.zip / web2c72.zip / info / kpathsea.info-3 (.txt) < prev    next >
GNU Info File  |  1998-04-11  |  41KB  |  798 lines
  1. This is Info file kpathsea.info, produced by Makeinfo version 1.68 from
  2. the input file kpathsea.texi.
  3. INFO-DIR-SECTION TeX
  4. START-INFO-DIR-ENTRY
  5. * Kpathsea: (kpathsea).                       File lookup along search paths.
  6. * kpsewhich: (kpathsea)Invoking kpsewhich.    TeX file searching.
  7. * mktexmf: (kpathsea)mktex scripts.           MF source generation.
  8. * mktexpk: (kpathsea)mktex scripts.           PK bitmap generation.
  9. * mktextex: (kpathsea)mktex scripts.          TeX source generation.
  10. * mktextfm: (kpathsea)mktex scripts.          TeX font metric generation.
  11. * mktexlsr: (kpathsea)Filename database.      Update ls-R.
  12. END-INFO-DIR-ENTRY
  13.   This file documents the Kpathsea library for path searching.
  14.   Copyright (C) 1993, 94, 95, 96, 97 K. Berry & O. Weber.
  15.   Permission is granted to make and distribute verbatim copies of this
  16. manual provided the copyright notice and this permission notice are
  17. preserved on all copies.
  18.   Permission is granted to copy and distribute modified versions of this
  19. manual under the conditions for verbatim copying, provided that the
  20. entire resulting derived work is distributed under the terms of a
  21. permission notice identical to this one.
  22.   Permission is granted to copy and distribute translations of this
  23. manual into another language, under the above conditions for modified
  24. versions, except that this permission notice may be stated in a
  25. translation approved by the Free Software Foundation.
  26. File: kpathsea.info,  Node: Subdirectory expansion,  Prev: KPSE_DOT expansion,  Up: Path expansion
  27. Subdirectory expansion
  28. ----------------------
  29.   Two or more consecutive slashes in a path element following a
  30. directory D is replaced by all subdirectories of D: first those
  31. subdirectories directly under D, then the subsubdirectories under
  32. those, and so on.  At each level, the order in which the directories are
  33. searched is unspecified.  (It's "directory order", and definitely not
  34. alphabetical.)
  35.   If you specify any filename components after the `//', only
  36. subdirectories which match those components are included.  For example,
  37. `/a//b' would expand into directories `/a/1/b', `/a/2/b', `/a/1/1/b',
  38. and so on, but not `/a/b/c' or `/a/1'.
  39.   You can include multiple `//' constructs in the path.
  40.   `//' at the beginning of a path is ignored; you didn't really want to
  41. search every directory on the system, did you?
  42.   I should mention one related implementation trick, which I took from
  43. GNU find.  Matthew Farwell suggested it, and David MacKenzie
  44. implemented it.
  45.   The trick is that in every real Unix implementation (as opposed to the
  46. POSIX specification), a directory which contains no subdirectories will
  47. have exactly two links (namely, one for `.' and one for `..').  That is
  48. to say, the `st_nlink' field in the `stat' structure will be two.
  49. Thus, we don't have to stat everything in the bottom-level (leaf)
  50. directories--we can just check `st_nlink', notice it's two, and do no
  51. more work.
  52.   But if you have a directory that contains a single subdirectory and
  53. 500 regular files, `st_nlink' will be 3, and Kpathsea has to stat every
  54. one of those 501 entries.  Therein lies slowness.
  55.   You can disable the trick by undefining `UNIX_ST_LINK' in
  56. `kpathsea/config.h'. (It is undefined by default except under Unix.)
  57.   Unfortunately, in some cases files in leaf directories are `stat''d:
  58. if the path specification is, say, `$TEXMF/fonts//pk//', then files in
  59. a subdirectory `.../pk', even if it is a leaf, are checked. The reason
  60. cannot be explained without reference to the implementation, so read
  61. `kpathsea/elt-dirs.c' (search for `may descend') if you are curious.
  62. And if you can find a way to *solve* the problem, please let me know.
  63.   Subdirectory expansion is implemented in the source file
  64. `kpathsea/elt-dirs.c'.
  65. File: kpathsea.info,  Node: Filename database,  Next: Invoking kpsewhich,  Prev: Path expansion,  Up: Path searching
  66. Filename database (`ls-R')
  67. ==========================
  68.   Kpathsea goes to some lengths to minimize disk accesses for searches
  69. (*note Subdirectory expansion::.).  Nevertheless, at installations with
  70. enough directories, searching each possible directory for a given file
  71. can take an excessively long time (depending on the speed of the disk,
  72. whether it's NFS-mounted, how patient you are, etc.).
  73.   In practice, a font tree containing the standard PostScript and PCL
  74. fonts is large enough for searching to be noticeably slow on typical
  75. systems these days.  Therefore, Kpathsea can use an externally-built
  76. "database" file named `ls-R' that maps files to directories, thus
  77. avoiding the need to exhaustively search the disk.
  78.   A second database file `aliases' allows you to give additional names
  79. to the files listed in `ls-R'.  This can be helpful to adapt to "8.3"
  80. filename conventions in source files.
  81.   The `ls-R' and `aliases' features are implemented in the source file
  82. `kpathsea/db.c'.
  83. * Menu:
  84. * ls-R::                        The main filename database.
  85. * Filename aliases::            Aliases for those names.
  86. * Database format::             Syntax details of the database file.
  87. File: kpathsea.info,  Node: ls-R,  Next: Filename aliases,  Up: Filename database
  88. `ls-R'
  89. ------
  90.   As mentioned above, you must name the main filename database `ls-R'.
  91. You can put one at the root of each TeX installation hierarchy you wish
  92. to search (`$TEXMF' by default); most sites have only one hierarchy.
  93. Kpathsea looks for `ls-R' files along the `TEXMFDBS' path, so that
  94. should presumably match the list of hierarchies.
  95.   The recommended way to create and maintain `ls-R' is to run the
  96. `mktexlsr' script, which is installed in `$(bindir)' (`/usr/local/bin'
  97. by default).  That script goes to some trouble to follow symbolic links
  98. as necessary, etc.  It's also invoked by the distributed `mktex...'
  99. scripts.
  100.   At its simplest, though, you can build `ls-R' with the command
  101.      cd /YOUR/TEXMF/ROOT && ls -LAR ./ >ls-R
  102. presuming your `ls' produces the right output format (see the section
  103. below).  GNU `ls', for example, outputs in this format.  Also presuming
  104. your `ls' hasn't been aliased in a system file (e.g., `/etc/profile')
  105. to something problematic, e.g., `ls --color=tty'.  In that case, you
  106. will have to disable the alias before generating `ls-R'.  For the
  107. precise definition of the file format, see *Note Database format::.
  108.   Regardless of whether you use the supplied script or your own, you
  109. will almost certainly want to invoke it via `cron', so when you make
  110. changes in the installed files (say if you install a new LaTeX
  111. package), `ls-R' will be automatically updated.
  112.   The `-A' option to `ls' includes files beginning with `.'  (except
  113. for `.' and `..'), such as the file `.tex' included with the LaTeX
  114. tools package.  (On the other hand, *directories* whose names begin
  115. with `.' are always ignored.)
  116.   If your system does not support symbolic links, omit the `-L'.
  117.   `ls -LAR /YOUR/TEXMF/ROOT' will also work.  But using `./' avoids
  118. embedding absolute pathnames, so the hierarchy can be easily
  119. transported.  It also avoids possible trouble with automounters or
  120. other network filesystem conventions.
  121.   Kpathsea warns you if it finds an `ls-R' file, but the file does not
  122. contain any usable entries.  The usual culprit is running plain `ls -R'
  123. instead of `ls -LR ./' or `ls -R /YOUR/TEXMF/ROOT'.  Another
  124. possibility is some system directory name starting with a `.' (perhaps
  125. if you are using AFS); Kpathsea ignores everything under such
  126. directories.
  127.   Because the database may be out-of-date for a particular run, if a
  128. file is not found in the database, by default Kpathsea goes ahead and
  129. searches the disk. If a particular path element begins with `!!',
  130. however, *only* the database will be searched for that element, never
  131. the disk.  If the database does not exist, nothing will be searched.
  132. Because this can surprise users ("I see the font `foo.tfm' when I do an
  133. `ls'; why can't Dvips find it?"), it is not in any of the default
  134. search paths.
  135. File: kpathsea.info,  Node: Filename aliases,  Next: Database format,  Prev: ls-R,  Up: Filename database
  136. Filename aliases
  137. ----------------
  138.   In some circumstances, you may wish to find a file under several
  139. names.  For example, suppose a TeX document was created using a DOS
  140. system and tries to read `longtabl.sty'.  But now it's being run on a
  141. Unix system, and the file has its original name, `longtable.sty'.  The
  142. file won't be found.  You need to give the actual file `longtable.sty'
  143. an alias `longtabl.sty'.
  144.   You can handle this by creating a file `aliases' as a companion to
  145. the `ls-R' for the hierarchy containing the file in question.  (You
  146. must have an `ls-R' for the alias feature to work.)
  147.   The format of `aliases' is simple: two whitespace-separated words per
  148. line; the first is the real name `longtable.sty', and second is the
  149. alias (`longtabl.sty').  These must be base filenames, with no
  150. directory components.  `longtable.sty' must be in the sibling `ls-R'.
  151.   Also, blank lines and lines starting with `%' or `#' are ignored in
  152. `aliases', to allow for comments.
  153.   If a real file `longtabl.sty' exists, it is used regardless of any
  154. aliases.
  155. File: kpathsea.info,  Node: Database format,  Prev: Filename aliases,  Up: Filename database
  156. Database format
  157. ---------------
  158.   The "database" read by Kpathsea is a line-oriented file of plain
  159. text. The format is that generated by GNU (and most other) `ls'
  160. programs given the `-R' option, as follows.
  161.    * Blank lines are ignored.
  162.    * If a line begins with `/' or `./' or `../' and ends with a colon,
  163.      it's the name of a directory.  (`../' lines aren't useful,
  164.      however, and should not be generated.)
  165.    * All other lines define entries in the most recently seen directory.
  166.      /'s in such lines will produce possibly-strange results.
  167.    * Files with no preceding directory line are ignored.
  168.   For example, here's the first few lines of `ls-R' (which totals about
  169. 30K bytes) on my system:
  170.      bibtex
  171.      dvips
  172.      fonts
  173.      ls-R
  174.      metafont
  175.      metapost
  176.      tex
  177.      web2c
  178.      
  179.      ./bibtex:
  180.      bib
  181.      bst
  182.      doc
  183.      
  184.      ./bibtex/bib:
  185.      asi.bib
  186.      btxdoc.bib
  187.      ...
  188. File: kpathsea.info,  Node: Invoking kpsewhich,  Prev: Filename database,  Up: Path searching
  189. `kpsewhich': Standalone path searching
  190. ======================================
  191.   The Kpsewhich program exercises the path searching functionality
  192. independent of any particular application.  This can also be useful as a
  193. sort of `find' program to locate files in your TeX hierarchies, perhaps
  194. in administrative scripts.  It is used heavily in the distributed
  195. `mktex...' scripts.
  196.   Synopsis:
  197.      kpsewhich OPTION... FILENAME...
  198.   The options and filename(s) to look up can be intermixed.  Options
  199. can start with either `-' or `--', and any unambiguous abbreviation is
  200. accepted.
  201. * Menu:
  202. * Path searching options::      Changing the mode, resolution, etc.
  203. * Auxiliary tasks::             Path and variable expansion.
  204. * Standard options::            -help and -version.
  205. File: kpathsea.info,  Node: Path searching options,  Next: Auxiliary tasks,  Up: Invoking kpsewhich
  206. Path searching options
  207. ----------------------
  208.   Kpsewhich looks up each non-option argument on the command line as a
  209. filename, and returns the first file found.  There is no option to
  210. return all the files with a particular name (you can run the Unix
  211. `find' utility for that, *note Invoking find: (findutils)Invoking
  212. find.).
  213.   Various options alter the path searching behavior:
  214. `--dpi=NUM'
  215.      Set the resolution to NUM; this only affects `gf' and `pk'
  216.      lookups.  `-D' is a synonym, for compatibility with Dvips.
  217.      Default is 600.
  218. `--format=NAME'
  219.      Set the format for lookup to NAME.  By default, the format is
  220.      guessed from the filename, with `tex' being used if nothing else
  221.      fits.  The recognized filename extensions (including any leading
  222.      `.') are also allowable NAMEs.
  223.      All formats also have a name, which is the only way to specify
  224.      formats with no associated suffix.  For example, for Dvips
  225.      configuration files you can use `--format="dvips config"'.  (The
  226.      quotes are for the sake of the shell.)
  227.      Here's the current list of recognized names and the associated
  228.      suffixes.  *Note Supported file formats::, for more information on
  229.      each of these.
  230.           gf: gf
  231.           pk: pk
  232.           bitmap font
  233.           afm: .afm
  234.           base: .base
  235.           bib: .bib
  236.           bst: .bst
  237.           cnf: .cnf
  238.           ls-R: ls-R
  239.           fmt: .fmt
  240.           map: .map
  241.           mem: .mem
  242.           mf: .mf
  243.           mfpool: .pool
  244.           mft: .mft
  245.           mp: .mp
  246.           mppool: .pool
  247.           MetaPost support
  248.           ocp: .ocp
  249.           ofm: .ofm .tfm
  250.           opl: .opl
  251.           otp: .otp
  252.           ovf: .ovf
  253.           ovp: .ovp
  254.           graphic/figure: .eps .epsi
  255.           tex: .tex
  256.           TeX system documentation
  257.           texpool: .pool
  258.           TeX system sources
  259.           PostScript header/font: .pro
  260.           Troff fonts
  261.           tfm: .tfm
  262.           type1 fonts: .pfa .pfb
  263.           vf: .vf
  264.           dvips config
  265.           ist: .ist
  266.           truetype fonts: .ttf .ttc
  267.           type42 fonts
  268.           web2c files
  269.           other text files
  270.           other binary files
  271.      This option and `--path' are mutually exclusive.
  272. `--interactive'
  273.      After processing the command line, read additional filenames to
  274.      look up from standard input.
  275. `-mktex=FILETYPE'
  276. `-no-mktex=FILETYPE'
  277.      Turn on or off the `mktex' script associated with FILETYPE.  The
  278.      only values that make sense for FILETYPE are `pk', `mf', `tex',
  279.      and `tfm'. By default, all are off in Kpsewhich.  *Note mktex
  280.      scripts::.
  281. `--mode=STRING'
  282.      Set the mode name to STRING; this also only affects `gf' and `pk'
  283.      lookups.  No default: any mode will be found.  *Note mktex script
  284.      arguments::.
  285. `--must-exist'
  286.      Do everything possible to find the files, notably including
  287.      searching the disk.  By default, only the `ls-R' database is
  288.      checked, in the interest of efficiency.
  289. `--path=STRING'
  290.      Search along the path STRING (colon-separated as usual), instead
  291.      of guessing the search path from the filename.  `//' and all the
  292.      usual expansions are supported (*note Path expansion::.).  This
  293.      option and `--format' are mutually exclusive.  To output the
  294.      complete directory expansion of a path, instead of doing a
  295.      one-shot lookup, see `--expand-path' in the following section.
  296. `--progname=NAME'
  297.      Set the program name to NAME; default is `kpsewhich'.  This can
  298.      affect the search paths via the `.PROGNAM' feature in
  299.      configuration files (*note Config files::.).
  300. File: kpathsea.info,  Node: Auxiliary tasks,  Next: Standard options,  Prev: Path searching options,  Up: Invoking kpsewhich
  301. Auxiliary tasks
  302. ---------------
  303.   Kpsewhich provides some additional features not strictly related to
  304. path lookup:
  305.    * `--debug=NUM' sets the debugging options to NUM.  *Note
  306.      Debugging::.
  307.    * `--expand-braces=STRING' outputs the variable and brace expansion
  308.      of STRING.  *Note Path expansion::.
  309.    * `--expand-var=STRING' outputs the variable expansion of STRING.
  310.      For example, the `mktex...' scripts run `kpsewhich
  311.      --expand-var='$TEXMF'' to find the root of the TeX system
  312.      hierarchy.  *Note Path expansion::.
  313.    * `--expand-path=STRING' outputs the complete expansion of STRING as
  314.      a colon-separated path.  This is useful to construct a search path
  315.      for a program that doesn't accept recursive subdirectory
  316.      specifications.
  317.      For one-shot uses of an arbitrary (not built in to Kpathsea) path,
  318.      see `--path' in the previous section.
  319.    * `--show-path=NAME' shows the path that would be used for file
  320.      lookups of file type NAME.  Either a filename extension (`pk',
  321.      `.vf', etc.) or an integer can be used, just as with `--format',
  322.      described in the previous section.
  323. File: kpathsea.info,  Node: Standard options,  Prev: Auxiliary tasks,  Up: Invoking kpsewhich
  324. Standard options
  325. ----------------
  326.   Kpsewhich accepts the standard GNU options:
  327.    * `--help' prints a help message on standard output and exits.
  328.    * `--version' prints the Kpathsea version number and exits.
  329. File: kpathsea.info,  Node: TeX support,  Next: Programming,  Prev: Path searching,  Up: Top
  330. TeX support
  331. ***********
  332.   Although the basic features in Kpathsea can be used for any type of
  333. path searching, it came about (like all libraries) with a specific
  334. application in mind: I wrote Kpathsea specifically for TeX system
  335. programs.  I had been struggling with the programs I was using (Dvips,
  336. Xdvi, and TeX itself) having slightly different notions of how to
  337. specify paths; and debugging was painful, since no code was shared.
  338.   Therefore, Kpathsea provides some TeX-specific formats and features.
  339. Indeed, many of the supposedly generic path searching features were
  340. provided because they seemed useful in that conTeXt (font lookup,
  341. particularly).
  342.   Kpathsea provides a standard way to search for files of any of the
  343. supported file types; glyph fonts are a bit different than all the rest.
  344. Searches are based solely on filenames, not file contents--if a GF file
  345. is named `cmr10.600pk', it will be found as a PK file.
  346. * Menu:
  347. * Supported file formats::      File types Kpathsea knows about.
  348. * File lookup::                 Searching for most kinds of files.
  349. * Glyph lookup::                Searching for bitmap fonts.
  350. * Suppressing warnings::        Avoiding warnings via TEX_HUSH.
  351. File: kpathsea.info,  Node: Supported file formats,  Next: File lookup,  Up: TeX support
  352. Supported file formats
  353. ======================
  354.   Kpathsea has support for a number of file types.  Each file type has a
  355. list of environment and config file variables that are checked to define
  356. the search path, and most have a default suffix that plays a role in
  357. finding files (see the next section).  Some also define additional
  358. suffixes, and/or a program to be run to create missing files on the fly.
  359.   Since environment variables containing periods, such as
  360. `TEXINPUTS.latex', are not allowed on some systems, Kpathsea looks for
  361. environment variables with an underscore, e.g., `TEXINPUTS_latex'
  362. (*note Config files::.).
  363.   The following table lists the above information.
  364. `afm'
  365.      (Adobe font metrics, *note Metric files: (dvips)Metric files.)
  366.      `AFMFONTS'; suffix `.afm'.
  367. `base'
  368.      (Metafont memory dump, *note Memory dumps: (web2c)Memory dumps.)
  369.      `MFBASES', `TEXMFINI'; suffix `.base'.
  370. `bib'
  371.      (BibTeX bibliography source, *note bibtex invocation:
  372.      (web2c)bibtex invocation.)  `BIBINPUTS', `TEXBIB'; suffix `.bib'.
  373. `bst'
  374.      (BibTeX style file, *note Basic BibTeX style files: (web2c)Basic
  375.      BibTeX style files.)  `BSTINPUTS'; suffix `.bst'.
  376. `cnf'
  377.      (Runtime configuration files, *note Config files::.)  `TEXMFCNF';
  378.      suffix `.cnf'.
  379. `dvips config'
  380.      (Dvips `config.*' files, such as `config.ps', *note Config files:
  381.      (dvips)Config files.)  `TEXCONFIG'.
  382. `fmt'
  383.      (TeX memory dump, *note Memory dumps: (web2c)Memory dumps.)
  384.      `TEXFORMATS', `TEXMFINI'; suffix `.fmt'.
  385.      (generic font bitmap, *note Glyph files: (dvips)Glyph files.)
  386.      `PROGRAMFONTS', `GFFONTS', `GLYPHFONTS', `TEXFONTS'; suffix `gf'.
  387. `graphic/figure'
  388.      (Encapsulated PostScript figures, *note PostScript figures:
  389.      (dvips)PostScript figures.)  `TEXPICTS', `TEXINPUTS'; additional
  390.      suffixes: `.eps', `.epsi'.
  391. `ist'
  392.      (makeindex style files) `TEXINDEXSTYLE', `INDEXSTYLE'; suffix
  393.      `.ist'.
  394. `ls-R'
  395.      (Filename databases, *note Filename database::.)  `TEXMFDBS'.
  396. `map'
  397.      (Fontmaps, *note Fontmap::.)  `TEXFONTMAPS'; suffix `.map'.
  398. `mem'
  399.      (MetaPost memory dump, *note Memory dumps: (web2c)Memory dumps.)
  400.      `MPMEMS', `TEXMFINI'; suffix `.mem'.
  401. `MetaPost support'
  402.      (MetaPost support files, used by DMP; *note dmp invocation:
  403.      (web2c)dmp invocation.)  `MPSUPPORT'.
  404.      (Metafont source, *note mf invocation: (web2c)mf invocation.)
  405.      `MFINPUTS'; suffix `.mf'; dynamic creation program: `mktexmf'.
  406. `mfpool'
  407.      (Metafont program strings, *note pooltype invocation:
  408.      (web2c)pooltype invocation.)  `MFPOOL', `TEXMFINI'; suffix `.pool'.
  409. `mft'
  410.      (`MFT' style file, *note mft invocation: (web2c)mft invocation.)
  411.      `MFTINPUTS'; suffix `.mft'.
  412.      (MetaPost source, *note mpost invocation: (web2c)mpost invocation.)
  413.      `MPINPUTS'; suffix `.mp'.
  414. `mppool'
  415.      (MetaPost program strings, *note pooltype invocation:
  416.      (web2c)pooltype invocation.)  `MPPOOL', `TEXMFINI'; suffix `.pool'.
  417. `ocp'
  418.      (Omega compiled process files) `OCPINPUTS';
  419.      suffix `.ocp'; dynamic creation program: `MakeOmegaOCP'.
  420. `ofm'
  421.      (Omega font metrics) `OFMFONTS', `TEXFONTS';
  422.      suffixes `.ofm', `.tfm'; dynamic creation program: `MakeOmegaOFM'.
  423. `opl'
  424.      (Omega property lists) `OPLFONTS', `TEXFONTS'; suffix `.opl'.
  425. `otp'
  426.      (Omega translation process files) `OTPINPUTS'; suffix `.otp'.
  427. `ovf'
  428.      (Omega virtual fonts) `OVFFONTS', `TEXFONTS'; suffix `.ovf'.
  429. `ovp'
  430.      (Omega virtual property lists) `OVPFONTS', `TEXFONTS'; suffix
  431.      `.ovp'.
  432.      (packed bitmap fonts, *note Glyph files: (dvips)Glyph files.)
  433.      `PROGRAMFONTS' (PROGRAM being `XDVI', etc.), `PKFONTS', `TEXPKS',
  434.      `GLYPHFONTS', `TEXFONTS'; suffix `pk'; dynamic creation program:
  435.      `mktexpk'.
  436. `PostScript header'
  437.      (downloadable PostScript, *note Header files: (dvips)Header files.)
  438.      `TEXPSHEADERS', `PSHEADERS'; additional suffix `.pro'.
  439. `tex'
  440.      (TeX source, *note tex invocation: (web2c)tex invocation.)
  441.      `TEXINPUTS'; suffix `.tex'; additional suffixes: none, because
  442.      such a list cannot be complete; dynamic creation program:
  443.      `mktextex'.
  444. `TeX system documentation'
  445.      (Documentation files for the TeX system) `TEXDOCS'.
  446. `TeX system sources'
  447.      (Source files for the TeX system) `TEXSOURCES'.
  448. `texpool'
  449.      (TeX program strings, *note pooltype invocation: (web2c)pooltype
  450.      invocation.)  `TEXPOOL', `TEXMFINI'; suffix `.pool'.
  451. `tfm'
  452.      (TeX font metrics, *note Metric files: (dvips)Metric files.)
  453.      `TFMFONTS', `TEXFONTS'; suffix `.tfm'; dynamic creation program:
  454.      `mktextfm'.
  455. `Troff fonts'
  456.      (Troff fonts, used by DMP; *note DMP invocation: (web2c)DMP
  457.      invocation.)  `TRFONTS'.
  458. `truetype fonts'
  459.      (TrueType outline fonts) `TTFONTS'; suffixes `.ttf', `.ttc'.
  460. `type1 fonts'
  461.      (Type 1 PostScript outline fonts, *note Glyph files: (dvips)Glyph
  462.      files.)  `T1FONTS', `T1INPUTS', `TEXPSHEADERS', `DVIPSHEADERS';
  463.      suffixes `.pfa', `.pfb'.
  464. `type42 fonts'
  465.      (Type 42 PostScript outline fonts) `T42FONTS'.
  466.      (virtual fonts, *note Virtual fonts: (dvips)Virtual fonts.)
  467.      `VFFONTS', `TEXFONTS'; suffix `.vf'.
  468.   There are two special cases, because the paths and environment
  469. variables always depend on the name of the program: the variable name is
  470. constructed by converting the program name to upper case, and then
  471. appending `INPUTS'.  Assuming the program is called `foo', this gives
  472. us the following table.
  473. `other text files'
  474.      (text files used by `foo') `FOOINPUTS'.
  475. `other binary files'
  476.      (binary files used by `foo') `FOOINPUTS'.
  477.   If an environment variable by these names are set, the corresponding
  478. `texmf.cnf' definition won't be looked at (unless, as usual, the
  479. environment variable value has an extra `:').  *Note Default
  480. expansion::.
  481.   For the font variables, the intent is that:
  482.    * `TEXFONTS' is the default for everything.
  483.    * `GLYPHFONTS' is the default for bitmap (or, more precisely,
  484.      non-metric) files.
  485.    * Each font format has a variable of its own.
  486.    * Each program has its own font override path as well; e.g.,
  487.      `DVIPSFONTS' for Dvipsk.  Again, this is for bitmaps, not metrics.
  488. File: kpathsea.info,  Node: File lookup,  Next: Glyph lookup,  Prev: Supported file formats,  Up: TeX support
  489. File lookup
  490. ===========
  491.   This section describes how Kpathsea searches for most files (bitmap
  492. font searches are the exception, as described in the next section).
  493.   Here is the search strategy for a file NAME:
  494.   1. If the file format defines default suffixes, and the suffix of
  495.      NAME name is not already a known suffix for that format, try the
  496.      name with each default appended, and use alternative names found
  497.      in the fontmaps if necessary.  We postpone searching the disk as
  498.      long as possible.  Example: given `foo.sty', look for `foo.sty.tex'
  499.      before `foo.sty'.  This is unfortunate, but allows us to find
  500.      `foo.bar.tex' before `foo.bar' if both exist and we were given
  501.      `foo.bar'.
  502.   2. Search for NAME, and if necssary for alternative names found in
  503.      the fontmaps.  Again we avoid searching the disk if possible.
  504.      Example: given `foo', we look for `foo'.
  505.   3. If the file format defines a program to invoke to create missing
  506.      files, run it (*note mktex scripts::.).
  507.   This is implemented in the routine `kpse_find_file' in
  508. `kpathsea/tex-file.c'.  You can watch it in action with the debugging
  509. options (*note Debugging::.).
  510. File: kpathsea.info,  Node: Glyph lookup,  Next: Suppressing warnings,  Prev: File lookup,  Up: TeX support
  511. Glyph lookup
  512. ============
  513.   This section describes how Kpathsea searches for a bitmap font in GF
  514. or PK format (or either) given a font name (e.g., `cmr10') and a
  515. resolution (e.g., 600).
  516.   Here is an outline of the search strategy (details in the sections
  517. below) for a file NAME at resolution DPI.  The search stops at the
  518. first successful lookup.
  519.   1. Look for an existing file NAME.DPIFORMAT in the specified
  520.      format(s).
  521.   2. If NAME is an alias for a file F in the fontmap file
  522.      `texfonts.map', look for F.DPI.
  523.   3. Run an external program (typically named `mktexpk') to generate
  524.      the font (*note mktex scripts::.)
  525.   4. Look for FALLBACK.DPI, where FALLBACK is some last-resort font
  526.      (typically `cmr10').
  527.   This is implemented in `kpse_find_glyph_format' in
  528. `kpathsea/tex-glyph.c'.
  529. * Menu:
  530. * Basic glyph lookup::          Features common to all glyph lookups.
  531. * Fontmap::                     Aliases for fonts.
  532. * Fallback font::               Resolutions and fonts of last resort.
  533. File: kpathsea.info,  Node: Basic glyph lookup,  Next: Fontmap,  Up: Glyph lookup
  534. Basic glyph lookup
  535. ------------------
  536.   When Kpathsea looks for a bitmap font NAME at resolution DPI in a
  537. format FORMAT, it first checks each directory in the search path for a
  538. file `NAME.DPIFORMAT'; for example, `cmr10.600pk'.  Kpathsea looks for
  539. a PK file first, then a GF file.
  540.   If that fails, Kpathsea looks for `dpiDPI/NAME.FORMAT'; for example,
  541. `dpi600/cmr10.pk'. This is how fonts are typically stored on
  542. filesystems (such as DOS) that permit only three-character extensions.
  543.   If that fails, Kpathsea looks for a font with a close-enough DPI.
  544. "Close enough" is defined by the macro `KPSE_BITMAP_TOLERANCE' in
  545. `kpathsea/tex-glyph.h' to be `DPI / 500 + 1'.  This is slightly more
  546. than the 0.2% minimum allowed by the DVI standard
  547. (`CTAN:/dviware/driv-standard/level-0').
  548. File: kpathsea.info,  Node: Fontmap,  Next: Fallback font,  Prev: Basic glyph lookup,  Up: Glyph lookup
  549. Fontmap
  550. -------
  551.   If a bitmap font or metric file is not found with the original name
  552. (see the previous section), Kpathsea looks through any "fontmap" files
  553. for an "alias" for the original font name.  These files are named
  554. `texfonts.map' and searched for along the `TEXFONTMAPS'
  555. environment/config file variable.  All `texfonts.map' files that are
  556. found are read; earlier definitions override later ones.
  557.   This feature is intended to help in two respects:
  558.   1. An alias name is limited in length only by available memory, not
  559.      by your filesystem.  Therefore, if you want to ask for
  560.      `Times-Roman' instead of `ptmr', you can (you get `ptmr8r').
  561.   2. A few fonts have historically had multiple names: specifically,
  562.      LaTeX's "circle font" has variously been known as `circle10',
  563.      `lcircle10', and `lcirc10'.  Aliases can make all the names
  564.      equivalent, so that it no longer matters what the name of the
  565.      installed file is; TeX documents will find their favorite name.
  566.   The format of fontmap files is straightforward:
  567.    * Comments start with `%' and continue to the end of the line.
  568.    * Blank lines are ignored.
  569.    * Each nonblank line is broken up into a series of "words":   a
  570.      sequence of non-whitespace characters.
  571.    * If the first word is `include', the second word is used as   a
  572.      filename, and it is searched for and read.
  573.    * Otherwise, the first word on each line is the true filename;
  574.    * the second word is the alias;
  575.    * subsequent words are ignored.
  576.   If an alias has an extension, it matches only those files with that
  577. extension; otherwise, it matches anything with the same root, regardless
  578. of extension.  For example, an alias `foo.tfm' matches only when
  579. `foo.tfm' is being searched for; but an alias `foo' matches `foo.vf',
  580. `foo.600pk', etc.
  581.   As an example, here is an excerpt from the `texfonts.map' in the
  582. Web2c distribution.  It makes the circle fonts equivalent and includes
  583. automatically generated maps for most PostScript fonts available from
  584. various font suppliers.
  585.      circle10        lcircle10
  586.      circle10        lcirc10
  587.      lcircle10       circle10
  588.      lcircle10       lcirc10
  589.      lcirc10         circle10
  590.      lcirc10         lcircle10
  591.      ...
  592.      include adobe.map
  593.      include apple.map
  594.      include bitstrea.map
  595.      ...
  596.   Fontmaps are implemented in the file `kpathsea/fontmap.c'.  The
  597. Fontname distribution has much more information on font naming (*note
  598. Introduction: (fontname)Introduction.).
  599. File: kpathsea.info,  Node: Fallback font,  Prev: Fontmap,  Up: Glyph lookup
  600. Fallback font
  601. -------------
  602.   If a bitmap font cannot be found or created at the requested size,
  603. Kpathsea looks for the font at a set of "fallback resolutions".  You
  604. specify these resolutions as a colon-separated list (like search paths).
  605. Kpathsea looks first for a program-specific environment variable (e.g.,
  606. `DVIPSSIZES' for Dvipsk), then the environment variable `TEXSIZES',
  607. then a default specified at compilation time (the Make variable
  608. `default_texsizes').  You can set this list to be empty if you prefer
  609. to find fonts at their stated size or not at all.
  610.   Finally, if the font cannot be found even at the fallback resolutions,
  611. Kpathsea looks for a fallback font, typically `cmr10'.  Programs must
  612. enable this feature by assigning to the global variable
  613. `kpse_fallback_font' or calling `kpse_init_prog' (*note Calling
  614. sequence::.); the default is no fallback font.
  615. File: kpathsea.info,  Node: Suppressing warnings,  Prev: Glyph lookup,  Up: TeX support
  616. Suppressing warnings
  617. ====================
  618.   Kpathsea provides a way to suppress selected usually-harmless
  619. warnings; this is useful at large sites where most users are not
  620. administrators, and thus the warnings are merely a source of confusion,
  621. not a help.  To do this, you set the environment variable or
  622. configuration file value `TEX_HUSH' to a colon-separated list of
  623. values.  Here are the possibilities:
  624. `all'
  625.      Suppress everything possible.
  626. `checksum'
  627.      Suppress mismatched font checksum warnings.
  628. `lostchar'
  629.      Suppress warnings when a character is missing from a font that a
  630.      DVI or VF file tries to typeset.
  631. `readable'
  632.      Suppress warnings about attempts to access a file whose permissions
  633.      render it unreadable.
  634. `special'
  635.      Suppresses warnings about an unimplemented or unparsable
  636.      `\special' command.
  637. `tex-hush.c' defines the function that checks the variable value.  Each
  638. driver implements its own checks where appropriate.
  639. File: kpathsea.info,  Node: Programming,  Next: Index,  Prev: TeX support,  Up: Top
  640. Programming
  641. ***********
  642.   This chapter is for programmers who wish to use Kpathsea.  *Note
  643. Introduction::, for the conditions under which you may do so.
  644. * Menu:
  645. * Overview: Programming overview.         Introduction.
  646. * Calling sequence::                      Specifics of what to call.
  647. * Program-specific files::                How to handle these.
  648. * Config: Programming with config files.  Getting info from texmf.cnf.
  649. File: kpathsea.info,  Node: Programming overview,  Next: Calling sequence,  Up: Programming
  650. Programming overview
  651. ====================
  652.   Aside from this manual, your best source of information is the source
  653. to the programs I've modified to use Kpathsea (*note Introduction::.).
  654. Of those, Dviljk is probably the simplest, and hence a good place to
  655. start.  Xdvik adds VF support and the complication of X resources.
  656. Dvipsk adds the complication of its own config files.  Web2c is source
  657. code I also maintain, so it uses Kpathsea rather straightforwardly, but
  658. is of course complicated by the Web to C translation.  Finally,
  659. Kpsewhich is a small utility program whose sole purpose is to exercise
  660. the main path-searching functionality.
  661.   Beyond these examples, the `.h' files in the Kpathsea source describe
  662. the interfaces and functionality (and of course the `.c' files define
  663. the actual routines, which are the ultimate documentation).
  664. `pathsearch.h' declares the basic searching routine.  `tex-file.h' and
  665. `tex-glyph.h' define the interfaces for looking up particular kinds of
  666. files.  You may wish to use `#include <kpathsea/kpathsea.h>', which
  667. includes every Kpathsea header.
  668.   The library provides no way for an external program to register new
  669. file types: `tex-file.[ch]' must be modified to do this. For example,
  670. Kpathsea has support for looking up Dvips config files, even though no
  671. program other than Dvips will likely ever want to do so.  I felt this
  672. was acceptable, since along with new file types should also come new
  673. defaults in `texmf.cnf' (and its descendant `paths.h'), since it's
  674. simplest for users if they can modify one configuration file for all
  675. kinds of paths.
  676.   Kpathsea does not parse any formats itself; it barely opens any files.
  677. Its primary purpose is to return filenames.  The GNU font utilities does
  678. contain libraries to read TFM, GF, and PK files, as do the programs
  679. above, of course.
  680. File: kpathsea.info,  Node: Calling sequence,  Next: Program-specific files,  Prev: Programming overview,  Up: Programming
  681. Calling sequence
  682. ================
  683.   The typical way to use Kpathsea in your program goes something like
  684. this:
  685.   1. Call `kpse_set_program_name' with `argv[0]' as the first argument;
  686.      the second argument is a string or `NULL'.  The second argument is
  687.      used by Kpathsea as the program name for the `.PROGRAM' feature of
  688.      config files (*note Config files::.).  If the second argument is
  689.      `NULL', the value of the first argument is used.  This function
  690.      must be called before any other use of the Kpathsea library.
  691.      If necessary, `kpse_set_program_name' sets the global variables
  692.      `program_invocation_name' and `program_invocation_short_name'.
  693.      These variables are used in the error message macros defined in
  694.      `kpathsea/lib.h'.  It sets the global variable `kpse_program_name'
  695.      to the program name it uses.  It also initializes debugging
  696.      options based on the environment variable `KPATHSEA_DEBUG' (if
  697.      that is set).  Finally, it sets the variables `SELFAUTOLOC',
  698.      `SELFAUTODIR' and `SELFAUTOPARENT' to the location, parent and
  699.      grandparent directory of the executable, removing `.' and `..'
  700.      path elements and resolving symbolic links.  These are used in the
  701.      default configuration file to allow people to invoke TeX from
  702.      anywhere, specifically from a mounted CD-ROM.  (You can use
  703.      `--expand-var=\$SELFAUTOLOC', etc., to see the values finds.)
  704.   2. The `kpse_set_progname' is deprecated.  A call to
  705.      `kpse_set_progname' with `argv[0]' is equivalent to a call of
  706.      `kpse_set_program_name' with first argument `argv[0]' and second
  707.      argument `NULL'.  The function is deprecated because it cannot
  708.      ensure that the `.PROGRAM' feature of config files will always
  709.      work (*note Config files::.).
  710.   3. Set debugging options. *Note Debugging::.  If your program doesn't
  711.      have a debugging option already, you can define one and set
  712.      `kpathsea_debug' to the number that the user supplies (as in Dviljk
  713.      and Web2c), or you can just omit this altogether (people can
  714.      always set `KPATHSEA_DEBUG').  If you do have runtime debugging
  715.      already, you need to merge Kpathsea's options with yours (as in
  716.      Dvipsk and Xdvik).
  717.   4. If your program has its own configuration files that can define
  718.      search paths, you should assign those paths to the `client_path'
  719.      member in the appropriate element of the `kpse_format_info' array.
  720.      (This array is indexed by file type; see `tex-file.h'.)  See
  721.      `resident.c' in Dvipsk for an example.
  722.   5. Call `kpse_init_prog' (see `proginit.c'). It's useful for the DVI
  723.      drivers, at least, but for other programs it may be simpler to
  724.      extract the parts of it that actually apply.  This does not
  725.      initialize any paths, it just looks for (and sets) certain
  726.      environment variables and other random information.  (A search
  727.      path is always initialized at the first call to find a file of
  728.      that type; this eliminates much useless work, e.g., initializing
  729.      the BibTeX search paths in a DVI driver.)
  730.   6. The routine to actually find a file of type FORMAT is
  731.      `kpse_find_FORMAT', defined in `tex-file.h'. These are macros that
  732.      expand to a call to `kpse_find_file'.  You can call, say,
  733.      `kpse_find_tfm' after doing only the first of the initialization
  734.      steps above--Kpathsea automatically reads the `texmf.cnf' generic
  735.      config files, looks for environment variables, and does expansions
  736.      at the first lookup.
  737.   7. To find PK and/or GF bitmap fonts, the routines are `kpse_find_pk',
  738.      `kpse_find_gf' and `kpse_find_glyph', defined in `tex-glyph.h'.
  739.      These return a structure in addition to the resultant filename,
  740.      because fonts can be found in so many ways. See the documentation
  741.      in the source.
  742.   8. To actually open a file, not just return a filename, call
  743.      `kpse_open_file'.  This function takes the name to look up and a
  744.      Kpathsea file format as arguments, and returns the usual `FILE *'.
  745.      It always assumes the file must exist, and thus will search the
  746.      disk if necessary (unless the search path specified `!!', etc.).
  747.      In other words, if you are looking up a VF or some other file that
  748.      need not exist, don't use this.
  749.   Kpathsea also provides many utility routines. Some are generic: hash
  750. tables, memory allocation, string concatenation and copying, string
  751. lists, reading input lines of arbitrary length, etc. Others are
  752. filename-related: default path, tilde, and variable expansion, `stat'
  753. calls, etc. (Perhaps someday I'll move the former to a separate
  754. library.)
  755.   The `c-*.h' header files can also help your program adapt to many
  756. different systems.  You will almost certainly want to use Autoconf for
  757. configuring your software if you use Kpathsea; I strongly recommend
  758. using Autoconf regardless.  It is available from
  759. `ftp://prep.ai.mit.edu/pub/gnu/'.
  760. File: kpathsea.info,  Node: Program-specific files,  Next: Programming with config files,  Prev: Calling sequence,  Up: Programming
  761. Program-specific files
  762. ======================
  763.   Many programs will need to find some configuration files.  Kpathsea
  764. contains some support to make it easy to place them in their own
  765. directories.  The Standard TeX directory structure (*note Introduction:
  766. (tds)Top.), specifies that such files should go into a subdirectory
  767. named after the program, like `texmf/ttf2pk'.
  768.   Two special formats, `kpse_program_text_format' and
  769. `kpse_program_binary_format' exist, which use `.:$TEXMF/PROGRAM//' as
  770. their compiled-in search path.  To override this default, you can use
  771. the variable `PROGRAMINPUTS' in the environment and/or `texmf.cnf'.
  772. That is to say, the name of the variable is constructed by converting
  773. the name of the program to upper case, and appending `INPUTS'.
  774.   The only difference between these two formats is whether
  775. `kpse_open_file' will open the files it finds in text or binary mode.
  776. File: kpathsea.info,  Node: Programming with config files,  Prev: Program-specific files,  Up: Programming
  777. Programming with config files
  778. =============================
  779.   You can (and probably should) use the same `texmf.cnf' configuration
  780. file that Kpathsea uses for your program.  This helps installers by
  781. keeping all configuration in one place.
  782.   To retrieve a value VAR from config files, the best way is to call
  783. `kpse_var_value' on the string `VAR'.  This will look first for an
  784. environment variable VAR, then a config file value.  The result will be
  785. the value found or `NULL'.  This function is declared in
  786. `kpathsea/variable.h'.  For an example, see the `shell_escape' code in
  787. `web2c/lib/texmfmp.c'.
  788.   The routine to do variable expansion in the context of a search path
  789. (as opposed to simply retrieving a value) is `kpse_var_expand', also
  790. declared in `kpathsea/variable.h'.  It's generally only necessary to
  791. set the search path structure components as explained in the previous
  792. section, rather than using this yourself.
  793.   If for some reason you want to retrieve a value *only* from a config
  794. file, not automatically looking for a corresponding environment
  795. variable, call `kpse_cnf_get' (declared in `kpathsea/cnf.h') with the
  796. string VAR.
  797.   No initialization calls are needed.
  798.