Debian Codegraph @

texmf-dist/doc/info/kpathsea.info

raw
1 This is kpathsea.info, produced by makeinfo version 7.2 from
2 kpathsea.texi.
3
4 This file documents the Kpathsea library for path searching.
5
6 Copyright © 1996-2026 Karl Berry & Olaf Weber.
7
8 Permission is granted to make and distribute verbatim copies of this
9 manual provided the copyright notice and this permission notice are
10 preserved on all copies.
11
12 Permission is granted to copy and distribute modified versions of
13 this manual under the conditions for verbatim copying, provided that the
14 entire resulting derived work is distributed under the terms of a
15 permission notice identical to this one.
16
17 Permission is granted to copy and distribute translations of this
18 manual into another language, under the above conditions for modified
19 versions, except that this permission notice may be stated in a
20 translation approved by the TeX Users Group.
21 INFO-DIR-SECTION TeX
22 START-INFO-DIR-ENTRY
23 * Kpathsea: (kpathsea). File lookup along search paths.
24 * kpsewhich: (kpathsea)Invoking kpsewhich. TeX file searching.
25 * mktexfmt: (kpathsea)mktex scripts. Format (fmt/base/mem) generation.
26 * mktexlsr: (kpathsea)Filename database. Update ls-R.
27 * mktexmf: (kpathsea)mktex scripts. MF source generation.
28 * mktexpk: (kpathsea)mktex scripts. PK bitmap generation.
29 * mktextex: (kpathsea)mktex scripts. TeX source generation.
30 * mktextfm: (kpathsea)mktex scripts. TeX font metric generation.
31 END-INFO-DIR-ENTRY
32
33 
34 File: kpathsea.info, Node: Top, Next: Introduction, Up: (dir)
35
36 Kpathsea library
37 ****************
38
39 This manual documents the Kpathsea library for path searching. It
40 corresponds to version 6.4.2/dev, released in January 2026.
41
42 * Menu:
43
44 * Introduction:: Overview and history.
45
46 * unixtex.ftp:: Obtaining TeX software.
47 * Security:: Who can write what files, etc.
48 * TeX directory structure:: Managing the horde of TeX input files.
49
50 * Path searching:: How filename lookups work.
51 * TeX support:: Special support for TeX-related file lookups.
52
53 * Programming:: How to use Kpathsea features in your program.
54
55 * Reporting bugs:: Where and how to report bugs.
56 * Index:: General index.
57
58 
59 File: kpathsea.info, Node: Introduction, Next: unixtex.ftp, Prev: Top, Up: Top
60
61 1 Introduction
62 **************
63
64 This manual corresponds to version 6.4.2/dev of the Kpathsea library,
65 released in January 2026.
66
67 The library's fundamental purpose is to return a filename from a list
68 of directories specified by the user, similar to what shells do when
69 looking up program names to execute.
70
71 The following software, all of which is maintained in parallel, uses
72 this library:
73
74 • Dviljk (see the ‘dvilj’ man page)
75 • Dvipsk (*note (dvips)Top::)
76 • GNU font utilities (*note (fontu)Top::)
77 • Web2c (*note (web2c)Top::)
78 • Xdvik (see the ‘xdvi’ man page)
79
80 Other software that we do not maintain also uses it.
81
82 Kpathsea is now maintained as part of the TeX Live distribution
83 (<https://tug.org/texlive>), which includes several more Kpathsea-using
84 programs. For information on configuration, building, installing, and
85 more, *note (tlbuild)Top::.
86
87 The library is still actively maintained. If you have comments or
88 suggestions, please send along (*note Reporting bugs::).
89
90 The Kpathsea library is distributed under the GNU Library General
91 Public License (LGPL), version 2.1 or (at your option) any later
92 version. In short, this means if you write a program using the library,
93 you must (offer to) distribute the source to the library, along with any
94 changes you have made, and allow anyone to modify the library source and
95 distribute their modifications. It does not mean you have to distribute
96 the source to your program using the library, although we hope you will.
97 See accompanying files for the text of the GNU licenses, or
98 <https://gnu.org/licenses>.
99
100 If you know enough about TeX to be reading this manual, then you (or
101 your institution) should consider joining the TeX Users Group (if you're
102 already a member, thanks!). TUG produces the periodical ‘TUGboat’,
103 sponsors an annual meeting and publishes the proceedings, and arranges
104 courses on TeX for all levels of users throughout the world. See
105 <https://tug.org> for information.
106
107 * Menu:
108
109 * History::
110
111 
112 File: kpathsea.info, Node: History, Up: Introduction
113
114 1.1 History
115 ===========
116
117 This section is for those people who are curious about how the library
118 came about. If you like to read historical accounts of software, we
119 urge you to seek out the GNU Autoconf manual and the "Errors of TeX"
120 paper by Don Knuth, published in his book ‘Digital Typography’, among
121 other places.
122
123 [Karl writes.] My first ChangeLog entry for Web2c seems to be
124 February 1990, but I may have done some work before then. In any case,
125 Tim Morgan and I were jointly maintaining it for a time. (I should
126 mention here that Tim had made Web2c into a real distribution long
127 before I had ever used it or even heard of it, and Tom Rokicki did the
128 original implementation. When I started, I was using ‘pxp’ and ‘pc’ on
129 VAX 11/750's and the hot new Sun 2 machines.)
130
131 It must have been later in 1990 and 1991 that I started working on
132 ‘TeX for the Impatient’. Dvips, Xdvi, Web2c, and the GNU fontutils
133 (which I was also writing at the time) all used different environment
134 variables, and, more importantly, had different bugs in their path
135 searching. This became extremely painful, as I was stressing everything
136 to the limit working on the book. I also desperately wanted to
137 implement subdirectory searching, since I couldn't stand putting
138 everything in one big directory, and also couldn't stand having to
139 explicitly specify ‘cm’, ‘pandora’, ... in a path.
140
141 In the first incarnation, I just hacked separately on each
142 program--that was the original subdirectory searching code in both Xdvi
143 and Dvips. That is, I tried to go with the flow in each program, rather
144 than changing the program's calling sequences to conform to new
145 routines.
146
147 Then, as bugs inevitably appeared, I found I was fixing the same
148 thing three times (Web2c and fontutils were already sharing code, since
149 I maintained both of those--there was no Dvipsk or Xdvik or Dviljk at
150 this point). After a while, I finally started sharing source files.
151 They weren't yet a library, though. I just kept things up to date with
152 shell scripts. (I was developing on a 386 running ISC 2.2 at the time,
153 and so didn't have symbolic links. An awful experience.)
154
155 The ChangeLogs for Xdvik and Dvipsk record initial releases of those
156 distributions in May and June 1992. I think it was because I was tired
157 of the different configuration strategies of each program, not so much
158 because of the path searching. Autoconf was being developed by David
159 MacKenzie and others, and I was adapting it to TeX and friends.
160
161 I started to make a separate library that other programs could link
162 with on my birthday in April 1993, according to the ChangeLog. I don't
163 remember exactly why I finally took the time to make it a separate
164 library; a conversation with david zuhn initiated it. Just seemed like
165 it was time.
166
167 Dviljk got started in March 1994 after I bought a Laserjet 4.
168 (Kpathsea work got suspended while Norm Walsh and I, with Gustaf
169 Neumann's help, implemented a way for TeX to get at all those neat
170 builtin LJ4 fonts ... such a treat to have something to typeset in
171 besides Palatino!)
172
173 By spring of 1995, I had implemented just about all the
174 path-searching features in Kpathsea that I plan to, driven beyond my
175 initial goals by Thomas Esser and others. I then started to integrate
176 Web2c with Kpathsea. After the release of a stable Web2c, I hope to be
177 able to stop development, and turn most of my attention back to making
178 fonts for GNU. (Always assuming Micros**t hasn't completely obliterated
179 Unix by then, or that software patents haven't stopped software
180 development by anybody smaller than a company with a
181 million-dollar-a-year legal budget. Which is actually what I think is
182 likely to happen, but that's another story...)
183
184 [Olaf writes.] At the end of 1997, Unix is still alive and kicking,
185 individuals still develop software, and Web2c development still
186 continues. Karl had been looking for some time for someone to take up
187 part of the burden, and I volunteered.
188
189 [Karl writes again.] Indeed, time goes on. As of 2006 or so, Olaf's
190 available time for Kpathsea was reduced, and I started taking overall
191 care of it again, although I did not do any significant new development.
192 In 2009, Taco Hoekwater implemented a major rearrangement to make the
193 library suitable for use within the MetaPost library (*note Programming
194 overview::). Also, for some years now, Peter Breitenlohner has made
195 many improvements to the infrastructure and kept it up-to-date with
196 respect to the overall TeX Live build, where Kpathsea is now maintained.
197
198 
199 File: kpathsea.info, Node: unixtex.ftp, Next: Security, Prev: Introduction, Up: Top
200
201 2 ‘unixtex.ftp’: Obtaining TeX
202 ******************************
203
204 This is <ftp://tug.org/tex/unixtex.ftp>, a.k.a.
205 <https://tug.org/unixtex.ftp>, last updated 29 February 2020. Email
206 <[email protected]> with comments or questions.
207
208 The principal free TeX distribution for Unix-like systems is TeX
209 Live, on the web at <http://tug.org/texlive>. The pages there describe
210 many ways to acquire and/or build TeX, over the Internet or on physical
211 media, both the sources and precompiled binaries for many systems,
212 either standalone or as part of various operating system distributions.
213
214 Web2c, Kpathsea, Dvips, and Dviljk, among others, are no longer
215 released as a separate packages. Their sources are now maintained as
216 part of TeX Live.
217
218 The host ftp.cs.stanford.edu is the original source for the files for
219 which Donald Knuth is directly responsible: ‘tex.web’, ‘plain.tex’, etc.
220 However, unless you want to undertake the project of building your TeX
221 system from scratch, it is more reliable and less work to retrieve these
222 files as part of a larger package.
223
224 In any case, the Stanford ftp site is not the canonical source for
225 anything except what was created as part of Knuth's original TeX, so do
226 not rely on any other files available there being up-to-date. The best
227 place to check for up-to-date files is CTAN (the Comprehensive TeX
228 Archive Network), <https://ctan.org>.
229
230 
231 File: kpathsea.info, Node: Security, Next: TeX directory structure, Prev: unixtex.ftp, Up: Top
232
233 3 Security
234 **********
235
236 None of the programs in the TeX system require any special system
237 privileges, so there's no first-level security concern of people gaining
238 illegitimate root access.
239
240 Thus, the general goal of our security measures is to make an
241 untrusted TeX document safe to execute, in the sense of no document
242 being able to change the system or user configuration, or transmit
243 information to an attacker. Here are some of the steps that have been
244 taken to make the TeX system safe in this regard:
245
246 • A TeX document can write to arbitrary files via ‘\openout’, e.g.,
247 ‘~/.profile’, and thus an unwitting user who runs TeX on an
248 untrusted document is vulnerable to a trojan horse attack. This
249 loophole is closed by default, but you can be permissive if you so
250 desire in ‘texmf.cnf’; see the variable ‘openout_any’. *Note
251 (web2c)tex invocation::. MetaPost has the same issue (Metafont
252 cannot write arbitrary files).
253
254 • Dvips, Xdvi, TeX, and others can execute shell commands. By
255 default, only a handful of commands that are believed to be safe,
256 to the best of our ability to check, are allowed. For the list,
257 see the ‘shell_escape_commands’ variable in ‘texmf.cnf’ (*note
258 (web2c)Shell escapes::). For more information, e.g., to disable
259 this completely, see the ‘-R’ option in *note (dvips)Option
260 details::, the xdvi man page, and *note (web2c)tex invocation::,
261 respectively.
262
263 • LuaTeX is a special case. Since Lua is a general-purpose
264 programming language, it has all the usual functionality for
265 writing files, executing shell commands, opening network
266 connections, and plenty more. When LuaTeX is used in its so-called
267 "kpse" mode, as with LuaLaTeX, we have nevertheless done our best
268 to also make it safe to execute by default, by disabling or
269 restricting the various problematic Lua features. *Note Safe
270 filenames::, for a bit more about this. (When LuaTeX is run in
271 non-kpse mode, as with ConTeXt MkIV, everything is allowed; thus,
272 untrusted documents should not be processed.)
273
274 • There are some well-known ways to crash TeX, using arithmetic
275 overflow, which Knuth deliberately left unchecked, and other
276 nefarious constructs; some are listed at
277 <https://tug.org/texmfbug/nobug.html>. While disturbing, TeX has
278 no special system access and so these crashes don't present a
279 security risk.
280
281 • One more issue is the desire for a globally writable font cache
282 directory; see the section below for this (*note Global font cache
283 and security::).
284
285 * Menu:
286
287 * Global font cache and security::
288
289 
290 File: kpathsea.info, Node: Global font cache and security, Up: Security
291
292 3.1 Global font cache and security
293 ==================================
294
295 It's useful to make arbitrary fonts on user demand with ‘mktexpk’ and
296 friends. Where do these files get installed? By default, the ‘mktexpk’
297 distributed with Kpathsea assumes a world-writable ‘/var/tmp’ directory;
298 this is a simple and convenient approach, but it does not suit all
299 situations, because it means that a local cache of fonts is created on
300 every user's system.
301
302 To avoid this duplication, many people consider a shared, globally
303 writable font tree desirable, in spite of the potential security
304 problems. To do this you should change the value of ‘VARTEXFONTS’ in
305 ‘texmf.cnf’ to refer to some globally known directory. *Note mktex
306 configuration::.
307
308 The first restriction you can apply is to make newly-created
309 directories under ‘texmf’ be append-only with an option in ‘mktex.cnf’.
310 *Note mktex configuration::.
311
312 Another approach is to establish a group (or user) for TeX files,
313 make the ‘texmf’ tree writable only to that group (or user), and make
314 ‘mktexpk’ et al. setgid to that group (or setuid to that user). Then
315 users must invoke the scripts to install things. (If you're worried
316 about the likelihood of security holes in scripts, you could write a C
317 wrapper to exec the script.)
318
319 The ‘mktex...’ scripts install files with the same read and write
320 permissions as the directory they are installed in. The executable,
321 sgid, suid, and sticky bits are always cleared.
322
323 Any directories created by the ‘mktex...’ scripts have the same
324 permissions as their parent directory, unless the ‘appendonlydir’
325 feature is used, in which case the sticky bit is always set.
326
327 Nowadays, with bitmap files rarely used, and with individual systems
328 being so much more powerful, this is less of an issue than in the past.
329 But the question still comes up occasionally.
330
331 
332 File: kpathsea.info, Node: TeX directory structure, Next: Path searching, Prev: Security, Up: Top
333
334 4 TeX directory structure
335 *************************
336
337 This section describes the default installation hierarchy of the
338 distribution. It conforms to both the GNU coding standards and the TeX
339 directory structure (TDS) standard. For rationale and further
340 explanation, please see those documents. The GNU document is available
341 from <https://gnu.org/prep/standards>. The TDS document is available
342 from <https://ctan.org/pkg/tds> (*note unixtex.ftp::).
343
344 In short, here is a skeleton of the default directory structure,
345 extracted from the TDS document:
346
347 PREFIX/ installation root (‘/usr/local’ by default)
348 bin/ executables
349 man/ man pages
350 include/ C header files
351 info/ GNU info files
352 lib/ libraries (‘libkpathsea.*’)
353 share/ architecture-independent files
354 texmf/ TDS root
355 bibtex/ BibTeX input files
356 bib/ BibTeX databases
357 base/ base distribution (e.g., ‘xampl.bib’)
358 misc/ single-file databases
359 PKG/ name of a package
360 bst/ BibTeX style files
361 base/ base distribution (e.g., ‘plain.bst’, ‘acm.bst’)
362 misc/ single-file styles
363 PKG/ name of a package
364 doc/ additional documentation
365 dvips/ ‘.pro’, ‘.ps’, ‘psfonts.map’
366 fonts/ font-related files
367 TYPE/ file type (e.g., ‘tfm’, ‘pk’)
368 MODE/ type of output device (types ‘pk’ and ‘gf’ only)
369 SUPPLIER/ name of a font supplier (e.g., ‘public’)
370 TYPEFACE/ name of a typeface (e.g., ‘cm’)
371 dpiNNN/ font resolution (types ‘pk’ and ‘gf’ only)
372 metafont/ Metafont (non-font) input files
373 base/ base distribution (e.g., ‘plain.mf’)
374 misc/ single-file packages (e.g., ‘modes.mf’)
375 PKG/ name of a package (e.g., ‘mfpic’)
376 metapost/ MetaPost input files
377 base/ base distribution (e.g., ‘plain.mp’)
378 misc/ single-file packages
379 PKG/ name of a package
380 support/ support files for MetaPost-related utilities (e.g., ‘trfonts.map’)
381 mft/ ‘MFT’ inputs (e.g., ‘plain.mft’)
382 tex/ TeX input files
383 FORMAT/ name of a format (e.g., ‘plain’)
384 base/ base distribution for FORMAT (e.g., ‘plain.tex’)
385 misc/ single-file packages (e.g., ‘webmac.tex’)
386 local/ local additions to or local configuration files for FORMAT
387 PKG/ name of a package (e.g., ‘graphics’, ‘mfnfss’)
388 generic/ format-independent packages
389 hyphen/ hyphenation patterns (e.g., ‘hyphen.tex’)
390 images/ image input files (e.g., Encapsulated PostScript)
391 misc/ single-file format-independent packages (e.g., ‘null.tex’).
392 PKG/ name of a package (e.g., ‘babel’)
393 web2c/ implementation-dependent files (‘.pool’, ‘.fmt’, ‘texmf.cnf’, etc.)
394
395 Some concrete examples for most file types:
396
397 /usr/local/bin/tex
398 /usr/local/man/man1/xdvi.1
399 /usr/local/info/kpathsea.info
400 /usr/local/lib/libkpathsea.a
401 /usr/local/share/texmf/bibtex/bst/base/plain.bst
402 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk
403 /usr/local/share/texmf/fonts/source/public/pandora/pnr10.mf
404 /usr/local/share/texmf/fonts/tfm/public/cm/cmr10.tfm
405 /usr/local/share/texmf/fonts/type1/adobe/utopia/putr.pfa
406 /usr/local/share/texmf/metafont/base/plain.mf
407 /usr/local/share/texmf/metapost/base/plain.mp
408 /usr/local/share/texmf/tex/plain/base/plain.tex
409 /usr/local/share/texmf/tex/generic/hyphen/hyphen.tex
410 /usr/local/share/texmf/web2c/tex.pool
411 /usr/local/share/texmf/web2c/tex.fmt
412 /usr/local/share/texmf/web2c/texmf.cnf
413
414 
415 File: kpathsea.info, Node: Path searching, Next: TeX support, Prev: TeX directory structure, Up: Top
416
417 5 Path searching
418 ****************
419
420 This chapter describes the generic path searching mechanism Kpathsea
421 provides. For information about searching for particular file types
422 (e.g., TeX fonts), see the next chapter.
423
424 This section, with minor differences, has been translated into
425 several other languages (Chinese, Spanish, Russian, Japanese, French,
426 German, ...) as part of the TeX Live guide; see
427 <https://tug.org/texlive/doc.html> for links.
428
429 * Menu:
430
431 * Searching overview:: Basic scheme for searching.
432 * Path sources:: Where search paths can be defined.
433 * Path expansion:: Special constructs in search paths.
434 * Casefolding search:: Fallback to case-insensitive search.
435 * Filename database:: Using an externally-built list to search.
436 * Invoking kpsewhich:: Standalone path lookup.
437
438 
439 File: kpathsea.info, Node: Searching overview, Next: Path sources, Up: Path searching
440
441 5.1 Searching overview
442 ======================
443
444 A “search path” is a colon-separated list of “path elements”, which are
445 directory names with a few extra frills. A search path can come from (a
446 combination of) many sources; see below. To look up a file ‘foo’ along
447 a path ‘.:/dir’, Kpathsea checks each element of the path in turn: first
448 ‘./foo’, then ‘/dir/foo’, returning the first match (or possibly all
449 matches).
450
451 The "colon" and "slash" mentioned here aren't necessarily ‘:’ and ‘/’
452 on non-Unix systems. Kpathsea tries to adapt to other operating
453 systems' conventions.
454
455 To check a particular path element E, Kpathsea first sees if a
456 prebuilt database (*note Filename database::) applies to E, i.e., if the
457 database is in a directory that is a prefix of E. If so, the path
458 specification is matched against the contents of the database.
459
460 If the database does not exist, or does not apply to this path
461 element, or contains no matches, the filesystem is searched (if this was
462 not forbidden by the specification with ‘!!’ and if the file being
463 searched for must exist). Kpathsea constructs the list of directories
464 that correspond to this path element, and then checks in each for the
465 file being searched for. (To help speed future lookups of files in the
466 same directory, the directory in which a file is found is floated to the
467 top of the directory list.)
468
469 The "file must exist" condition comes into play with VF files and
470 input files read by the TeX ‘\openin’ command. These files might very
471 well not exist (consider ‘cmr10.vf’), and so it would be wrong to search
472 the disk for them. Therefore, if you fail to update ‘ls-R’ when you
473 install a new VF file, it will not be found.
474
475 Each path element is checked in turn: first the database, then the
476 disk. If a match is found, the search stops and the result is returned
477 (unless the search explicitly requested all matches). This avoids
478 possibly-expensive processing of path specifications that are never
479 needed on a particular run.
480
481 On Unix-like systems, if no match is found by any of the above, and
482 the path element allows checking the filesystem (per the above), a final
483 check is made for a case-insensitive match. Thus, looking for a name
484 like ‘./FooBar.TeX’ will match a file ‘./foobar.tex’, and vice versa.
485 This is not done on Windows. *Note Casefolding search::.
486
487 Although the simplest and most common path element is a directory
488 name, Kpathsea supports additional features in search paths: layered
489 default values, environment variable names, config file values, users'
490 home directories, and recursive subdirectory searching. Thus, we say
491 that Kpathsea “expands” a path element, meaning transforming all the
492 magic specifications into the basic directory name or names. This
493 process is described in the sections below. It happens in the same
494 order as the sections.
495
496 Exception to all of the above: If the filename being searched for is
497 absolute or explicitly relative, i.e., starts with ‘/’ or ‘./’ or ‘../’,
498 Kpathsea simply checks if that file exists, with a fallback to a
499 casefolding match if needed and enabled, as described above.
500
501 Ordinarily, if Kpathsea tries to access a file or directory that
502 cannot be read, it gives a warning. This is so you will be alerted to
503 directories or files that accidentally lack any read permission (for
504 example, a ‘lost+found’ directory). If you prefer not to see these
505 warnings, include the value ‘readable’ in the ‘TEX_HUSH’ environment
506 variable or config file value.
507
508 This generic path searching algorithm is implemented in
509 ‘kpathsea/pathsearch.c’. It is employed by a higher-level algorithm
510 when searching for a file of a particular type (*note File lookup::, and
511 *note Glyph lookup::).
512
513 
514 File: kpathsea.info, Node: Path sources, Next: Path expansion, Prev: Searching overview, Up: Path searching
515
516 5.2 Path sources
517 ================
518
519 A search path or other configuration value can come from many sources.
520 In the order in which Kpathsea looks for them:
521
522 1. A command-line option such as ‘--cnf-line’, available in
523 ‘kpsewhich’ and most TeX engines. *Note Path searching options::.
524
525 A user-set environment variable, e.g., ‘TEXINPUTS’. Environment
526 variables with an underscore and the program name appended
527 override; for example, ‘TEXINPUTS_latex’ overrides ‘TEXINPUTS’ if
528 the program being run is named ‘latex’.
529
530 2. A program-specific configuration file, e.g., an ‘S /a:/b’ line in
531 Dvips' ‘config.ps’ (*note (dvips)Config files::).
532
533 3. A line in a Kpathsea configuration file ‘texmf.cnf’, e.g.,
534 ‘TEXINPUTS=/c:/d’ (see below).
535
536 4. The compile-time default (specified in ‘kpathsea/paths.h’).
537
538 You can see each of these values for a given search path by using the
539 debugging options (*note Debugging::).
540
541 These sources may be combined via default expansion (*note Default
542 expansion::).
543
544 * Menu:
545
546 * Config files:: Kpathsea's runtime config files (texmf.cnf).
547
548 
549 File: kpathsea.info, Node: Config files, Up: Path sources
550
551 5.2.1 Config files
552 ------------------
553
554 As mentioned above, Kpathsea reads “runtime configuration files” named
555 ‘texmf.cnf’ for search path and other definitions. The search path used
556 to look for these configuration files is named ‘TEXMFCNF’, and is
557 constructed in the usual way, as described above, except that
558 configuration files cannot be used to define the path, naturally; also,
559 an ‘ls-R’ database is not used to search for them.
560
561 Kpathsea reads _all_ ‘texmf.cnf’ files in the search path, not just
562 the first one found; definitions in earlier files override those in
563 later files. Thus, if the search path is ‘.:$TEXMF’, values from
564 ‘./texmf.cnf’ override those from ‘$TEXMF/texmf.cnf’.
565
566 If Kpathsea cannot find any ‘texmf.cnf’ file, it reports a warning
567 including all the directories it checked. If you don't want to see this
568 warning, set the environment variable ‘KPATHSEA_WARNING’ to the single
569 character ‘0’ (zero, not oh).
570
571 While (or instead of) reading this description, you may find it
572 helpful to look at the distributed ‘texmf.cnf’, which uses or at least
573 mentions most features. The format of ‘texmf.cnf’ files follows:
574
575 • Comments start with ‘%’ or ‘#’, either at the beginning of a line
576 or preceded by whitespace, and continue to the end of the line.
577 That is, similar to most shells, a comment character in the
578 "middle" of a value does not start a comment. Examples:
579
580 % this is a comment
581 var = a%b % but the value of var will be "a%b"
582
583 • Blank lines are ignored.
584
585 • A ‘\’ at the end of a line acts as a continuation character, i.e.,
586 the next line is appended. Whitespace at the beginning of
587 continuation lines is not ignored.
588
589 • Each remaining line will look like:
590
591 VARIABLE [. PROGNAME] [=] VALUE
592
593 where the ‘=’ and surrounding whitespace is optional.
594
595 • The VARIABLE name may contain any character other than whitespace,
596 ‘=’, or ‘.’, but sticking to ‘A-Za-z_’ is safest.
597
598 • If ‘.PROGNAME’ is present (preceding spaces are ignored), the
599 definition only applies if the program that is running is named
600 (i.e., the last component of ‘argv[0]’ is) PROGNAME or
601 ‘PROGNAME.{exe,bat,cmd,...}’. Most notably, this allows different
602 flavors of TeX to have different search paths. The PROGNAME value
603 is used literally, without variable or other expansions.
604
605 • Considered as strings, VALUE may contain any character. However,
606 in practice most ‘texmf.cnf’ values are related to path expansion,
607 and since various special characters are used in expansion, such as
608 braces and commas, they cannot be used in directory names.
609
610 The ‘$VAR.PROG’ feature is not available on the right-hand side;
611 instead, you must use an additional variable (see below for
612 example).
613
614 A ‘;’ in VALUE is translated to ‘:’ if running under Unix, in order
615 to have a single ‘texmf.cnf’ that can support both Unix and Windows
616 systems. This translation happens with any value, not just search
617 paths, but fortunately in practice ‘;’ is not needed in other
618 values.
619
620 • All definitions are read before anything is expanded, so you can
621 use variables before they are defined (like Make, unlike most other
622 programs).
623
624 Here is a configuration file fragment illustrating most of these points:
625
626 % TeX input files -- i.e., anything to be found by \input or \openin ...
627 latex209_inputs = .:$TEXMF/tex/latex209//:$TEXMF/tex//
628 latex2e_inputs = .:$TEXMF/tex/latex//:$TEXMF/tex//
629 TEXINPUTS = .:$TEXMF/tex//
630 TEXINPUTS.latex209 = $latex209_inputs
631 TEXINPUTS.latex2e = $latex2e_inputs
632 TEXINPUTS.latex = $latex2e_inputs
633
634 The combination of spaces being ignored before the ‘.’ of a program
635 name qualifer and the optional ‘=’ for the assignment has an unexpected
636 consequence: if the value begins with a literal ‘.’ and the ‘=’ is
637 omitted, the intended value is interpreted as a program name. For
638 example, a line ‘var .;/some/path’ is taken as an empty value for ‘var’
639 running under the program named ‘;/some/path’. To diagnose this,
640 Kpathsea warns if the program name contains a path separator or other
641 special character. The simplest way to avoid the problem is to use the
642 ‘=’.
643
644 Exactly when a character will be considered special or act as itself
645 depends on the context in which it is used. The rules are inherent in
646 the multiple levels of interpretation of the configuration (parsing,
647 expansion, search, ...) and so cannot be concisely stated,
648 unfortunately. There is no general escape mechanism; in particular, ‘\’
649 is not an "escape character" in ‘texmf.cnf’ files. When it comes
650 choosing directory names for installation, it is safest to avoid them
651 all.
652
653 The implementation of all this is in ‘kpathsea/cnf.c’.
654
655 
656 File: kpathsea.info, Node: Path expansion, Next: Casefolding search, Prev: Path sources, Up: Path searching
657
658 5.3 Path expansion
659 ==================
660
661 Kpathsea recognizes certain special characters and constructions in
662 search paths, similar to that in shells. As a general example:
663 ‘~$USER/{foo,bar}//baz’ expands to all subdirectories under directories
664 ‘foo’ and ‘bar’ in $USER's home directory that contain a directory or
665 file ‘baz’.
666
667 These expansions are explained in the sections below.
668
669 * Menu:
670
671 * Default expansion:: a: or :a or a::b expands to a default.
672 * Variable expansion:: $foo and ${foo} expand to environment values.
673 * Tilde expansion:: ~ and ~user expand to home directories.
674 * Brace expansion:: a{foo,bar}b expands to afoob abarb.
675 * KPSE_DOT expansion:: . is replaced with $KPSE_DOT if it is defined.
676 * Subdirectory expansion:: a// and a//b recursively expand to subdirs.
677
678 
679 File: kpathsea.info, Node: Default expansion, Next: Variable expansion, Up: Path expansion
680
681 5.3.1 Default expansion
682 -----------------------
683
684 If the highest-priority search path (*note Path sources::) contains an
685 “extra colon” (i.e., leading, trailing, or doubled), Kpathsea inserts at
686 that point the next-highest-priority search path that is defined. If
687 that inserted path has an extra colon, the same happens with the
688 next-highest. (An extra colon in the compile-time default value has
689 unpredictable results, so installers beware.)
690
691 For example, given an environment variable setting
692
693 setenv TEXINPUTS /home/karl:
694
695 and a ‘TEXINPUTS’ value from ‘texmf.cnf’ of
696
697 .:$TEXMF//tex
698
699 then the final value used for searching will be:
700
701 /home/karl:.:$TEXMF//tex
702
703 Put another way, default expansion works on "formats" (search paths),
704 and not directly on environment variables. Example, showing the
705 trailing ‘:’ ignored in the first case and expanded in the second:
706
707 $ env TTFONTS=/tmp: kpsewhich --expand-path '$TTFONTS'
708 /tmp
709 $ env TTFONTS=/tmp: kpsewhich --show-path=.ttf
710 /tmp:.:/home/olaf/texmf/fonts/truetype//:...
711
712 Since Kpathsea looks for multiple configuration files, it would be
713 natural to expect that (for example) an extra colon in ‘./texmf.cnf’
714 would expand to the path in ‘$TEXMF/texmf.cnf’. Or, with Dvips'
715 configuration files, that an extra colon in ‘config.$PRINTER’ would
716 expand to the path in ‘config.ps’. This doesn't happen. It's not clear
717 this would be desirable in all cases, and trying to devise a way to
718 specify the path to which the extra colon should expand seemed truly
719 baroque.
720
721 Technicality: Since it would be useless to insert the default value
722 in more than one place, Kpathsea changes only one extra ‘:’ and leaves
723 any others in place (they will eventually be ignored). Kpathsea checks
724 first for a leading ‘:’, then a trailing ‘:’, then a doubled ‘:’.
725
726 You can trace this by debugging "paths" (*note Debugging::). Default
727 expansion is implemented in the source file ‘kpathsea/kdefault.c’.
728
729 
730 File: kpathsea.info, Node: Variable expansion, Next: Tilde expansion, Prev: Default expansion, Up: Path expansion
731
732 5.3.2 Variable expansion
733 ------------------------
734
735 ‘$foo’ or ‘${foo}’ in a path element is replaced by (1) the value of an
736 environment variable ‘foo’ (if defined); (2) the value of ‘foo’ from
737 ‘texmf.cnf’ (if defined); (3) the empty string.
738
739 If the character after the ‘$’ is alphanumeric or ‘_’, the variable
740 name consists of all consecutive such characters. If the character
741 after the ‘$’ is a ‘{’, the variable name consists of everything up to
742 the next ‘}’ (braces may not be nested around variable names).
743 Otherwise, Kpathsea gives a warning and ignores the ‘$’ and its
744 following character.
745
746 You must quote the $'s and braces as necessary for your shell.
747 _Shell_ variable values cannot be seen by Kpathsea, i.e., ones defined
748 by ‘set’ in C shells and without ‘export’ in Bourne shells.
749
750 For example, given
751 setenv tex /home/texmf
752 setenv TEXINPUTS .:$tex:${tex}prev
753 the final ‘TEXINPUTS’ path is the three directories:
754 .:/home/texmf:/home/texmfprev
755
756 The ‘.PROGNAME’ suffix on variables and ‘_PROGNAME’ on environment
757 variable names are not implemented for general variable expansions.
758 These are only recognized when search paths are initialized (*note Path
759 sources::).
760
761 Variable expansion is implemented in the source file
762 ‘kpathsea/variable.c’.
763
764 
765 File: kpathsea.info, Node: Tilde expansion, Next: Brace expansion, Prev: Variable expansion, Up: Path expansion
766
767 5.3.3 Tilde expansion
768 ---------------------
769
770 A leading ‘~’ in a path element is replaced by the value of the
771 environment variable ‘HOME’, or ‘.’ if ‘HOME’ is not set. On Windows,
772 the environment variable ‘USERPROFILE’ is checked instead of ‘HOME’.
773
774 A leading ‘~USER’ in a path element is replaced by USER's home
775 directory from the system ‘passwd’ database.
776
777 For example,
778 setenv TEXINPUTS ~/mymacros:
779
780 will prepend a directory ‘mymacros’ in your home directory to the
781 default path.
782
783 As a special case, if a home directory ends in ‘/’, the trailing
784 slash is dropped, to avoid inadvertently creating a ‘//’ construct in
785 the path. For example, if the home directory of the user ‘root’ is ‘/’,
786 the path element ‘~root/mymacros’ expands to just ‘/mymacros’, not
787 ‘//mymacros’.
788
789 Tilde expansion is implemented in the source file ‘kpathsea/tilde.c’.
790
791 
792 File: kpathsea.info, Node: Brace expansion, Next: KPSE_DOT expansion, Prev: Tilde expansion, Up: Path expansion
793
794 5.3.4 Brace expansion
795 ---------------------
796
797 ‘x{A,B}y’ expands to ‘xAy:xBy’. For example:
798
799 foo/{1,2}/baz
800
801 expands to ‘foo/1/baz:foo/2/baz’. ‘:’ is the path separator on the
802 current system; e.g., on a Windows system, it's ‘;’.
803
804 Braces can be nested; for example, ‘x{A,B{1,2}}y’ expands to
805 ‘xAy:xB1y:xB2y’.
806
807 Multiple non-nested braces are expanded from right to left; for
808 example, ‘x{A,B}{1,2}y’ expands to ‘x{A,B}1y:x{A,B}2y’, which expands to
809 ‘xA1y:xB1y:xA2y:xB2y’.
810
811 This feature can be used to implement multiple TeX hierarchies, by
812 assigning a brace list to ‘$TEXMF’, as mentioned in ‘texmf.in’.
813
814 You can also use the path separator instead of the comma. The last
815 example could have been written ‘x{A:B}{1:2}y’ (on Unix).
816
817 Brace expansion is implemented in the source file
818 ‘kpathsea/expand.c’.
819
820 
821 File: kpathsea.info, Node: KPSE_DOT expansion, Next: Subdirectory expansion, Prev: Brace expansion, Up: Path expansion
822
823 5.3.5 ‘KPSE_DOT’ expansion
824 --------------------------
825
826 When ‘KPSE_DOT’ is defined in the environment, it names a directory that
827 should be considered the current directory for the purpose of looking up
828 files in the search paths. This feature is needed by the ‘mktex...’
829 scripts *note mktex scripts::, because these change the working
830 directory. You should not ever define it yourself.
831
832 
833 File: kpathsea.info, Node: Subdirectory expansion, Prev: KPSE_DOT expansion, Up: Path expansion
834
835 5.3.6 Subdirectory expansion
836 ----------------------------
837
838 Two or more consecutive slashes in a path element following a directory
839 D is replaced by all subdirectories of D: first those subdirectories
840 directly under D, then the subsubdirectories under those, and so on. At
841 each level, the order in which the directories are searched is
842 unspecified. (It's "directory order", and definitely not alphabetical.)
843
844 If you specify any filename components after the ‘//’, only
845 subdirectories which match those components are included. For example,
846 ‘/a//b’ would expand into directories ‘/a/1/b’, ‘/a/2/b’, ‘/a/1/1/b’,
847 and so on, but not ‘/a/b/c’ or ‘/a/1’.
848
849 You can include multiple ‘//’ constructs in the path.
850
851 ‘//’ at the beginning of a path is ignored. Searching every
852 directory on the system is not relevant for TeX.
853
854 We need to discuss one related implementation trick, originally taken
855 from GNU find. Matthew Farwell suggested it, and David MacKenzie
856 implemented it.
857
858 The trick is that in normal Unix implementations (though not in the
859 POSIX specification), a directory which contains no subdirectories will
860 have exactly two links (namely, one for ‘.’ and one for ‘..’). That is
861 to say, the ‘st_nlink’ field in the ‘stat’ structure will be two. Thus,
862 we don't have to stat everything in the bottom-level (leaf)
863 directories--we can just check ‘st_nlink’, notice it's two, and do no
864 more work.
865
866 Kpathsea never does this ‘st_nlink=2’ check (or any disk checking)
867 for ‘!!’ trees (*note ls-R::). And the non-‘!!’ trees in a TeX Live
868 installation are typically extremely small. Therefore the ‘st_nlink’
869 check is not performed by default at all, as of 2025 (Kpathsea 6.3.4).
870 That way, two not-uncommon situations work out: 1) all ‘gvisor’-handled
871 filesystems return ‘st_nlink=1’ before some post-2025 release
872 (<https://tug.org/pipermail/texhax/2025-July/026772.html>); 2) a
873 symbolic link to another directory in such an apparent leaf directory
874 will get followed even though ‘st_nlink=2’
875 (<https://tex.stackexchange.com/questions/132908>).
876
877 If you have an extremely large non-‘!!’ tree, most likely
878 ‘TEXMFHOME’, you may find it useful to enable the check: you can do this
879 by setting the configuration variable ‘texmf_nlink_for_leaf’ to 1.
880 Alternatively, with such a large tree, you may find it even more useful
881 to add the tree to ‘TEXMFDBS’ so that only ‘ls-R’ lookups are done
882 (again, *note ls-R::).
883
884 Unfortunately, in some cases files in leaf directories are ‘stat’'d
885 anyway: if the path specification is, say, ‘$TEXMF/fonts//pk//’, then
886 files in a subdirectory ‘.../pk’, even if it is a leaf, are checked.
887 The reason cannot be explained without reference to the implementation,
888 so read ‘kpathsea/elt-dirs.c’ (search for ‘may descend’) if you are
889 curious. And if you find a way to solve the problem, please let me
890 know.
891
892 Subdirectory expansion is implemented in the source file
893 ‘kpathsea/elt-dirs.c’.
894
895 
896 File: kpathsea.info, Node: Casefolding search, Next: Filename database, Prev: Path expansion, Up: Path searching
897
898 5.4 Casefolding search
899 ======================
900
901 In Kpathsea version 6.3.0 (released with TeX Live 2018), a new fallback
902 search was implemented on Unix-like systems, including Macs: for each
903 path element in turn, if no match is found by the normal search, and the
904 path element allows for checking the filesystem, a second check is made
905 for a case-insensitive match.
906
907 This is enabled at compile-time on Unix systems, and enabled at
908 runtime by setting the configuration variable ‘texmf_casefold_search’,
909 to a true value, e.g., ‘1’; this is done by default in TeX Live.
910
911 * Menu:
912
913 * Rationale: Casefolding rationale.
914 * Examples: Casefolding examples.
915
916 
917 File: kpathsea.info, Node: Casefolding rationale, Next: Casefolding examples, Up: Casefolding search
918
919 5.4.1 Casefolding rationale
920 ---------------------------
921
922 The purpose of the fallback casefolding search is to ease moving complex
923 documents between case-insensitive (file)systems and case-sensitive
924 ones. In particular, Apple decided to make the default filesystem on
925 Macs be case-insensitive some years ago, and this has exacerbated a
926 problem of people creating documents that use, say, an image under the
927 name ‘foo.jpg’, while the actual file is named ‘foo.JPG’ or ‘Foo.jpg’.
928 It works on the Mac but if the document is transferred and run on a
929 standard case-sensitive Unix (file)system, the file can't be found, due
930 only to differences in case.
931
932 This same problematic scenario has always existed on Windows, but for
933 whatever reason, it has become much more common since Apple also went to
934 a case-insensitive filesystem. Hence the relatively late change to the
935 Kpathsea behavior.
936
937 The fallback case-insensitive search is omitted at compile-time on
938 Windows, where (for practical purposes) all file names are
939 case-insensitive at the kernel level, and so the normal search will
940 already have definitively matched or not. Therefore, search results in
941 unusual cases can be different on Windows and Unix--but this has always
942 been true.
943
944 
945 File: kpathsea.info, Node: Casefolding examples, Prev: Casefolding rationale, Up: Casefolding search
946
947 5.4.2 Casefolding examples
948 --------------------------
949
950 The casefolding implementation prefers exact matches to casefolded
951 matches within a given path element, so as to retain most compatibility.
952 Backward compatibility is not perfect, however, as a casefolded match
953 may be found in an earlier path element than an exact match was
954 previously found (see example #4 below). Still, preferring the match in
955 the earlier element seemed potentially less confusing than otherwise,
956 and is in fact consistent with past behavior on Windows. Since case
957 mismatches are rare to begin with, and name collisions with respect only
958 to case thus even more rare, the hope is that it will not cause
959 difficulties in practice.
960
961 If it's desirable in a given situation to have the exact same search
962 behavior as previously, that can be accomplished by setting the
963 configuration variable ‘texmf_casefold_search’ to ‘0’ (*note Path
964 sources::).
965
966 Some examples to illustrate the new behavior follow.
967
968 Example #1: suppose the file ‘./foobar.tex’ exists. Now, searching
969 for ‘./FooBar.TeX’ (or any other case variation) will succeed, returning
970 ‘./foobar.tex’--the name as stored on disk. In previous releases, or if
971 ‘texmf_casefold_search’ is false, the search would fail.
972
973 Example #2: suppose we are using a case-sensitive (file)system, and
974 the search path is ‘.:/somedir’, and the files ‘./foobar.tex’ and
975 ‘/somedir/FooBar.TeX’ both exist. Both now and previously, searching
976 for ‘foobar.tex’ returns ‘./foobar.tex’. However, searching for
977 ‘FooBar.TeX’ now returns ‘./foobar.tex’ instead of
978 ‘/somedir/FooBar.TeX’; this is the incompatibility mentioned above.
979 Also (as expected), searching for ‘FOOBAR.TEX’ (or whatever variation)
980 will now return ‘./foobar.tex’, whereas before it would fail. Searching
981 for all (‘kpsewhich --all’) ‘foobar.tex’ will return both matches.
982
983 Example #3: same as example #2, but on a case-insensitive
984 (file)system: both now and previously, searching for ‘FooBar.TeX’
985 returns ‘./foobar.tex’, since the system considers that a match. The
986 Kpathsea casefolding never comes into play.
987
988 Example #4: if we have (on a case-sensitive system) both
989 ‘./foobar.tex’ and ‘./FOOBAR.TEX’, searching with the exact case returns
990 that exact match, now and previously. Searching for ‘FooBar.tex’ will
991 now return one or the other (chosen arbitrarily), rather than failing.
992 Perhaps unexpectedly, searching for all ‘foobar.tex’ or ‘FooBar.tex’
993 will also return only one or the other, not both (see more below).
994
995 Example #5: the font file ‘STIX-Regular.otf’ is included in TeX Live
996 in the system directory ‘texmf-dist/fonts/opentype/public/stix’.
997 Because Kpathsea never searches the disk in the big system directory,
998 the casefolding is not done, and a search for ‘stix-regular.otf’ will
999 fail (on case-sensitive systems), as it always has.
1000
1001 The caveat about not searching the disk amounts to saying that
1002 casefolding does not happen in the trees specified with ‘!!’ (*note
1003 ls-R::), that is, where only database (‘ls-R’) searching is done. In
1004 TeX Live, that is the ‘texmf-local’ and ‘texmf-dist’ trees (also
1005 ‘$TEXMFSYSCONFIG’ and ‘$TEXMFSYSVAR’, but those are rarely noticed).
1006 The rationale for this is that in practice, case mangling happens with
1007 user-created files, not with packages distributed as part of the TeX
1008 system.
1009
1010 One more caveat: the purpose of ‘kpsewhich’ is to exercise the path
1011 searching in Kpathsea as it is actually done. Therefore, as shown
1012 above, ‘kpsewhich --all’ will not return all matches regardless of case
1013 within a given path element. If you want to find all matches in all
1014 directories, ‘find’ is the best tool, although the setup takes a couple
1015 steps:
1016
1017 kpsewhich -show-path=tex >/tmp/texpath # search path specification
1018 kpsewhich -expand-path="`cat /tmp/texpath`" >/tmp/texdirs # all dirs
1019 tr ':' '\n' </tmp/texdirs >/tmp/texdirlist # colons to newlines
1020 find `cat /tmp/texdirlist` -iname somefile.tex -print </tmp/texdirlist
1021
1022 Sorry that it's annoyingly lengthy, but implementing this inside
1023 Kpathsea would be a lot of error-prone trouble for something that is
1024 only useful for debugging. If your ‘find’ does not support ‘-iname’,
1025 you can get GNU Find from <https://gnu.org/software/findutils>.
1026
1027 The casefolding search is implemented in the source file
1028 ‘kpathsea/pathsearch.c’. Two implementation points:
1029
1030 • Kpathsea never tries to check if a given directory resides on a
1031 case-insensitive filesystem, because there is no efficient and
1032 portable way to do so. All it does is try to see if a potential
1033 file name is a readable normal file (with, usually, the ‘access’
1034 system call).
1035
1036 • Kpathsea does not do any case-insensitive matching of the
1037 directories along the path. It's not going to find
1038 ‘/Some/Random/file.tex’ when looking for ‘/some/random/file.tex’.
1039 The casefolding only happens with the elements of the leaf
1040 directory.
1041
1042 
1043 File: kpathsea.info, Node: Filename database, Next: Invoking kpsewhich, Prev: Casefolding search, Up: Path searching
1044
1045 5.5 Filename database (‘ls-R’)
1046 ==============================
1047
1048 Kpathsea goes to some lengths to minimize disk accesses for searches
1049 (*note Subdirectory expansion::). Nevertheless, in practice searching
1050 every possible directory in typical TeX installations takes an
1051 excessively long time.
1052
1053 Therefore, Kpathsea can use an externally-built “filename database”
1054 file named ‘ls-R’ that maps files to directories, thus avoiding the need
1055 to exhaustively search the disk.
1056
1057 A second database file ‘aliases’ allows you to give additional names
1058 to the files listed in ‘ls-R’.
1059
1060 The ‘ls-R’ and ‘aliases’ features are implemented in the source file
1061 ‘kpathsea/db.c’.
1062
1063 * Menu:
1064
1065 * ls-R:: The main filename database.
1066 * Filename aliases:: Aliases for those names.
1067 * Database format:: Syntax details of the database file.
1068
1069 
1070 File: kpathsea.info, Node: ls-R, Next: Filename aliases, Up: Filename database
1071
1072 5.5.1 ‘ls-R’
1073 ------------
1074
1075 As mentioned above, you must name the main filename database ‘ls-R’.
1076 You can put one at the root of each TeX installation hierarchy you wish
1077 to search (‘$TEXMF’ by default, which expands to a braced list of
1078 several hierarchies in TeX Live).
1079
1080 Kpathsea looks for ‘ls-R’ files along the ‘TEXMFDBS’ path. It is
1081 best for this to contain all and only those hierarchies from ‘$TEXMF’
1082 which are specified with ‘!!’--and also to specify them with ‘!!’ in
1083 ‘TEXMFDBS’. (See the end of this section for more on ‘!!’.)
1084
1085 The recommended way to create and maintain ‘ls-R’ is to run the
1086 ‘mktexlsr’ script, which is installed in ‘$(bindir)’ (‘/usr/local/bin’
1087 by default). That script goes to some trouble to follow symbolic links
1088 as necessary, etc. It's also invoked by the distributed ‘mktex...’
1089 scripts.
1090
1091 At its simplest, though, you can build ‘ls-R’ with the command
1092 cd /YOUR/TEXMF/ROOT && ls -LAR ./ >ls-R
1093
1094 presuming your ‘ls’ produces the right output format (see the section
1095 below). GNU ‘ls’, for example, outputs in this format. Also presuming
1096 your ‘ls’ hasn't been aliased in a system file (e.g., ‘/etc/profile’) to
1097 something problematic, e.g., ‘ls --color=tty’. In that case, you will
1098 have to disable the alias before generating ‘ls-R’. For the precise
1099 definition of the file format, see *note Database format::.
1100
1101 Regardless of whether you use the supplied script or your own, you
1102 will almost certainly want to invoke it via ‘cron’, so when you make
1103 changes in the installed files (say if you install a new LaTeX package),
1104 ‘ls-R’ will be automatically updated. However, for those using TeX Live
1105 or system distributions, the package managers should run ‘mktexlsr’ as
1106 needed.
1107
1108 The ‘-A’ option to ‘ls’ includes files beginning with ‘.’ (except for
1109 ‘.’ and ‘..’), such as the file ‘.tex’ included with the LaTeX tools
1110 package. (On the other hand, _directories_ whose names begin with ‘.’
1111 are always ignored.)
1112
1113 If your system does not support symbolic links, omit the ‘-L’.
1114
1115 ‘ls -LAR /YOUR/TEXMF/ROOT’ will also work. But using ‘./’ avoids
1116 embedding absolute pathnames, so the hierarchy can be easily
1117 transported. It also avoids possible trouble with automounters or other
1118 network filesystem conventions.
1119
1120 Kpathsea warns you if it finds an ‘ls-R’ file, but the file does not
1121 contain any usable entries. The usual culprit is running plain ‘ls -R’
1122 instead of ‘ls -LR ./’ or ‘ls -R /YOUR/TEXMF/ROOT’. Another possibility
1123 is some system directory name starting with a ‘.’ (perhaps if you are
1124 using AFS); Kpathsea ignores everything under such directories.
1125
1126 If a particular path element begins with ‘!!’, _only_ the database
1127 will be searched for that element, never the disk; and if the database
1128 does not exist, nothing at all will be searched. In TeX Live, most of
1129 the trees are specified with ‘!!’.
1130
1131 For path elements that do not begin with ‘!!’, if the database
1132 exists, it will be used, and the disk will not be searched. However, in
1133 this case, if the database does not exist, the disk will be searched.
1134 In TeX Live, the most notable case of this is the ‘TEXMFHOME’ tree, to
1135 allow users to add and remove files from their own tree without having
1136 to worry about ‘ls-R’.
1137
1138 (Aside: there are uncommon cases where a ‘!!’ tree will be searched
1139 on disk even if the ‘ls-R’ file exists; they are too obscure to try to
1140 explain here. See ‘pathsearch.c’ in the source if you need to know.)
1141
1142 To sum up: do not create an ‘ls-R’ file unless you also take care to
1143 keep it up to date. Otherwise newly-installed files will not be found.
1144
1145 
1146 File: kpathsea.info, Node: Filename aliases, Next: Database format, Prev: ls-R, Up: Filename database
1147
1148 5.5.2 Filename aliases
1149 ----------------------
1150
1151 In some circumstances, you may wish to find a file under several names.
1152 For example, suppose a TeX document was created using a DOS system and
1153 tries to read ‘longtabl.sty’. But now it's being run on a Unix system,
1154 and the file has its original name, ‘longtable.sty’. The file won't be
1155 found. You need to give the actual file ‘longtable.sty’ an alias
1156 ‘longtabl.sty’.
1157
1158 You can handle this by creating a file ‘aliases’ as a companion to
1159 the ‘ls-R’ for the hierarchy containing the file in question. (You must
1160 have an ‘ls-R’ for the alias feature to work.)
1161
1162 The format of ‘aliases’ is simple: two whitespace-separated words per
1163 line; the first is the real name ‘longtable.sty’, and second is the
1164 alias (‘longtabl.sty’). These must be base filenames, with no directory
1165 components. ‘longtable.sty’ must be in the sibling ‘ls-R’.
1166
1167 Also, blank lines and lines starting with ‘%’ or ‘#’ are ignored in
1168 ‘aliases’, to allow for comments.
1169
1170 If a real file ‘longtabl.sty’ exists, it is used regardless of any
1171 aliases.
1172
1173 
1174 File: kpathsea.info, Node: Database format, Prev: Filename aliases, Up: Filename database
1175
1176 5.5.3 Database format
1177 ---------------------
1178
1179 The "database" read by Kpathsea is a line-oriented file of plain text.
1180 The format is that generated by GNU (and most other) ‘ls’ programs given
1181 the ‘-R’ option, as follows.
1182
1183 • Blank lines are ignored.
1184
1185 • If a line begins with ‘/’ or ‘./’ or ‘../’ and ends with a colon,
1186 it's the name of a directory. (‘../’ lines aren't useful, however,
1187 and should not be generated.)
1188
1189 • All other lines define entries in the most recently seen directory.
1190 /'s in such lines will produce possibly-strange results.
1191
1192 • Files with no preceding directory line are ignored.
1193
1194 For example, here's the first few lines of ‘ls-R’ (which totals about
1195 30K bytes) on my system:
1196
1197 bibtex
1198 dvips
1199 fonts
1200 ls-R
1201 metafont
1202 metapost
1203 tex
1204 web2c
1205
1206 ./bibtex:
1207 bib
1208 bst
1209 doc
1210
1211 ./bibtex/bib:
1212 asi.bib
1213 btxdoc.bib
1214 ...
1215
1216 
1217 File: kpathsea.info, Node: Invoking kpsewhich, Prev: Filename database, Up: Path searching
1218
1219 5.6 ‘kpsewhich’: Standalone path searching
1220 ==========================================
1221
1222 The Kpsewhich program exercises the path searching functionality
1223 independent of any particular application. This can also be useful as a
1224 sort of ‘find’ program to locate files in your TeX hierarchies, perhaps
1225 in administrative scripts. It is used heavily in the distributed
1226 ‘mktex...’ scripts.
1227
1228 Synopsis:
1229
1230 kpsewhich OPTION... FILENAME...
1231
1232 The options and filename(s) to look up can be intermixed. Options
1233 can start with either ‘-’ or ‘--’, and any unambiguous abbreviation is
1234 accepted.
1235
1236 Kpsewhich looks up each non-option argument on the command line as a
1237 filename, and outputs (by default) the first file found to standard
1238 output. If a file is not found, and more than FILENAME is given, a
1239 blank line is output for that file. See examples below.
1240
1241 The exit status is zero if all files were found, nonzero otherwise.
1242
1243 * Menu:
1244
1245 * kpsewhich examples:: Simple examples of running kpsewhich.
1246 * Path searching options:: Changing the mode, resolution, etc.
1247 * Specially-recognized files:: Default formats for texmf.cnf, etc.
1248 * Auxiliary tasks:: Path and variable expansion, etc.
1249 * Standard options:: ‘--help’ and ‘--version’.
1250
1251 
1252 File: kpathsea.info, Node: kpsewhich examples, Next: Path searching options, Up: Invoking kpsewhich
1253
1254 5.6.1 ‘kpsewhich’ examples
1255 --------------------------
1256
1257 Some examples of running ‘kpsewhich’ with a typical TeX tree. A basic
1258 successful search (exit status 0):
1259
1260 $ kpsewhich plain.tex
1261 /usr/local/texlive/2024/texmf-dist/tex/plain/base/plain.tex
1262
1263 Searching for multiple files, one of which is not found (exit status
1264 is 1 for this):
1265
1266 $ kpsewhich plain.tex foobar plain.mf
1267 /usr/local/texlive/2024/texmf-dist/tex/plain/base/plain.tex
1268
1269 /usr/local/texlive/2024/texmf-dist/metafont/base/plain.mf
1270
1271 Using ‘--all’ to see all files by the same name (exit status 0):
1272
1273 $ kpsewhich --all language.dat
1274 /usr/local/texlive/2024/texmf-dist/tex/generic/config/language.dat
1275 /usr/local/texlive/2024/texmf-dist/lambda/generic/config/language.dat
1276
1277 
1278 File: kpathsea.info, Node: Path searching options, Next: Specially-recognized files, Prev: kpsewhich examples, Up: Invoking kpsewhich
1279
1280 5.6.2 Path searching options
1281 ----------------------------
1282
1283 Various options alter the path searching behavior. Options apply to all
1284 lookups.
1285
1286 ‘--all’
1287 Report all matches found, one per line. By default, if there is
1288 more than one match, just one will be reported (chosen effectively
1289 at random). Exception: with the glyph formats (‘pk’, ‘gf’), this
1290 option has no effect and only the first match is returned.
1291
1292 With both ‘-all’ and multiple input files, there's no easy way to
1293 discern which matches belong to which files; you have to check the
1294 basename of the output. This could be improved, if there is any
1295 demand.
1296
1297 ‘--casefold-search’
1298 ‘--no-casefold-search’
1299 Explicitly enable or disable the fallback to a case-insensitive
1300 search on Unix platforms (*note Casefolding search::); no effect on
1301 Windows. The default is enabled, set in ‘texmf.cnf’. Disabling
1302 (‘--no-casefold-search’) does not mean that searches magically
1303 become case-sensitive when the underlying (file)system is
1304 case-insensitive, it merely means that Kpathsea does not do any
1305 casefolding itself.
1306
1307 ‘--cnf-line=STR’
1308 Parse STR as if it were a line in the ‘texmf.cnf’ configuration
1309 file (*note Config files::), overriding settings in the actual
1310 configuration files, and also in the environment (*note Path
1311 sources::). This is implemented by making any settings from STR in
1312 the environment, overwriting any value already there. Thus, an
1313 extra colon in a ‘--cnf-line’ value will refer to the value from a
1314 configuration file, not a user-set environment variable.
1315
1316 Furthermore, any variable set from STR will also be set with the
1317 program name suffix. For example, ‘pdftex
1318 --cnf-line=TEXINPUTS=/foo:’ will set both ‘TEXINPUTS’ and
1319 ‘TEXINPUTS_pdftex’ in the environment (and the value will be ‘/foo’
1320 followed by the setting from ‘texmf.cnf’, ignoring any user-set
1321 ‘TEXINPUTS’).
1322
1323 This behavior is desirable because, in practice, many variables in
1324 the distributed ‘texmf.cnf’ are program-specific, and the intuitive
1325 behavior is for values set on the command line with ‘--cnf-line’ to
1326 override them.
1327
1328 ‘--dpi=NUM’
1329 Set the resolution to NUM; this only affects ‘gf’ and ‘pk’ lookups.
1330 ‘-D’ is a synonym, for compatibility with Dvips. Default is 600.
1331
1332 ‘--engine=NAME’
1333 Set the engine name to NAME. By default it is not set in
1334 ‘kpsewhich’ (TeX engines set it to the appropriate string). The
1335 engine name is used in some search paths to allow files with the
1336 same name but used by different engines to coexist.
1337
1338 In particular, since the memory dump files (‘.fmt’/‘.base’/‘.mem’)
1339 are now stored in subdirectories named for the engine (‘tex’,
1340 ‘pdftex’, ‘xetex’, etc.), you must specify an engine name in order
1341 to find them. For example, ‘cont-en.fmt’ typically exists for both
1342 ‘pdftex’ and ‘xetex’. With the default path settings, you can use
1343 ‘--engine=/’ to look for any dump file, regardless of engine; if a
1344 dump file exists for more than one engine, it's indeterminate which
1345 one is returned. (The ‘/’ ends up specifying a normal recursive
1346 search along the path where the dumps are stored, namely
1347 ‘$TEXMF/web2c{/$engine,}’.)
1348
1349 ‘--format=NAME’
1350 Set the format for lookup to NAME. By default, the format is
1351 guessed from the filename, with ‘tex’ being used if nothing else
1352 fits. The recognized filename extensions (including any leading
1353 ‘.’) are also allowable NAMEs.
1354
1355 All formats also have a name, which is the only way to specify
1356 formats with no associated suffix. For example, for Dvips
1357 configuration files you can use ‘--format="dvips config"’. (The
1358 quotes are for the sake of the shell.)
1359
1360 Here's the current list of recognized names and the associated
1361 suffixes. *Note Supported file formats::, for more information on
1362 each of these.
1363
1364 The strings in parentheses are abbreviations recognized only by
1365 ‘kpsewhich’ (not the underlying library calls). They are provided
1366 when it would otherwise require an argument containing a space to
1367 specify the format, to simplify quoting of calls from shells.
1368
1369 gf: gf
1370 pk: pk
1371 bitmap font (bitmapfont):
1372 tfm: .tfm
1373 afm: .afm
1374 base: .base
1375 bib: .bib
1376 bst: .bst
1377 cnf: .cnf
1378 ls-R: ls-R ls-r
1379 fmt: .fmt
1380 map: .map
1381 mem: .mem
1382 mf: .mf
1383 mfpool: .pool
1384 mft: .mft
1385 mp: .mp
1386 mppool: .pool
1387 MetaPost support (mpsupport):
1388 ocp: .ocp
1389 ofm: .ofm .tfm
1390 opl: .opl .pl
1391 otp: .otp
1392 ovf: .ovf .vf
1393 ovp: .ovp .vpl
1394 graphic/figure: .eps .epsi
1395 tex: .tex .sty .cls .fd .aux .bbl .def .clo .ldf
1396 TeX system documentation (doc):
1397 texpool: .pool
1398 TeX system source (source, src): .dtx .ins
1399 PostScript header (psheader): .pro
1400 Troff fonts (trofffont):
1401 type1 fonts: .pfa .pfb
1402 vf: .vf
1403 dvips config (dvipsconfig):
1404 ist: .ist
1405 truetype fonts (truetype, ttf): .ttf .ttc .TTF .TTC .dfont
1406 type42 fonts (type42): .t42 .T42
1407 web2c files (web2c):
1408 other text files (othertext):
1409 other binary files (otherbin):
1410 misc fonts (miscfont):
1411 web: .web .ch
1412 cweb: .w .web .ch
1413 enc files (enc): .enc
1414 cmap files (cmap):
1415 subfont definition files (sfd): .sfd
1416 opentype fonts (opentype, otf): .otf .OTF
1417 pdftex config (pdftexconfig):
1418 lig files (lig): .lig
1419 texmfscripts:
1420 lua: .lua .luatex .luc .luctex .texlua .texluc .tlu
1421 font feature files (fea): .fea
1422 cid maps (cidmap): .cid .cidmap
1423 mlbib: .mlbib .bib
1424 mlbst: .mlbst .bst
1425 clua: .dll .so
1426 ris: .ris
1427 bltxml: .bltxml
1428
1429 This option and ‘--path’ are mutually exclusive.
1430
1431 ‘--interactive’
1432 After processing the command line, read additional filenames to
1433 look up from standard input.
1434
1435 ‘--mktex=FILETYPE’
1436 ‘--no-mktex=FILETYPE’
1437 Turn on or off the ‘mktex’ script associated with FILETYPE. Usual
1438 values for FILETYPE are ‘pk’, ‘mf’, ‘tex’, and ‘tfm’. By default,
1439 all are off in Kpsewhich, even if they are enabled for TeX. This
1440 option implies setting ‘--must-exist’. *Note mktex scripts::.
1441
1442 ‘--mode=STRING’
1443 Set the mode name to STRING; this also only affects ‘gf’ and ‘pk’
1444 lookups. No default: any mode will be found. *Note mktex script
1445 arguments::.
1446
1447 ‘--must-exist’
1448 Do everything possible to find the files, notably including
1449 searching the disk and running the ‘mktex’ scripts. By default,
1450 only the ‘ls-R’ database is checked, in the interest of efficiency.
1451
1452 ‘--path=STRING’
1453 Search along the path STRING (colon-separated as usual), instead of
1454 guessing the search path from the filename. ‘//’ and all the usual
1455 expansions are supported (*note Path expansion::). This option and
1456 ‘--format’ are mutually exclusive. To output the complete
1457 directory expansion of a path, instead of doing a one-shot lookup,
1458 see ‘--expand-path’ and ‘--show-path’ in the following section.
1459
1460 ‘--progname=NAME’
1461 Set the program name to NAME; default is ‘kpsewhich’. This can
1462 affect the search paths via the ‘.PROGNAM’ feature in configuration
1463 files (*note Config files::).
1464
1465 ‘--subdir=STRING’
1466 Report only those matches whose directory part _ends_ with STRING
1467 (compared literally, except case is ignored on a case-insensitive
1468 operating system). For example, suppose there are two matches for
1469 a given name:
1470
1471 kpsewhich foo.sty
1472 ⇒ /some/where/foo.sty
1473 /another/place/foo.sty
1474
1475 Then we can narrow the result to what we are interested in with
1476 ‘--subdir’:
1477
1478 kpsewhich --subdir=where foo.sty
1479 ⇒ /some/where/foo.sty
1480
1481 kpsewhich --subdir=place foo.sty
1482 ⇒ /another/place/foo.sty
1483
1484 The string to match must be at the end of the directory part of the
1485 match, and it is taken literally, with no pattern matching:
1486
1487 kpsewhich --subdir=another foo.sty
1488 ⇒
1489
1490 The string to match may cross directory components:
1491
1492 kpsewhich --subdir=some/where foo.sty
1493 ⇒ /some/where/foo.sty
1494
1495 ‘--subdir’ implies ‘--all’; if there is more than one match, they
1496 will all be reported (in our example, both ‘where’ and ‘place’ end
1497 in ‘e’):
1498
1499 kpsewhich --subdir=e
1500 ⇒ /some/where/foo.sty
1501 /another/place/foo.sty
1502
1503 Because of the above rules, the presence of a leading ‘/’ is
1504 important, since it "anchors" the match to a full component name:
1505
1506 kpsewhich --subdir=/lace foo.sty
1507 ⇒
1508
1509 However, a trailing ‘/’ is immaterial (and ignored), since the
1510 match always takes place at the end of the directory part:
1511
1512 kpsewhich --subdir=lace/ foo.sty
1513 ⇒ /another/place/foo.sty
1514
1515 The purpose of these rules is to make it convenient to find results
1516 only within a particular area of the tree. For instance, a given
1517 script named ‘foo.lua’ might exist within both
1518 ‘texmf-dist/scripts/pkg1/’ and ‘texmf-dist/scripts/pkg2/’. By
1519 specifying, say, ‘--subdir=/pkg1’, you can be sure of getting the
1520 one you are interested in.
1521
1522 We only match at the end because a site might happen to install TeX
1523 in ‘/some/coincidental/pkg1/path/’, and we wouldn't want to match
1524 ‘texmf-dist/scripts/pkg2/’ that when searching for ‘/pkg1’.
1525
1526 
1527 File: kpathsea.info, Node: Specially-recognized files, Next: Auxiliary tasks, Prev: Path searching options, Up: Invoking kpsewhich
1528
1529 5.6.3 Specially-recognized files for ‘kpsewhich’
1530 ------------------------------------------------
1531
1532 ‘kpsewhich’ recognizes a few special filenames on the command line and
1533 defaults to using the 'known' file formats for them, merely to save the
1534 time and trouble of specifying the format. This is only a feature of
1535 ‘kpsewhich’; when using the Kpathsea library itself, none of these
1536 special filenames are recognized, and it's still up to the caller to
1537 specify the desired format.
1538
1539 Here is the list of special filenames to ‘kpsewhich’, along with
1540 their corresponding format:
1541
1542 ‘config.ps’
1543 ‘dvips config’
1544
1545 ‘dvipdfmx.cfg’
1546 ‘other text files’
1547
1548 ‘fmtutil.cnf’
1549 ‘web2c files’
1550
1551 ‘glyphlist.txt’
1552 ‘map’
1553
1554 ‘mktex.cnf’
1555 ‘web2c files’
1556
1557 ‘pdfglyphlist.txt’
1558 ‘map’
1559
1560 ‘pdftex.cfg’
1561 ‘pdftex config’ (although ‘pdftex.cfg’ is not used any more; look
1562 for the file ‘pdftexconfig.tex’ instead.)
1563
1564 ‘texmf.cnf’
1565 ‘cnf’
1566
1567 ‘XDvi’
1568 ‘other text files’
1569
1570 A user-specified format will override the above defaults.
1571
1572 Another reference for information about TeX's many special files is
1573 ‘tcfmgr.map’, found in ‘texmf/texconfig/tcfmgr.map’, which records
1574 various information about the above configuration files (among others).
1575
1576 
1577 File: kpathsea.info, Node: Auxiliary tasks, Next: Standard options, Prev: Specially-recognized files, Up: Invoking kpsewhich
1578
1579 5.6.4 Auxiliary tasks
1580 ---------------------
1581
1582 Kpsewhich provides some features in addition to path lookup as such:
1583
1584 ‘--debug=NUM’
1585 Set debugging options to NUM. *Note Debugging::.
1586
1587 ‘--expand-braces=STRING’
1588 Output variable, tilde, and brace expansion of STRING, which is
1589 assumed to be a single path element. *Note Path expansion::.
1590
1591 ‘--expand-path=STRING’
1592 Output the complete expansion of STRING, with each element
1593 separated by the usual path separator on the current system (‘;’ on
1594 Windows, ‘:’ otherwise). This may be useful to construct a custom
1595 search path for a format not otherwise supported. To retrieve the
1596 search path for a format that is already supported, see
1597 ‘--show-path’.
1598
1599 Nonexistent directories are culled from the output:
1600
1601 $ kpsewhich --expand-path '/tmp'
1602 ⇒ /tmp
1603 $ kpsewhich --expand-path '/nonesuch'
1604 ⇒
1605
1606 For one-shot uses of an arbitrary (not built in to Kpathsea) path,
1607 see ‘--path’ (*note Path searching options::).
1608
1609 ‘--expand-var=STRING’
1610 Output the variable and tilde expansion of STRING. For example,
1611 with the usual ‘texmf.cnf’, ‘kpsewhich --expand-var='$TEXMF'’
1612 returns the TeX system hierarchy root(s). *Note Path expansion::.
1613 The specified STRING can contain anything, though, not just
1614 variable references. This calls ‘kpse_var_expand’ (*note
1615 Programming with config files::).
1616
1617 ‘--help-formats’
1618 Output information about each supported format (*note Supported
1619 file formats::), including the names and abbreviations, variables
1620 looked for, and the original path.
1621
1622 ‘--safe-extended-in-name=NAME’
1623 ‘--safe-extended-out-name=NAME’
1624 As with ‘--safe-in-name’ and ‘--safe-out-name’ (next item), but
1625 also allow files under the variables ‘TEXMFVAR’ and ‘TEXMFSYSVAR’
1626 (*note Calling sequence::).
1627
1628 ‘--safe-in-name=NAME’
1629 ‘--safe-out-name=NAME’
1630 Exit successfully if NAME is safe to open for reading or writing,
1631 respectively, else unsuccessfully. No errors are output. These
1632 tests take account of the related Kpathsea configuration settings
1633 (*note Calling sequence::).
1634
1635 ‘--show-path=NAME’
1636 Show the path that would be used for file lookups of file type
1637 NAME. Either a filename extension (‘pk’, ‘.vf’, etc.) or an
1638 integer can be used, just as with ‘--format’, described in the
1639 previous section.
1640
1641 ‘--var-brace-value=VARIABLE’
1642 Like ‘--var-value’ (next), but also expands ‘{...}’ constructs.
1643 (*note Brace expansion::). Thus, the value is assumed to possibly
1644 be several path elements, and ‘~’ is expanded at the beginning of
1645 each. The path separator is changed to that of the current system
1646 in the expansion.
1647
1648 Example: ‘FOO='.;~' kpsewhich --var-brace-value=FOO’ outputs (on a
1649 Unix-ish system) ‘.:/home/karl’, supposing the latter is the
1650 current user's home directory. Note that the ‘;’ in the source
1651 value, as commonly used in ‘texmf.cnf’, has changed to a ‘:’, as
1652 the normal path separator on the current system. On a Windows-ish
1653 system, the ‘;’ would remain.
1654
1655 ‘--var-value=VARIABLE’
1656 Outputs the value of VARIABLE (a simple identifier like
1657 ‘TEXMFDIST’, with no ‘$’ or other constructs), expanding ‘$’ (*note
1658 Variable expansion::) and ‘~’ (*note Tilde expansion::) constructs
1659 in the value. ‘~’ expansion happens at the beginning of the
1660 overall value and at the beginning of a variable expansion, but not
1661 arbitrarily within the string. Braces are not expanded.
1662
1663 Example: ‘--var-value=texmf_casefold_search’ outputs (if the
1664 default is not changed) ‘1’.
1665
1666 Example to contrast with ‘--var-brace-value’: ‘FOO='.;~' kpsewhich
1667 --var-value=FOO’ outputs ‘.;~’, i.e., the same as the input value,
1668 on all systems.
1669
1670 
1671 File: kpathsea.info, Node: Standard options, Prev: Auxiliary tasks, Up: Invoking kpsewhich
1672
1673 5.6.5 Standard options
1674 ----------------------
1675
1676 Kpsewhich accepts the standard GNU options:
1677
1678 • ‘--help’ prints a help message on standard output and exits
1679 successfully.
1680
1681 • ‘--version’ prints the Kpathsea version number and exits
1682 successfully.
1683
1684 
1685 File: kpathsea.info, Node: TeX support, Next: Programming, Prev: Path searching, Up: Top
1686
1687 6 TeX support
1688 *************
1689
1690 Although the basic features in Kpathsea can be used for any type of path
1691 searching, it came about, as usual, with a specific application in mind:
1692 I wrote Kpathsea specifically for TeX system programs. I had been
1693 struggling with the programs I was using (Dvips, Xdvi, and TeX itself)
1694 having slightly different notions of how to specify paths; and debugging
1695 was painful, since no code was shared.
1696
1697 Therefore, Kpathsea provides some TeX-specific formats and features.
1698 Indeed, many of the purportedly generic path searching features were
1699 provided because they seemed useful in that conTeXt (font lookup,
1700 particularly).
1701
1702 Kpathsea provides a standard way to search for files of any of the
1703 supported file types; glyph fonts are a bit different than all the rest.
1704 Searches are based solely on names of files, not their contents--if a GF
1705 file is (mis)named ‘cmr10.600pk’, it will be found as a PK file.
1706
1707 * Menu:
1708
1709 * Supported file formats:: File types Kpathsea knows about.
1710 * File lookup:: Searching for most kinds of files.
1711 * Glyph lookup:: Searching for bitmap fonts.
1712 * Suppressing warnings:: Avoiding warnings via TEX_HUSH.
1713 * mktex scripts:: Generating files at runtime.
1714
1715 
1716 File: kpathsea.info, Node: Supported file formats, Next: File lookup, Up: TeX support
1717
1718 6.1 Supported file formats
1719 ==========================
1720
1721 Kpathsea has support for a number of file types. Each file type has a
1722 list of environment and config file variables that are checked to define
1723 the search path, and most have a default suffix that plays a role in
1724 finding files (see the next section). Some also define additional
1725 suffixes, and/or a program to be run to create missing files on the fly.
1726
1727 Since environment variables containing periods, such as
1728 ‘TEXINPUTS.latex’, are not allowed on some systems, Kpathsea looks for
1729 environment variables with an underscore, e.g., ‘TEXINPUTS_latex’ (*note
1730 Config files::).
1731
1732 The following table lists the above information. You can also get
1733 the list by giving the ‘--help-formats’ option to ‘kpsewhich’ (*note
1734 Auxiliary tasks::).
1735
1736 ‘afm’
1737 (Adobe font metrics, *note (dvips)Metric files::) ‘AFMFONTS’;
1738 suffix ‘.afm’.
1739
1740 ‘base’
1741 (Metafont memory dump, *note (web2c)Memory dumps::) ‘MFBASES’,
1742 ‘TEXMFINI’; suffix ‘.base’.
1743
1744 ‘bib’
1745 (BibTeX bibliography source, *note (web2c)bibtex invocation::)
1746 ‘BIBINPUTS’, ‘TEXBIB’; suffix ‘.bib’.
1747
1748 ‘bltxml’
1749 (BibLaTeXML bibliography files for Biber,
1750 <https://ctan.org/pkg/biber>) ‘BLTXMLINPUTS’ suffix ‘.bltxml’.
1751
1752 ‘bst’
1753 (BibTeX style, *note Basic BibTeX style files: (web2c)Basic BibTeX
1754 style files.) ‘BSTINPUTS’; suffix ‘.bst’.
1755
1756 ‘clua’
1757 (dynamic libraries for Lua, <https://ctan.org/pkg/luatex>)
1758 ‘CLUAINPUTS’ suffixes ‘.dll’ and ‘.so’.
1759
1760 ‘cmap’
1761 (character map files) ‘CMAPFONTS’; suffix ‘.cmap’.
1762
1763 ‘cnf’
1764 (Runtime configuration files, *note Config files::) ‘TEXMFCNF’;
1765 suffix ‘.cnf’.
1766
1767 ‘cweb’
1768 (CWEB input files) ‘CWEBINPUTS’; suffixes ‘.w’, ‘.web’; additional
1769 suffix ‘.ch’.
1770
1771 ‘dvips config’
1772 (Dvips ‘config.*’ files, such as ‘config.ps’, *note (dvips)Config
1773 files::) ‘TEXCONFIG’.
1774
1775 ‘enc files’
1776 (encoding vectors) ‘ENCFONTS’; suffix ‘.enc’.
1777
1778 ‘fmt’
1779 (TeX memory dump, *note (web2c)Memory dumps::) ‘TEXFORMATS’,
1780 ‘TEXMFINI’; suffix ‘.fmt’.
1781
1782 ‘font cid map’
1783 (CJK mapping) ‘FONTCIDMAPS’ suffix ‘.cid’.
1784
1785 ‘font feature files’
1786 (primarily for OpenType font features) ‘FONTFEATURES’ suffix
1787 ‘.fea’.
1788
1789 ‘gf’
1790 (generic font bitmap, *note (dvips)Glyph files::) ‘PROGRAMFONTS’,
1791 ‘GFFONTS’, ‘GLYPHFONTS’, ‘TEXFONTS’; suffix ‘gf’.
1792
1793 ‘graphic/figure’
1794 (Encapsulated PostScript figures, *note (dvips)PostScript
1795 figures::) ‘TEXPICTS’, ‘TEXINPUTS’; additional suffixes: ‘.eps’,
1796 ‘.epsi’.
1797
1798 ‘ist’
1799 (makeindex style files) ‘TEXINDEXSTYLE’, ‘INDEXSTYLE’; suffix
1800 ‘.ist’.
1801
1802 ‘lig files’
1803 (ligature definition files) ‘LIGFONTS’; suffix ‘.lig’.
1804
1805 ‘ls-R’
1806 (Filename databases, *note Filename database::) ‘TEXMFDBS’.
1807
1808 ‘lua’
1809 (Lua scripts, <https://ctan.org/pkg/luatex>) ‘LUAINPUTS’ suffixes
1810 ‘.lua’, ‘.luatex’, ‘.luc’, ‘.luctex’, ‘.texlua’, ‘.texluc’, ‘.tlu’.
1811
1812 ‘map’
1813 (Fontmaps, *note Fontmap::) ‘TEXFONTMAPS’; suffix ‘.map’.
1814
1815 ‘mem’
1816 (MetaPost memory dump, *note (web2c)Memory dumps::) ‘MPMEMS’,
1817 ‘TEXMFINI’; suffix ‘.mem’.
1818
1819 ‘MetaPost support’
1820 (MetaPost support files, used by DMP; *note (web2c)dmp
1821 invocation::) ‘MPSUPPORT’.
1822
1823 ‘mf’
1824 (Metafont source, *note (web2c)mf invocation::) ‘MFINPUTS’; suffix
1825 ‘.mf’; dynamic creation program: ‘mktexmf’.
1826
1827 ‘mfpool’
1828 (Metafont program strings, *note (web2c)pooltype invocation::)
1829 ‘MFPOOL’, ‘TEXMFINI’; suffix ‘.pool’.
1830
1831 ‘mft’
1832 (‘MFT’ style file, *note (web2c)mft invocation::) ‘MFTINPUTS’;
1833 suffix ‘.mft’.
1834
1835 ‘misc fonts’
1836 (font-related files that don't fit the other categories)
1837 ‘MISCFONTS’
1838
1839 ‘mlbib’
1840 (MlBibTeX bibliography source) ‘MLBIBINPUTS’, ‘BIBINPUTS’,
1841 ‘TEXBIB’; suffixes ‘.mlbib’, ‘.mlbib’.
1842
1843 ‘mlbst’
1844 (MlBibTeX style) ‘MLBSTINPUTS’, ‘BSTINPUTS’; suffixes ‘.mlbst’,
1845 ‘.bst’.
1846
1847 ‘mp’
1848 (MetaPost source, *note (web2c)mpost invocation::) ‘MPINPUTS’;
1849 suffix ‘.mp’.
1850
1851 ‘mppool’
1852 (MetaPost program strings, *note (web2c)pooltype invocation::)
1853 ‘MPPOOL’, ‘TEXMFINI’; suffix ‘.pool’.
1854
1855 ‘ocp’
1856 (Omega compiled process files) ‘OCPINPUTS’;
1857 suffix ‘.ocp’; dynamic creation program: ‘MakeOmegaOCP’.
1858
1859 ‘ofm’
1860 (Omega font metrics) ‘OFMFONTS’, ‘TEXFONTS’;
1861 suffixes ‘.ofm’, ‘.tfm’; dynamic creation program: ‘MakeOmegaOFM’.
1862
1863 ‘opentype fonts’
1864 (OpenType fonts) ‘OPENTYPEFONTS’.
1865
1866 ‘opl’
1867 (Omega property lists) ‘OPLFONTS’, ‘TEXFONTS’; suffix ‘.opl’.
1868
1869 ‘otp’
1870 (Omega translation process files) ‘OTPINPUTS’; suffix ‘.otp’.
1871
1872 ‘ovf’
1873 (Omega virtual fonts) ‘OVFFONTS’, ‘TEXFONTS’; suffix ‘.ovf’.
1874
1875 ‘ovp’
1876 (Omega virtual property lists) ‘OVPFONTS’, ‘TEXFONTS’; suffix
1877 ‘.ovp’.
1878
1879 ‘pdftex config’
1880 (PDFTeX-specific configuration files) ‘PDFTEXCONFIG’.
1881
1882 ‘pk’
1883 (packed bitmap fonts, *note (dvips)Glyph files::) ‘PROGRAMFONTS’
1884 (PROGRAM being ‘XDVI’, etc.), ‘PKFONTS’, ‘TEXPKS’, ‘GLYPHFONTS’,
1885 ‘TEXFONTS’; suffix ‘pk’; dynamic creation program: ‘mktexpk’.
1886
1887 ‘PostScript header’
1888 (downloadable PostScript, *note (dvips)Header files::)
1889 ‘TEXPSHEADERS’, ‘PSHEADERS’; additional suffix ‘.pro’.
1890
1891 ‘ris’
1892 (RIS bibliography files, primarily for Biber,
1893 <https://ctan.org/pkg/biber>) ‘RISINPUTS’ suffix ‘.ris’.
1894
1895 ‘subfont definition files’
1896 (subfont definition files) ‘SFDFONTS’ suffix ‘.sfd’.
1897
1898 ‘tex’
1899 (TeX source, *note (web2c)tex invocation::) ‘TEXINPUTS’; suffix
1900 ‘.tex’; additional suffixes: none, because such a list cannot be
1901 complete; dynamic creation program: ‘mktextex’.
1902
1903 ‘TeX system documentation’
1904 (Documentation files for the TeX system) ‘TEXDOCS’.
1905
1906 ‘TeX system sources’
1907 (Source files for the TeX system) ‘TEXSOURCES’.
1908
1909 ‘texmfscripts’
1910 (Architecture-independent executables distributed in the texmf
1911 trees) ‘TEXMFSCRIPTS’.
1912
1913 ‘texpool’
1914 (TeX program strings, *note (web2c)pooltype invocation::)
1915 ‘TEXPOOL’, ‘TEXMFINI’; suffix ‘.pool’.
1916
1917 ‘tfm’
1918 (TeX font metrics, *note (dvips)Metric files::) ‘TFMFONTS’,
1919 ‘TEXFONTS’; suffix ‘.tfm’; dynamic creation program: ‘mktextfm’.
1920
1921 ‘Troff fonts’
1922 (Troff fonts, used by DMP; *note (web2c)DMP invocation::)
1923 ‘TRFONTS’.
1924
1925 ‘truetype fonts’
1926 (TrueType outline fonts) ‘TTFONTS’; suffixes ‘.ttf’ and ‘.TTF’,
1927 ‘.ttc’ and ‘.TTC’, ‘.dfont’.
1928
1929 ‘type1 fonts’
1930 (Type 1 PostScript outline fonts, *note (dvips)Glyph files::)
1931 ‘T1FONTS’, ‘T1INPUTS’, ‘TEXPSHEADERS’, ‘DVIPSHEADERS’; suffixes
1932 ‘.pfa’, ‘.pfb’.
1933
1934 ‘type42 fonts’
1935 (Type 42 PostScript outline fonts) ‘T42FONTS’.
1936
1937 ‘vf’
1938 (virtual fonts, *note (dvips)Virtual fonts::) ‘VFFONTS’,
1939 ‘TEXFONTS’; suffix ‘.vf’.
1940
1941 ‘web’
1942 (WEB input files) ‘WEBINPUTS’; suffix ‘.web’; additional suffix
1943 ‘.ch’.
1944
1945 ‘web2c files’
1946 (files specific to the web2c implementation) ‘WEB2C’.
1947
1948 There are two special cases, because the paths and environment
1949 variables always depend on the name of the program: the variable name is
1950 constructed by converting the program name to upper case, and then
1951 appending ‘INPUTS’. Assuming the program is called ‘foo’, this gives us
1952 the following table.
1953
1954 ‘other text files’
1955 (text files used by ‘foo’) ‘FOOINPUTS’.
1956
1957 ‘other binary files’
1958 (binary files used by ‘foo’) ‘FOOINPUTS’.
1959
1960 If an environment variable by these names are set, the corresponding
1961 ‘texmf.cnf’ definition won't be looked at (unless, as usual, the
1962 environment variable value has an extra ‘:’). *Note Default
1963 expansion::.
1964
1965 For the font variables, the intent is that:
1966 • ‘TEXFONTS’ is the default for everything.
1967
1968 • ‘GLYPHFONTS’ is the default for bitmap (or, more precisely,
1969 non-metric) files.
1970
1971 • Each font format has a variable of its own.
1972
1973 • Each program has its own font override path as well; e.g.,
1974 ‘DVIPSFONTS’ for Dvipsk. Again, this is for bitmaps, not metrics.
1975
1976 
1977 File: kpathsea.info, Node: File lookup, Next: Glyph lookup, Prev: Supported file formats, Up: TeX support
1978
1979 6.2 File lookup
1980 ===============
1981
1982 This section describes how Kpathsea searches for most files (bitmap font
1983 searches are the exception, as described in the next section).
1984
1985 Here is the search strategy for a file NAME:
1986
1987 1. If the file format defines default suffixes, and the suffix of NAME
1988 name is not already a known suffix for that format, try the name
1989 with each default appended, and use alternative names found in the
1990 fontmaps if necessary. Example: given ‘foo.bar’, look for
1991 ‘foo.bar.tex’.
1992
1993 2. Search for NAME, and if necessary for alternative names found in
1994 the fontmaps. Example: given ‘foo.bar’, we also look for
1995 ‘foo.bar’.
1996
1997 3. If the file format defines a program to invoke to create missing
1998 files, run it (*note mktex scripts::).
1999
2000 The order in which we search for "suffixed" name (item 1) or the
2001 "as-is" name (item 2) is controlled by the ‘try_std_extension_first’
2002 configuration value. The default set in ‘texmf.cnf’ is true, since
2003 common suffixes are already recognized: ‘babel.sty’ will only look for
2004 ‘babel.sty’, not ‘babel.sty.tex’, regardless of this setting.
2005
2006 When the suffix is unknown (e.g., ‘foo.bar’), both names are always
2007 tried; the difference is the order in which they are tried.
2008
2009 ‘try_std_extension_first’ only affects names being looked up which
2010 *already* have an extension. A name without an extension (e.g., ‘tex
2011 story’) will always have an extension added first.
2012
2013 This algorithm is implemented in the function ‘kpathsea_find_file’ in
2014 the source file ‘kpathsea/tex-file.c’. You can watch it in action with
2015 the debugging options (*note Debugging::).
2016
2017 
2018 File: kpathsea.info, Node: Glyph lookup, Next: Suppressing warnings, Prev: File lookup, Up: TeX support
2019
2020 6.3 Glyph lookup
2021 ================
2022
2023 This section describes how Kpathsea searches for a bitmap font in GF or
2024 PK format (or either) given a font name (e.g., ‘cmr10’) and a resolution
2025 (e.g., 600).
2026
2027 Here is an outline of the search strategy (details in the sections
2028 below) for a file NAME at resolution DPI. The search stops at the first
2029 successful lookup.
2030
2031 1. Look for an existing file NAME.DPIFORMAT in the specified
2032 format(s).
2033
2034 2. If NAME is an alias for a file F in the fontmap file
2035 ‘texfonts.map’, look for F.DPI.
2036
2037 3. Run an external program (typically named ‘mktexpk’) to generate the
2038 font (*note mktex scripts::)
2039
2040 4. Look for FALLBACK.DPI, where FALLBACK is some last-resort font
2041 (typically ‘cmr10’).
2042
2043 This is implemented in ‘kpathsea_find_glyph’ in
2044 ‘kpathsea/tex-glyph.c’.
2045
2046 * Menu:
2047
2048 * Basic glyph lookup:: Features common to all glyph lookups.
2049 * Fontmap:: Aliases for fonts.
2050 * Fallback font:: Resolutions and fonts of last resort.
2051
2052 
2053 File: kpathsea.info, Node: Basic glyph lookup, Next: Fontmap, Up: Glyph lookup
2054
2055 6.3.1 Basic glyph lookup
2056 ------------------------
2057
2058 When Kpathsea looks for a bitmap font NAME at resolution DPI in a format
2059 FORMAT, it first checks each directory in the search path for a file
2060 ‘NAME.DPIFORMAT’; for example, ‘cmr10.600pk’. Kpathsea looks for a PK
2061 file first, then a GF file.
2062
2063 If that fails, Kpathsea looks for ‘dpiDPI/NAME.FORMAT’; for example,
2064 ‘dpi600/cmr10.pk’. This is how fonts are typically stored on
2065 filesystems (such as DOS) that permit only three-character extensions.
2066
2067 If that fails, Kpathsea looks for a font with a close-enough DPI.
2068 "Close enough" is defined by the macro ‘KPSE_BITMAP_TOLERANCE’ in
2069 ‘kpathsea/tex-glyph.h’ to be ‘DPI / 500 + 1’. This is slightly more
2070 than the 0.2% minimum allowed by the DVI standard
2071 (<CTAN:/dviware/driv-standard/level-0>).
2072
2073 
2074 File: kpathsea.info, Node: Fontmap, Next: Fallback font, Prev: Basic glyph lookup, Up: Glyph lookup
2075
2076 6.3.2 Fontmap
2077 -------------
2078
2079 If a bitmap font or metric file is not found with the original name (see
2080 the previous section), Kpathsea looks through any “fontmap” files for an
2081 “alias” for the original font name. These files are named
2082 ‘texfonts.map’ and searched for along the ‘TEXFONTMAPS’
2083 environment/config file variable. All ‘texfonts.map’ files that are
2084 found are read; earlier definitions override later ones.
2085
2086 This feature is intended to help in two respects:
2087
2088 1. An alias name is limited in length only by available memory, not by
2089 your filesystem. Therefore, if you want to ask for ‘Times-Roman’
2090 instead of ‘ptmr’, you can (you get ‘ptmr8r’).
2091
2092 2. A few fonts have historically had multiple names: specifically,
2093 LaTeX's "circle font" has variously been known as ‘circle10’,
2094 ‘lcircle10’, and ‘lcirc10’. Aliases can make all the names
2095 equivalent, so that it no longer matters what the name of the
2096 installed file is; TeX documents will find their favorite name.
2097
2098 The format of fontmap files:
2099
2100 • Comments start with the last ‘%’ on a line and continue to the end
2101 of the line. (This provides for names that include a %,
2102 ill-advised as that may be.)
2103
2104 • Blank lines are ignored.
2105
2106 • Each nonblank line is broken up into a series of “words”: a
2107 sequence of non-whitespace characters.
2108
2109 • If the first word is ‘include’, the second word is used as a
2110 filename, and it is searched for and read.
2111
2112 • Otherwise, the first word on each line is the true filename;
2113
2114 • the second word is the alias;
2115
2116 • subsequent words are ignored.
2117
2118 If an alias has an extension, it matches only those files with that
2119 extension; otherwise, it matches anything with the same root, regardless
2120 of extension. For example, an alias ‘foo.tfm’ matches only when
2121 ‘foo.tfm’ is being searched for; but an alias ‘foo’ matches ‘foo.vf’,
2122 ‘foo.600pk’, etc.
2123
2124 As an example, here is an excerpt from the ‘texfonts.map’ in the
2125 Web2c distribution. It makes the old and new names of the LaTeX circle
2126 fonts equivalent.
2127
2128 circle10 lcircle10
2129 circle10 lcirc10
2130 lcircle10 circle10
2131 lcircle10 lcirc10
2132 lcirc10 circle10
2133 lcirc10 lcircle10
2134 ...
2135
2136 Fontmaps are implemented in the file ‘kpathsea/fontmap.c’. The
2137 Fontname distribution has much more information on font naming (*note
2138 (fontname)Top::).
2139
2140 
2141 File: kpathsea.info, Node: Fallback font, Prev: Fontmap, Up: Glyph lookup
2142
2143 6.3.3 Fallback font
2144 -------------------
2145
2146 If a bitmap font cannot be found or created at the requested size,
2147 Kpathsea looks for the font at a set of “fallback resolutions”. You
2148 specify these resolutions as a colon-separated list (like search paths).
2149 Kpathsea looks first for a program-specific environment variable (e.g.,
2150 ‘DVIPSSIZES’ for Dvipsk), then the environment variable ‘TEXSIZES’, then
2151 a default specified at compilation time (the Make variable
2152 ‘default_texsizes’). You can set this list to be empty if you prefer to
2153 find fonts at their stated size or not at all.
2154
2155 Finally, if the font cannot be found even at the fallback
2156 resolutions, Kpathsea looks for a fallback font, typically ‘cmr10’.
2157 Programs must enable this feature by calling ‘kpathsea_init_prog’ (*note
2158 Calling sequence::); the default is no fallback font.
2159
2160 
2161 File: kpathsea.info, Node: Suppressing warnings, Next: mktex scripts, Prev: Glyph lookup, Up: TeX support
2162
2163 6.4 Suppressing warnings
2164 ========================
2165
2166 Kpathsea provides a way to suppress selected usually-harmless warnings;
2167 this is useful at large sites where most users are not administrators,
2168 and thus the warnings are merely a source of confusion, not a help. To
2169 do this, you set the environment variable or configuration file value
2170 ‘TEX_HUSH’ to a colon-separated list of values. Here are the
2171 possibilities:
2172
2173 ‘all’
2174 Suppress everything possible.
2175
2176 ‘checksum’
2177 Suppress mismatched font checksum warnings.
2178
2179 ‘lostchar’
2180 Suppress warnings when a character is missing from a font that a
2181 DVI or VF file tries to typeset.
2182
2183 ‘none’
2184 Don't suppress any warnings.
2185
2186 ‘readable’
2187 Suppress warnings about attempts to access a file whose permissions
2188 render it unreadable.
2189
2190 ‘special’
2191 Suppresses warnings about an unimplemented or unparsable ‘\special’
2192 command.
2193
2194 ‘tex-hush.c’ defines the function that checks the variable value. Each
2195 driver implements its own checks where appropriate.
2196
2197 
2198 File: kpathsea.info, Node: mktex scripts, Prev: Suppressing warnings, Up: TeX support
2199
2200 6.5 ‘mktex’ scripts
2201 ===================
2202
2203 If Kpathsea cannot otherwise find a file, for some file types it is
2204 configured by default to invoke an external program to create it
2205 dynamically (*note mktex configuration::). These are collectively known
2206 as “‘mktex’ scripts”, since most of them are named ‘mktex...’.
2207
2208 For example, this is useful for fonts (bitmaps, TFM's, and
2209 arbitrarily-sizable Metafont sources such as the Sauter and EC fonts),
2210 since any given document can use fonts never before referenced.
2211 Building all fonts in advance is therefore impractical, if not
2212 impossible.
2213
2214 It is also useful for the TeX ‘.fmt’ (and Metafont ‘.base’ and
2215 Metapost ‘.mem’ files, *note (Web2c)Memory dumps::), where
2216 pre-generating every format consumes a lot of both time and space.
2217
2218 The script is passed the name of the file to create and possibly
2219 other arguments, as explained below. It must echo the full pathname of
2220 the file it created (and nothing else) to standard output; it can write
2221 diagnostics to standard error.
2222
2223 * Menu:
2224
2225 * config: mktex configuration.
2226 * names: mktex script names.
2227 * args: mktex script arguments.
2228
2229 
2230 File: kpathsea.info, Node: mktex configuration, Next: mktex script names, Up: mktex scripts
2231
2232 6.5.1 ‘mktex’ configuration
2233 ---------------------------
2234
2235 The list of file types and program names that can run an external
2236 program to create missing files is listed in the next section. In the
2237 absence of ‘configure’ options specifying otherwise, everything but
2238 ‘mktextex’ will be enabled by default. The ‘configure’ options to
2239 change the defaults are:
2240
2241 --without-mktexfmt-default
2242 --without-mktexmf-default
2243 --without-mktexocp-default
2244 --without-mktexofm-default
2245 --without-mktexpk-default
2246 --without-mktextfm-default
2247 --with-mktextex-default
2248
2249 The ‘configure’ setting is overridden if the environment variable or
2250 configuration file value named for the script is set; e.g., ‘MKTEXPK’
2251 (*note mktex script arguments::).
2252
2253 ‘mktexfmt’ reads a file ‘fmtutil.cnf’, typically located in
2254 ‘texmf/web2c/’ to glean its configuration information. The rest of the
2255 files and features in this section are primarily intended for the font
2256 generation scripts.
2257
2258 As distributed, all the scripts source a file ‘texmf/web2c/mktex.cnf’
2259 if it exists, so you can override various defaults. See ‘mktex.opt’,
2260 for instance, which defines the default mode, resolution, some special
2261 directory names, etc. If you prefer not to change the distributed
2262 scripts, you can simply create ‘mktex.cnf’ with the appropriate
2263 definitions (you do not need to create it if you have nothing to put in
2264 it). ‘mktex.cnf’ has no special syntax; it's an arbitrary Bourne shell
2265 script. The distribution contains a sample ‘mktex.cnf’ for you to copy
2266 and modify as you please (it is not installed anywhere).
2267
2268 In addition, you can configure a number of features with the
2269 ‘MT_FEATURES’ variable, which you can define:
2270
2271 • in ‘mktex.opt’, as just mentioned;
2272
2273 • by editing the file ‘mktex.opt’, either before ‘make install’ (in
2274 the source hierarchy) or after (in the installed hierarchy);
2275
2276 • or in the environment.
2277
2278 If none of the options below are enabled, ‘mktexpk’, ‘mktextfm’, and
2279 ‘mktexmf’ follow the following procedure to decide where fonts should be
2280 installed. Find the tree where the font's sources are, and test the
2281 permissions of the ‘fonts’ directory of that tree to determine whether
2282 it is writable. If it is, put the files in the tree in appropriate
2283 locations. If it isn't writable, see whether the tree is a system tree
2284 (named in ‘SYSTEXMF’). If so, the ‘VARTEXFONTS’ tree is used. In all
2285 other cases the working directory is used.
2286
2287 The ‘appendonlydir’ option is enabled by default.
2288
2289 ‘appendonlydir’
2290 Tell ‘mktexdir’ to create directories append-only, i.e., set their
2291 sticky bit (*note (coreutils)Mode Structure::). This feature is
2292 silently ignored on non-Unix platforms (e.g. Windows/NT and
2293 MS-DOS) which don't support similar functionality. This feature is
2294 enabled by default.
2295
2296 ‘dosnames’
2297 Use 8.3 names; e.g., ‘dpi600/cmr10.pk’ instead of ‘cmr10.600pk’.
2298 Note that this feature only affects filenames that would otherwise
2299 clash with other TeX-related filenames; ‘mktex’ scripts do nothing
2300 about filenames which exceed the 8+3 MS-DOS limits but remain
2301 unique when truncated (by the OS) to these limits, and nether do
2302 the scripts care about possible clashes with files which aren't
2303 related with TeX. For example, ‘cmr10.600pk’ would clash with
2304 ‘cmr10.600gf’ and is therefore changed when ‘dosnames’ is in
2305 effect, but ‘mf.pool’ and ‘mp.base’ don't clash with any
2306 TeX-related files and are therefore unchanged.
2307
2308 This feature is turned on by default on MS-DOS. If you do not wish
2309 ‘dosnames’ to be set on an MS-DOS platform, you need to set the
2310 ‘MT_FEATURES’ environment variable to a value that doesn't include
2311 ‘dosnames’. You can also change the default setting by editing
2312 ‘mktex.opt’, but only if you use the ‘mktex’ shell scripts; the
2313 emulation programs don't consult ‘mktex.opt’.
2314
2315 ‘fontmaps’
2316 Instead of deriving the location of a font in the destination tree
2317 from the location of the sources, the aliases and directory names
2318 from the Fontname distribution are used. (*note Introduction:
2319 (fontname)Top.).
2320
2321 ‘nomfdrivers’
2322 Let mktexpk and mktextfm create metafont driver files in a
2323 temporary directory. These will be used for just one metafont run
2324 and not installed permanently.
2325
2326 ‘nomode’
2327 Omit the directory level for the mode name; this is fine as long as
2328 you generate fonts for only one mode.
2329
2330 ‘stripsupplier’
2331 Omit the font supplier name directory level.
2332
2333 ‘striptypeface’
2334 Omit the font typeface name directory level.
2335
2336 ‘strip’
2337 Omit the font supplier and typeface name directory levels. This
2338 feature is deprecated in favour of ‘stripsupplier’ and
2339 ‘striptypeface’.
2340
2341 ‘varfonts’
2342 When this option is enabled, fonts that would otherwise be written
2343 in system texmf tree go to the ‘VARTEXFONTS’ tree instead. The
2344 default value in ‘kpathsea/Makefile.in’ is ‘/var/tmp/texfonts’.
2345 The ‘Linux File System Standard’ recommends ‘/var/tex/fonts’.
2346
2347 The ‘varfonts’ setting in ‘MT_FEATURES’ is overridden by the
2348 ‘USE_VARTEXFONTS’ environment variable: if set to ‘1’, the feature
2349 is enabled, and if set to ‘0’, the feature is disabled.
2350
2351 ‘texmfvar’
2352 Force generated files that would go into a system tree (as defined
2353 by ‘SYSTEXMF’) into ‘TEXMFVAR’. Starting with teTeX-3.0, the
2354 variable ‘TEXMFVAR’ is always set. The ‘varfonts’ feature takes
2355 precedence if also set.
2356
2357 The ‘texmfvar’ setting in ‘MT_FEATURES’ is overridden by the
2358 ‘USE_TEXMFVAR’ environment variable: if set to ‘1’, the feature is
2359 enabled, and if set to ‘0’, the feature is disabled.
2360
2361 
2362 File: kpathsea.info, Node: mktex script names, Next: mktex script arguments, Prev: mktex configuration, Up: mktex scripts
2363
2364 6.5.2 ‘mktex’ script names
2365 --------------------------
2366
2367 The following table shows the default name of the script for each of the
2368 file types which support runtime generation.
2369
2370 ‘mktexfmt’
2371 (‘.fmt’, ‘.base’, ‘.mem’) TeX/Metafont/MetaPost formats. This
2372 script is also named ‘fmtutil’, and reads ‘fmtutil.cnf’ for
2373 configuration information.
2374
2375 ‘mktexmf’
2376 (‘.mf’) Metafont input files.
2377
2378 ‘mkocp’
2379 (‘.ocp’) Omega compiled process files.
2380
2381 ‘mkofm’
2382 (‘.ofm’) Omega font metric files.
2383
2384 ‘mktexpk’
2385 (‘pk’) Glyph fonts.
2386
2387 ‘mktextex’
2388 (‘.tex’) TeX input files (disabled by default).
2389
2390 ‘mktextfm’
2391 (‘.tfm’) TFM files.
2392
2393 These names can be overridden by an environment variable specific to the
2394 program; for example, ‘DVIPSMAKEPK’ for Dvipsk.
2395
2396 If a ‘mktex...’ script fails, the invocation is appended to a file
2397 ‘missfont.log’ (by default) in the current directory. After fixing the
2398 problem, you can then execute the log file to create the missing files.
2399
2400 If the environment variable ‘TEXMF_OUTPUT_DIRECTORY’ is set,
2401 ‘missfont.log’ is first tried to be written there; if it's not set, the
2402 current directory is tried first. If that first write fails and the
2403 environment variable or configuration file value ‘TEXMFOUTPUT’ is set,
2404 we try to write ‘missfont.log’ there. Otherwise nothing is written.
2405
2406 The base filename ‘missfont.log’ is overridden by the ‘MISSFONT_LOG’
2407 environment variable or configuration file value.
2408
2409 
2410 File: kpathsea.info, Node: mktex script arguments, Prev: mktex script names, Up: mktex scripts
2411
2412 6.5.3 ‘mktex’ script arguments
2413 ------------------------------
2414
2415 The first argument to a ‘mktex’ script is always the name of the file to
2416 be created.
2417
2418 In the default ‘mktexpk’ implementation, additional arguments may
2419 also be passed:
2420
2421 ‘--dpi NUM’
2422 Sets the resolution of the generated font to NUM.
2423 ‘--mfmode NAME’
2424 Sets the Metafont mode to NAME.
2425 ‘--bdpi NUM’
2426 Sets the "base dpi" for the font. This must match the mode being
2427 used.
2428 ‘--mag STRING’
2429 A "magstep" string suitable for the Metafont ‘mag’ variable. This
2430 must match the combination of BDPI and DPI being used.
2431 ‘--destdir STRING’
2432 A directory name. If the directory is absolute, it is used as-is.
2433 Otherwise, it is appended to the root destination directory set in
2434 the script.
2435
2436 
2437 File: kpathsea.info, Node: Programming, Next: Reporting bugs, Prev: TeX support, Up: Top
2438
2439 7 Programming
2440 *************
2441
2442 This chapter is for programmers who wish to use Kpathsea. *Note
2443 Introduction::, for the conditions under which you may do so (in short,
2444 it is released under LGPLv2.1 or later).
2445
2446 * Menu:
2447
2448 * Overview: Programming overview. Introduction.
2449 * Calling sequence:: Specifics of what to call.
2450 * Safe filenames:: Only opening allowed files.
2451 * Program-specific files:: How to handle these.
2452 * Config: Programming with config files. Getting info from texmf.cnf.
2453
2454 
2455 File: kpathsea.info, Node: Programming overview, Next: Calling sequence, Up: Programming
2456
2457 7.1 Programming overview
2458 ========================
2459
2460 Aside from this manual, your best source of information is the source to
2461 the programs that use Kpathsea (*note Introduction::). First, Kpsewhich
2462 is a small utility program whose sole purpose is to exercise the main
2463 path-searching functionality. Of the drivers, Dviljk is probably the
2464 simplest full application program. Xdvik adds VF support and the
2465 complication of X resources. Dvipsk adds the complication of its own
2466 config files. Web2c is source code I also maintain, so it uses Kpathsea
2467 rather straightforwardly, but is of course complicated by the Web to C
2468 translation.
2469
2470 When looking at these program sources, you should know that previous
2471 versions of the library had a different programming interface; the
2472 current interface supports re-entrancy. Historically, the library
2473 function names were prefixed with ‘kpse_’ instead of ‘kpathsea_’, and
2474 they did not need an instance variable as first argument. This change
2475 was made in 2009. The old functions will never disappear, and can
2476 reliably continue to be used when they suffice, as they do for the
2477 programs above. The main application using the re-entrant API is the
2478 MetaPost library used by MetaPost and LuaTeX.
2479
2480 Beyond these examples, the ‘.h’ files in the Kpathsea source describe
2481 the interfaces and functionality (and of course the ‘.c’ files define
2482 the actual routines, which are the ultimate documentation).
2483 ‘pathsearch.h’ declares the basic searching routine. ‘tex-file.h’ and
2484 ‘tex-glyph.h’ define the interfaces for looking up particular kinds of
2485 files. In view of the way the headers depend on each other, it is
2486 recommended to use ‘#include <kpathsea/kpathsea.h>’, which includes
2487 every Kpathsea header.
2488
2489 If you want to include only specific headers, you should still
2490 consider including ‘kpathsea/config.h’ before including any other
2491 Kpathsea header, as it provides symbols used in the other headers;
2492 ‘kpathsea/config.h’ includes ‘kpathsea/c-auto.h’, which is generated by
2493 Autoconf.
2494
2495 The library provides no way for an external program to register new
2496 file types: ‘tex-file.[ch]’ must be modified to do this. For example,
2497 Kpathsea has support for looking up Dvips config files, even though no
2498 program other than Dvips is likely to ever want to do so. I felt this
2499 was acceptable, since along with new file types should also come new
2500 defaults in ‘texmf.cnf’ (and its descendant ‘paths.h’), since it's
2501 simplest for users if they can modify one configuration file for all
2502 kinds of paths.
2503
2504 Kpathsea does not parse any formats itself; it barely opens any
2505 files. Its primary purpose is to return filenames. The GNU font
2506 utilities package contains libraries to read TFM, GF, and PK files, as
2507 do the programs above, of course.
2508
2509 
2510 File: kpathsea.info, Node: Calling sequence, Next: Safe filenames, Prev: Programming overview, Up: Programming
2511
2512 7.2 Calling sequence
2513 ====================
2514
2515 The typical way to use Kpathsea in your program goes something like
2516 this:
2517
2518 1. Call ‘kpathsea_new’ to create a new library instance. This
2519 variable must be passed as the first argument to all the following
2520 library functions. The rest of this manual will be using ‘kpse’ as
2521 a placeholder for the name of this variable.
2522
2523 2. Call ‘kpathsea_set_program_name’ with ‘argv[0]’ as the second
2524 argument; the third argument is a string or ‘NULL’. The third
2525 argument is used by Kpathsea as the program name for the ‘.PROGRAM’
2526 feature of config files (*note Config files::). If the third
2527 argument is ‘NULL’, the value of the second argument is used. This
2528 function must be called before any other use of the Kpathsea
2529 library.
2530
2531 ‘kpathsea_set_program_name’ always sets the variables
2532 ‘kpse->invocation_name’ and ‘kpse->invocation_short_name’. These
2533 variables are used in the error message macros defined in
2534 ‘kpathsea/lib.h’. It sets the variable ‘kpse->program_name’ to the
2535 program name it uses.
2536
2537 It also initializes debugging options based on the environment
2538 variable ‘KPATHSEA_DEBUG’ (if that is set).
2539
2540 Finally, it sets the environment variables ‘SELFAUTOLOC’,
2541 ‘SELFAUTODIR’ and ‘SELFAUTOPARENT’ to the location, parent and
2542 grandparent directory of the executable, removing ‘.’ and ‘..’ path
2543 elements and resolving symbolic links. These are used in the
2544 default configuration file to allow people to invoke TeX from
2545 anywhere. You can use ‘kpsewhich --expand-var=\$SELFAUTOLOC’,
2546 etc., to see the values.
2547
2548 3. Set debugging options. *Note Debugging::. If your program doesn't
2549 have a debugging option already, you can define one and set
2550 ‘kpse->debug’ to the number that the user supplies (as in Dviljk
2551 and Web2c), or you can just omit this altogether (users can always
2552 set the ‘KPATHSEA_DEBUG’ environment variable). If you do have
2553 runtime debugging already, you need to merge Kpathsea's options
2554 with yours (as in Dvipsk and Xdvik).
2555
2556 4. If your program has its own configuration files that can define
2557 search paths, you should assign those paths to the ‘client_path’
2558 member in the appropriate element of the ‘kpse->format_info’ array.
2559 (This array is indexed by file type; see ‘tex-file.h’.) See
2560 ‘resident.c’ in Dvipsk for an example.
2561
2562 5. Call ‘kpathsea_init_prog’ (see ‘proginit.c’). It's useful for the
2563 DVI drivers, at least, but for other programs it may be simpler to
2564 extract the parts of it that actually apply. This does not
2565 initialize any paths, it just looks for (and sets) certain
2566 environment variables and other random information. Search paths
2567 are always initialized at the first call to find a file of a given
2568 type, not requiring an explicit initialization call; this
2569 eliminates much useless work, e.g., initializing the BibTeX search
2570 paths in a DVI driver.
2571
2572 6. The routine to actually find a file of type FORMAT is
2573 ‘kpathsea_find_file’. You can call ‘kpathsea_find_file’ after
2574 doing only the first and second of the initialization steps
2575 above--Kpathsea automatically reads the ‘texmf.cnf’ generic config
2576 files, looks for environment variables, and does expansions at the
2577 first lookup.
2578
2579 7. To find PK and/or GF bitmap fonts, the routine is
2580 ‘kpathsea_find_glyph’, defined in ‘tex-glyph.h’. This returns a
2581 structure in addition to the resultant filename, because fonts can
2582 be found in so many ways. See the documentation in the source.
2583
2584 8. Before opening a file, especially for writing, you should check if
2585 the filename is acceptable. See the next section (*note Safe
2586 filenames::).
2587
2588 9. To actually open a file, not just return a filename, call
2589 ‘kpathsea_open_file’. This function takes the name to look up and
2590 a Kpathsea file format as arguments, and returns the usual ‘FILE
2591 *’. It always assumes the file must exist, and thus will search
2592 the disk if necessary (unless the search path specified ‘!!’,
2593 etc.). In other words, if you are looking up a VF or some other
2594 file that need not exist, don't use this.
2595
2596 10. To close the Kpathsea library instance you are using, call
2597 ‘kpathsea_finish’. This function closes any open log files and
2598 frees the memory used by the instance.
2599
2600 Kpathsea also provides many utility routines. Some are generic: hash
2601 tables, memory allocation, string concatenation and copying, string
2602 lists, reading input lines of arbitrary length, etc. Others are
2603 filename-related: default path, tilde, and variable expansion, ‘stat’
2604 calls, etc.
2605
2606 The ‘c-*.h’ header files can also help your program adapt to many
2607 different systems. You will almost certainly want to use Autoconf and
2608 probably Automake for configuring and building your software if you use
2609 Kpathsea; I strongly recommend using Autoconf and Automake regardless.
2610 They are available from <https://gnu.org/software>.
2611
2612 
2613 File: kpathsea.info, Node: Safe filenames, Next: Program-specific files, Prev: Calling sequence, Up: Programming
2614
2615 7.3 Safe filenames
2616 ==================
2617
2618 *Note Security::, for some general security considerations with the TeX
2619 system.
2620
2621 In the implementation, the main security feature to disallow writing
2622 to potentially dangerous files is a configuration variable
2623 ‘openout_any’. It specifies one of three levels:
2624
2625 • When set to ‘a’ (for "any"), no restrictions are imposed.
2626
2627 • When is set to ‘r’ (for "restricted"), filenames beginning with ‘.’
2628 are disallowed.
2629
2630 • When set to ‘p’ (for "paranoid"), additional restrictions are
2631 imposed.
2632
2633 1. First, an absolute filename must refer to a file in (or in a
2634 subdirectory of) either the ‘TEXMF_OUTPUT_DIRECTORY’
2635 environment variable or the ‘TEXMFOUTPUT’ environment variable
2636 or configuration file setting.
2637
2638 2. LuaTeX uses a so-called "extended" mode, in which the values
2639 of ‘TEXMFVAR’ and ‘TEXMFSYSVAR’ are also checked for absolute
2640 filenames. This is done because, in practice, fundamental
2641 parts of the LuaLaTeX system (notably ‘luaotfload’) need a
2642 cache directory, and historically the ‘TEXMF[SYS]VAR’
2643 variables are what has been used. We neither recommend nor
2644 expect any other programs to need this.
2645
2646 3. Finally, any attempt to go up a directory level is forbidden;
2647 that is, paths may not contain a ‘..’ component.
2648
2649 The paranoid setting is the default. Any program intended to be
2650 safely called from TeX should implement the same measures, one way or
2651 another. *Note (web2c)Shell escapes::.
2652
2653 Kpathsea does not resolve ‘..’ components, or symbolic links, to see
2654 if the final result is an acceptable directory; they are simply
2655 forbidden. That is, Kpathsea merely considers the value as a string,
2656 not looking on the filesystem at all. (However, if another program
2657 wants to do such resolutions and check the result, that's ok; possibly
2658 preferable.)
2659
2660 For backwards compatibility, ‘y’ and ‘1’ are synonyms of ‘a’, while
2661 ‘n’ and ‘0’ are synonyms for ‘r’.
2662
2663 The function ‘kpathsea_out_name_ok’, with a filename as second
2664 argument, returns ‘true’ if that filename is acceptable to be opened for
2665 output or ‘false’ otherwise. The Kpsewhich program has an option
2666 (‘--safe-out-name’) providing a command line interface for the check.
2667
2668 For LuaTeX's extended mode, the function is
2669 ‘kpathsea_out_name_ok_extended’, and the Kpsewhich option is
2670 ‘--safe-extended-out-name’.
2671
2672 Although the analogous functions ‘kpathsea_in_name_ok’ (resp.
2673 ‘_extended’, as well as the others below, exist to check a filename
2674 being acceptable for reading, as of 2026, they always return true
2675 without checking anything. This is because no other value was useful
2676 (or used) in practice. More comments about this are in the default
2677 ‘texmf.cnf’, at ‘openin_any’ (which variable is defined, but is now
2678 ignored).
2679
2680 The functions above write a message to standard error if the usage is
2681 forbidden (so every caller does not have to do so). Each function has a
2682 ‘_silent’ counterpart which does not write the message; this is what
2683 Kpsewhich calls, since messages would be counterproductive in that case.
2684 Thus:
2685
2686 kpathsea_out_name_ok_silent
2687 kpathsea_out_name_ok_silent_extended
2688 kpathsea_in_name_ok_silent
2689 kpathsea_in_name_ok_silent_extended
2690
2691 Furthermore, there are ‘kpse_...’ versions of all the above functions
2692 (as usual), with the default library instance implicitly passed as the
2693 first argument. LuaTeX provides both ‘kpse.*’ and ‘kpathsea.*’
2694 bindings, so it's good to always have both.
2695
2696 Sorry for the combinatorial explosion, but we hope no further options
2697 will ever be needed. If so, we'll likely provide a more generic
2698 interface as well as the above.
2699
2700 
2701 File: kpathsea.info, Node: Program-specific files, Next: Programming with config files, Prev: Safe filenames, Up: Programming
2702
2703 7.4 Program-specific files
2704 ==========================
2705
2706 Many programs will need to find some configuration files. Kpathsea
2707 contains some support to make it easy to place them in their own
2708 directories. The Standard TeX directory structure (*note Introduction:
2709 (tds)Top.), specifies that such files should go into a subdirectory
2710 named after the program, like ‘texmf/ttf2pk’.
2711
2712 Two formats, ‘kpse_program_text_format’ and
2713 ‘kpse_program_binary_format’, use ‘.:$TEXMF/PROGRAM//’ as their
2714 compiled-in search path. To override this default, you can use the
2715 variable ‘PROGRAMINPUTS’ in the environment and/or ‘texmf.cnf’. That is
2716 to say, the name of the variable is constructed by converting the name
2717 of the program to upper case, and appending ‘INPUTS’.
2718
2719 The only difference between these two formats is whether
2720 ‘kpathsea_open_file’ will open the files it finds in text or binary
2721 mode.
2722
2723 
2724 File: kpathsea.info, Node: Programming with config files, Prev: Program-specific files, Up: Programming
2725
2726 7.5 Programming with config files
2727 =================================
2728
2729 You can (and probably should) use the same ‘texmf.cnf’ configuration
2730 file that Kpathsea uses for your program. This helps installers by
2731 keeping all configuration in one place.
2732
2733 To retrieve a value for a configuration variable VAR, the best way is
2734 to call ‘kpathsea_var_value’ on the string ‘VAR’. This will look first
2735 for an environment variable VAR, then a config file value. The result
2736 will be the value found or ‘NULL’. This function is declared in
2737 ‘kpathsea/variable.h’. For an example, see the ‘shell_escape’ code in
2738 ‘web2c/lib/texmfmp.c’.
2739
2740 The routine to do full variable and tilde expansion of an arbitrary
2741 string in the context of a search path (as opposed to simply retrieving
2742 a value) is ‘kpathsea_var_expand’, also declared in
2743 ‘kpathsea/variable.h’. However, it's generally only necessary to set
2744 the search path structure components as explained in the previous
2745 section instead of using this directly. Because of its usage with any
2746 input string, undefined ‘$FOO’ constructs in the argument to
2747 ‘kpathsea_var_expand’ are returned literally (‘"$FOO"’), while undefined
2748 ‘${FOO}’ constructs are expanded to the empty string.
2749
2750 If for some reason you want to retrieve a value _only_ from a config
2751 file, not automatically looking for a corresponding environment
2752 variable, call ‘kpathsea_cnf_get’ (declared in ‘kpathsea/cnf.h’) with
2753 the string VAR.
2754
2755 No initialization calls are needed.
2756
2757 
2758 File: kpathsea.info, Node: Reporting bugs, Next: Index, Prev: Programming, Up: Top
2759
2760 8 Reporting bugs
2761 ****************
2762
2763 If you have problems or suggestions, please report them to
2764 <[email protected]> using the bug checklist below.
2765
2766 Please report bugs in the documentation; not only factual errors or
2767 inconsistent behavior, but unclear or incomplete explanations, typos,
2768 wrong fonts, ...
2769
2770 * Menu:
2771
2772 * Bug checklist:: What to include in a good bug report.
2773 * Mailing lists:: Joining the bugs or announcements mailing lists.
2774 * Debugging:: Analyzing runtime problems.
2775 * Logging:: Recording searches.
2776 * Common problems:: When things go wrong.
2777
2778 
2779 File: kpathsea.info, Node: Bug checklist, Next: Mailing lists, Up: Reporting bugs
2780
2781 8.1 Bug checklist
2782 =================
2783
2784 Before reporting a bug, please check below to be sure it isn't already
2785 known (*note Common problems::).
2786
2787 Bug reports should be sent via electronic mail to <[email protected]>.
2788
2789 The general principle is that a good bug report includes all the
2790 information necessary for reproduction. Therefore, to enable
2791 investigation, your report should include the following:
2792
2793 • The version number(s) of the program(s) involved, and of Kpathsea
2794 itself. You can get the former by giving a sole option ‘--version’
2795 to the program, and the latter by running ‘kpsewhich --version’.
2796 The ‘NEWS’ and ‘ChangeLog’ files also contain the version number.
2797
2798 • The hardware, operating system (including version), compiler, and
2799 ‘make’ program you are using (the output of ‘uname -a’ is a start
2800 on the first two, though incomplete).
2801
2802 • Any options you gave to ‘configure’. This is recorded in the
2803 ‘config.status’ files.
2804
2805 If you are reporting a bug in ‘configure’ itself, it's probably
2806 system-dependent, and it will be unlikely the maintainers can do
2807 anything useful if you merely report that thus-and-such is broken.
2808 Therefore, you need to do some additional work: for some bugs, you
2809 can look in the file ‘config.log’ where the test that failed should
2810 appear, along with the compiler invocation and source program in
2811 question. You can then compile it yourself by hand, and discover
2812 why the test failed. Other ‘configure’ bugs do not involve the
2813 compiler; in that case, the only recourse is to inspect the
2814 ‘configure’ shell script itself, or the Autoconf macros that
2815 generated ‘configure’.
2816
2817 • The log of all debugging output, if the bug is in path searching.
2818 You can get this by setting the environment variable
2819 ‘KPATHSEA_DEBUG’ to ‘-1’ before running the program. Please look
2820 at the log yourself to make sure the behavior is really a bug
2821 before reporting it; perhaps "old" environment variable settings
2822 are causing files not to be found, for example.
2823
2824 • The contents of any input files necessary to reproduce the bug.
2825 For bugs in DVI-reading programs, for example, this generally means
2826 a DVI file (and any EPS or other files it uses)--TeX source files
2827 are helpful, but the DVI file is required, because that's the
2828 actual program input.
2829
2830 • If you are sending a patch (do so if you can!), please do so in the
2831 form of a context diff (‘diff -c’) against the original
2832 distribution source. Any other form of diff is either not as
2833 complete or harder for me to understand. Please also include a
2834 ‘ChangeLog’ entry.
2835
2836 • If the bug involved is an actual crash (i.e., core dump), it is
2837 easy and useful to include a stack trace from a debugger (I
2838 recommend the GNU debugger GDB (<https://gnu.org/software/gdb>).
2839 If the cause is apparent (a ‘NULL’ value being dereferenced, for
2840 example), please send the details along. If the program involved
2841 is TeX or Metafont, and the crash is happening at apparently-sound
2842 code, however, the bug may well be in the compiler, rather than in
2843 the program or the library (*note TeX or Metafont failing: TeX or
2844 Metafont failing.).
2845
2846 • Any additional information that will be helpful in reproducing,
2847 diagnosing, or fixing the bug.
2848
2849 
2850 File: kpathsea.info, Node: Mailing lists, Next: Debugging, Prev: Bug checklist, Up: Reporting bugs
2851
2852 8.2 Mailing lists
2853 =================
2854
2855 Web2c and Kpathsea in general are discussed on the mailing list
2856 <[email protected]>. You can subscribe and peruse the archives on the web
2857 <https://lists.tug.org/tex-k>.
2858
2859 You do not need to join to submit a report, nor will it affect
2860 whether you get a response. Be aware that large data files are
2861 sometimes included in bug reports. If this is a problem for you, do not
2862 join the list.
2863
2864 If you are looking for general TeX help, such as how to install a
2865 full TeX system or how to use LaTeX, please see
2866 <https://tug.org/begin.html>.
2867
2868 
2869 File: kpathsea.info, Node: Debugging, Next: Logging, Prev: Mailing lists, Up: Reporting bugs
2870
2871 8.3 Debugging
2872 =============
2873
2874 Kpathsea provides a number of runtime debugging options, detailed below
2875 by their names and corresponding numeric values. When the files you
2876 expect aren't being found, the thing to do is enable these options and
2877 examine the output.
2878
2879 You can set these with some runtime argument (e.g., ‘-d’) to the
2880 program; in that case, you should use the numeric values described in
2881 the program's documentation (which, for Dvipsk and Xdvik, are different
2882 than those below). It's best to give the ‘-d’ (or whatever) option
2883 first, for maximal output. Dvipsk and Xdvik have additional
2884 program-specific debugging options as well.
2885
2886 You can also set the environment variable ‘KPATHSEA_DEBUG’; in this
2887 case, you should use the numbers below. If you run the program under a
2888 debugger and set the instance variable ‘kpse->debug’, also use the
2889 numbers below.
2890
2891 In any case, by far the simplest value to use is ‘-1’, which will
2892 turn on all debugging output. This is usually better than guessing
2893 which particular values will yield the output you need.
2894
2895 Debugging output always goes to standard error, so you can redirect
2896 it easily. For example, in Bourne-compatible shells:
2897 dvips -d -1 ... 2>/tmp/debug
2898
2899 It is sometimes helpful to run the standalone Kpsewhich utility
2900 (*note Invoking kpsewhich::), instead of the original program.
2901
2902 In any case, you cannot use the names below; you must always use
2903 somebody's numbers. (Sorry.) To set more than one option, just sum the
2904 corresponding numbers.
2905
2906 ‘KPSE_DEBUG_STAT (1)’
2907 Report ‘stat’(2) calls. This is useful for verifying that your
2908 directory structure is not forcing Kpathsea to do many additional
2909 file tests (*note Slow path searching::, and *note Subdirectory
2910 expansion::). If you are using an up-to-date ‘ls-R’ database
2911 (*note Filename database::), this should produce no output unless a
2912 nonexistent file that must exist is searched for.
2913
2914 ‘KPSE_DEBUG_HASH (2)’
2915 Report lookups in all hash tables: ‘ls-R’ and ‘aliases’ (*note
2916 Filename database::); font aliases (*note Fontmap::); and config
2917 file values (*note Config files::). Useful when expected values
2918 are not being found, e.g.., file searches are looking at the disk
2919 instead of using ‘ls-R’.
2920
2921 ‘KPSE_DEBUG_FOPEN (4)’
2922 Report file openings and closings. Especially useful when your
2923 system's file table is full, for seeing which files have been
2924 opened but never closed. In case you want to set breakpoints in a
2925 debugger: this works by redefining ‘fopen’ (‘fclose’) to be
2926 ‘kpse_fopen_trace’ (‘kpse_fclose_trace’).
2927
2928 ‘KPSE_DEBUG_PATHS (8)’
2929 Report general path information for each file type Kpathsea is
2930 asked to search. This is useful when you are trying to track down
2931 how a particular path got defined--from ‘texmf.cnf’, ‘config.ps’,
2932 an environment variable, the compile-time default, etc. This is
2933 the contents of the ‘kpse_format_info_type’ structure defined in
2934 ‘tex-file.h’.
2935
2936 ‘KPSE_DEBUG_EXPAND (16)’
2937 Report the directory list corresponding to each path element
2938 Kpathsea searches. This is only relevant when Kpathsea searches
2939 the disk, since ‘ls-R’ searches don't look through directory lists
2940 in this way.
2941
2942 ‘KPSE_DEBUG_SEARCH (32)’
2943 Report on each file search: the name of the file searched for, the
2944 path searched in, whether or not the file must exist (when drivers
2945 search for ‘cmr10.vf’, it need not exist), and whether or not we
2946 are collecting all occurrences of the file in the path (as with,
2947 e.g., ‘texmf.cnf’ and ‘texfonts.map’), or just the first (as with
2948 most lookups). This can help you correlate what Kpathsea is doing
2949 with what is in your input file.
2950
2951 ‘KPSE_DEBUG_VARS (64)’
2952 Report the value of each variable Kpathsea looks up. This is
2953 useful for verifying that variables do indeed obtain their correct
2954 values.
2955
2956 ‘GSFTOPK_DEBUG (128)’
2957 Activates debugging printout specific to ‘gsftopk’ program.
2958
2959 ‘MAKETEX_DEBUG (512)’
2960 If you use the optional ‘mktex’ programs instead of the traditional
2961 shell scripts, this will report the name of the site file
2962 (‘mktex.cnf’ by default) which is read, directories created by
2963 ‘mktexdir’, the full path of the ‘ls-R’ database built by
2964 ‘mktexlsr’, font map searches, ‘MT_FEATURES’ in effect, parameters
2965 from ‘mktexnam’, filenames added by ‘mktexupd’, and some subsidiary
2966 commands run by the programs.
2967
2968 ‘MAKETEX_FINE_DEBUG (1024)’
2969 When the optional ‘mktex’ programs are used, this will print
2970 additional debugging info from functions internal to these
2971 programs.
2972
2973 Debugging output from Kpathsea is always written to standard error,
2974 and begins with the string ‘kdebug:’. (Except for hash table buckets,
2975 which just start with the number, but you can only get that output
2976 running under a debugger. See comments at the ‘hash_summary_only’
2977 variable in ‘kpathsea/db.c’.)
2978
2979 
2980 File: kpathsea.info, Node: Logging, Next: Common problems, Prev: Debugging, Up: Reporting bugs
2981
2982 8.4 Logging
2983 ===========
2984
2985 Kpathsea can record the time and filename found for each successful
2986 search. This may be useful in finding good candidates for deletion when
2987 your filesystem is full, or in discovering usage patterns at your site.
2988
2989 To do this, define the environment or config file variable
2990 ‘TEXMFLOG’. The value is the name of the file to append the information
2991 to. The file is created if it doesn't exist, and appended to if it
2992 does.
2993
2994 Each successful search turns into one line in the log file: two words
2995 separated by a space. The first word is the time of the search, as the
2996 integer number of seconds since "the epoch", i.e., UTC midnight 1
2997 January 1970 (more precisely, the result of the ‘time’ system call).
2998 The second word is the filename.
2999
3000 For example, after ‘setenv TEXMFLOG /tmp/log’, running Dvips on
3001 ‘story.dvi’ appends the following lines:
3002
3003 774455887 /usr/local/share/texmf/dvips/config.ps
3004 774455887 /usr/local/share/texmf/dvips/psfonts.map
3005 774455888 /usr/local/share/texmf/dvips/texc.pro
3006 774455888 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmbx10.600pk
3007 774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmsl10.600pk
3008 774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk
3009 774455889 /usr/local/share/texmf/dvips/texc.pro
3010
3011 Only filenames that are absolute are recorded, to preserve some
3012 semblance of privacy.
3013
3014 In addition to this Kpathsea-specific logging, ‘pdftex’ provides an
3015 option ‘-recorder’ to write the names of all files accessed during a run
3016 to the file ‘BASEFILE.fls’.
3017
3018 Finally, most systems provide a general tool to output each system
3019 call, thus including opening and closing files. It might be named
3020 ‘strace’, ‘truss’, ‘struss’, or something else.
3021
3022 
3023 File: kpathsea.info, Node: Common problems, Prev: Logging, Up: Reporting bugs
3024
3025 8.5 Common problems
3026 ===================
3027
3028 Here are some common problems with configuration, compilation, linking,
3029 execution, ...
3030
3031 * Menu:
3032
3033 * Unable to find files:: If your program can't find fonts (or whatever).
3034 * Slow path searching:: If it takes forever to find anything.
3035 * Unable to generate fonts:: If mktexpk fails.
3036 * TeX or Metafont failing:: Likely compiler bugs.
3037
3038 
3039 File: kpathsea.info, Node: Unable to find files, Next: Slow path searching, Up: Common problems
3040
3041 8.5.1 Unable to find files
3042 --------------------------
3043
3044 If a program complains it cannot find fonts (or other input files), any
3045 of several things might be wrong. In any case, you may find the
3046 debugging options helpful. *Note Debugging::.
3047
3048 • Perhaps you simply haven't installed all the necessary files; the
3049 basic fonts and input files are distributed separately from the
3050 programs. *Note unixtex.ftp::.
3051
3052 • You have (perhaps unknowingly) told Kpathsea to use search paths
3053 that don't reflect where the files actually are. One common cause
3054 is having environment variables set from a previous installation,
3055 thus overriding what you carefully set in ‘texmf.cnf’ (*note
3056 Supported file formats::). System ‘/etc/profile’ or other files
3057 such may be the culprit.
3058
3059 • Your files reside in a directory that is only pointed to via a
3060 symbolic link within a leaf directory, and is not listed in ‘ls-R’.
3061
3062 Unfortunately, Kpathsea's subdirectory searching has a problematic
3063 deficiency: If a directory D being searched for subdirectories
3064 contains symbolic links to other directories (and possibly other
3065 plain files or symlinks), but no true subdirectories, by default D
3066 will be considered a leaf directory, i.e., the symbolic links will
3067 not be followed. *Note Subdirectory expansion::.
3068
3069 You can work around this problem by creating an empty dummy
3070 subdirectory in D. Then D will no longer be a leaf, and the
3071 symlinks will be followed.
3072
3073 Another workaround is to set the configuration variable
3074 ‘kpse_ignore_nlink_for_leaf’ to 1. Then Kpathsea will look at all
3075 entries in all directories in determining whether they are
3076 (symlinks to) subdirectories. This is not the default because it
3077 is considerably expensive to consider the contents of every leaf
3078 directory.
3079
3080 The directory immediately followed by the ‘//’ in the path
3081 specification is always searched for subdirectories, even if it is
3082 a leaf. Presumably you would not have asked for the directory to
3083 be searched for subdirectories if you didn't want it to be.
3084
3085 • If the fonts (or whatever) don't already exist, ‘mktexpk’ (or
3086 ‘mktexmf’ or ‘mktextfm’) will try to create them. If these rather
3087 complicated shell scripts fail, you'll eventually get an error
3088 message saying something like ‘Can't find font FONTNAME’. The best
3089 solution is to fix (or at least report) the bug in ‘mktexpk’; the
3090 workaround is to generate the necessary fonts by hand with
3091 Metafont, or to grab them from a CTAN site (*note unixtex.ftp::).
3092
3093 • There is a bug in the library. *Note Reporting bugs::.
3094
3095 
3096 File: kpathsea.info, Node: Slow path searching, Next: Unable to generate fonts, Prev: Unable to find files, Up: Common problems
3097
3098 8.5.2 Slow path searching
3099 -------------------------
3100
3101 If your program takes an excessively long time to find fonts or other
3102 input files, but does eventually succeed, here are some possible
3103 culprits:
3104
3105 • Most likely, you just have a lot of directories to search, and that
3106 takes a noticeable time. The solution is to create and maintain a
3107 separate ‘ls-R’ file that lists all the files in your main TeX
3108 hierarchy. *Note Filename database::. Kpathsea always uses ‘ls-R’
3109 if it's present; there's no need to recompile or reconfigure any of
3110 the programs.
3111
3112 • Your recursively-searched directories (e.g.,
3113 ‘/usr/local/share/texmf/fonts//’), contain a mixture of files and
3114 directories. This prevents Kpathsea from using a useful
3115 optimization (*note Subdirectory expansion::).
3116
3117 It is best to have only directories (and perhaps a ‘README’) in the
3118 upper levels of the directory structure, and it's very important to
3119 have _only_ files, and no subdirectories, in the leaf directories
3120 where the dozens of TFM, PK, or whatever files reside.
3121
3122 In any case, you may find the debugging options helpful in
3123 determining precisely when the disk or network is being pounded. *Note
3124 Debugging::.
3125
3126 
3127 File: kpathsea.info, Node: Unable to generate fonts, Next: TeX or Metafont failing, Prev: Slow path searching, Up: Common problems
3128
3129 8.5.3 Unable to generate fonts
3130 ------------------------------
3131
3132 Metafont outputs fonts in bitmap format, tuned for a particular device
3133 at a particular resolution, in order to allow for the highest-possible
3134 quality of output. Some DVI-to-whatever programs, such as Dvips, try to
3135 generate these on the fly when they are needed, but this generation may
3136 fail in several cases.
3137
3138 If ‘mktexpk’ runs, but fails with this error:
3139 mktexpk: Can't guess mode for NNN dpi devices.
3140 mktexpk: Use a config file to specify the mode, or update me.
3141 you need to ensure the resolution and mode match; just specifying the
3142 resolution, as in ‘-D 360’, is not enough.
3143
3144 You can specify the mode name with the ‘-mode’ option on the Dvips
3145 command line, or in a Dvips configuration file (*note (dvips)Config
3146 files::), such as ‘config.ps’ in your document directory, ‘~/.dvipsrc’
3147 in your home directory, or in a system directory (again named
3148 ‘config.ps’). (Other drivers use other files, naturally.)
3149
3150 For example, if you need 360dpi fonts, you could include this in a
3151 configuration file:
3152 D 360
3153 M lqmed
3154
3155 If Metafont runs, but generates fonts at the wrong resolution or for
3156 the wrong device, most likely ‘mktexpk’'s built-in guess for the mode is
3157 wrong, and you should override it as above.
3158
3159 See <https://ctan.org/pkg/modes> for a list of resolutions and mode
3160 names for most devices (additional submissions are welcome).
3161
3162 If Metafont runs but generates fonts at a resolution of 2602dpi (and
3163 prints out the name of each character as well as just a character
3164 number, and maybe tries to display the characters), then your Metafont
3165 base file probably hasn't been made properly. (It's using the default
3166 ‘proof’ mode, instead of an actual device mode.) To make a proper
3167 ‘plain.base’, assuming the local mode definitions are contained in a
3168 file ‘modes.mf’, run the following command (assuming Unix):
3169
3170 inimf "plain; input modes; dump"
3171
3172 Then copy the ‘plain.base’ file from the current directory to where the
3173 base files are stored on your system (‘/usr/local/share/texmf/web2c’ by
3174 default), and make a link (either hard or soft) from ‘plain.base’ to
3175 ‘mf.base’ in that directory. *Note (web2c)inimf invocation::.
3176
3177 If ‘mf’ is a command not found at all by ‘mktexpk’, then you need to
3178 install Metafont (*note unixtex.ftp::).
3179
3180 
3181 File: kpathsea.info, Node: TeX or Metafont failing, Prev: Unable to generate fonts, Up: Common problems
3182
3183 8.5.4 TeX or Metafont failing
3184 -----------------------------
3185
3186 If TeX or Metafont get a segmentation fault or otherwise fail while
3187 running a normal input file, the problem is usually a compiler bug
3188 (unlikely as that may sound). Even if the trip and trap tests are
3189 passed, problems may lurk. Optimization occasionally causes trouble in
3190 programs other than TeX and Metafont themselves, too.
3191
3192 For a workaround, if you enabled any optimization flags, it's best to
3193 omit optimization entirely. In any case, the way to find the facts is
3194 to run the program under the debugger and see where it's failing.
3195
3196 Also, if you have trouble with a system C compiler, I advise trying
3197 the GNU C compiler. And vice versa, unfortunately; but in that case I
3198 also recommend reporting a bug to the GCC mailing list; see *note
3199 (gcc)Bugs::.
3200
3201 To report compiler bugs effectively requires perseverance and
3202 perspicacity: you must find the miscompiled line, and that usually
3203 involves delving backwards in time from the point of error, checking
3204 through TeX's (or whatever program's) data structures. Good luck.
3205
3206 
3207 File: kpathsea.info, Node: Index, Prev: Reporting bugs, Up: Top
3208
3209 Index
3210 *****
3211
3212 [index]
3213 * Menu:
3214
3215 * --all: Path searching options.
3216 (line 10)
3217 * --casefold-search: Path searching options.
3218 (line 22)
3219 * --cnf-line: Path searching options.
3220 (line 31)
3221 * --cnf-line, source for path: Path sources. (line 9)
3222 * --color=tty: ls-R. (line 25)
3223 * --debug=NUM: Auxiliary tasks. (line 9)
3224 * --dpi=NUM: Path searching options.
3225 (line 52)
3226 * --engine=NAME: Path searching options.
3227 (line 56)
3228 * --expand-braces=STRING: Auxiliary tasks. (line 12)
3229 * --expand-path=STRING: Auxiliary tasks. (line 16)
3230 * --expand-var=STRING: Auxiliary tasks. (line 34)
3231 * --format=NAME: Path searching options.
3232 (line 73)
3233 * --help: Standard options. (line 8)
3234 * --help-formats: Auxiliary tasks. (line 42)
3235 * --interactive: Path searching options.
3236 (line 155)
3237 * --mktex=FILETYPE: Path searching options.
3238 (line 160)
3239 * --mode=STRING: Path searching options.
3240 (line 166)
3241 * --must-exist: Path searching options.
3242 (line 171)
3243 * --no-casefold-search: Path searching options.
3244 (line 22)
3245 * --no-mktex=FILETYPE: Path searching options.
3246 (line 160)
3247 * --path=STRING: Path searching options.
3248 (line 176)
3249 * --progname=NAME: Path searching options.
3250 (line 184)
3251 * --safe-extended-in-name=NAME: Auxiliary tasks. (line 48)
3252 * --safe-extended-out-name=NAME: Auxiliary tasks. (line 48)
3253 * --safe-in-name=NAME: Auxiliary tasks. (line 54)
3254 * --safe-out-name=NAME: Auxiliary tasks. (line 54)
3255 * --show-path=NAME: Auxiliary tasks. (line 60)
3256 * --subdir=STRING: Path searching options.
3257 (line 189)
3258 * --var-brace-value=VARIABLE: Auxiliary tasks. (line 66)
3259 * --var-value=VARIABLE: Auxiliary tasks. (line 80)
3260 * --version: Standard options. (line 11)
3261 * --with-mktextex-default: mktex configuration. (line 12)
3262 * --without-mktexfmt-default: mktex configuration. (line 12)
3263 * --without-mktexmf-default: mktex configuration. (line 12)
3264 * --without-mktexocp-default: mktex configuration. (line 12)
3265 * --without-mktexofm-default: mktex configuration. (line 12)
3266 * --without-mktexpk-default: mktex configuration. (line 12)
3267 * --without-mktextfm-default: mktex configuration. (line 12)
3268 * -1 debugging value: Debugging. (line 23)
3269 * -A option to ls: ls-R. (line 39)
3270 * -D NUM: Path searching options.
3271 (line 52)
3272 * -iname, find predicate: Casefolding examples.
3273 (line 78)
3274 * -L option to ls: ls-R. (line 44)
3275 * ; translated to : in texmf.cnf: Config files. (line 66)
3276 * : may not be :: Searching overview. (line 13)
3277 * :: expansion: Default expansion. (line 6)
3278 * !! and casefolding: Casefolding examples.
3279 (line 57)
3280 * !! in path specifications: ls-R. (line 57)
3281 * !! in TEXMFDBS: ls-R. (line 11)
3282 * . directories, ignored: ls-R. (line 39)
3283 * . files: ls-R. (line 39)
3284 * .2602gf: Unable to generate fonts.
3285 (line 36)
3286 * .afm: Supported file formats.
3287 (line 22)
3288 * .base: Supported file formats.
3289 (line 26)
3290 * .bib: Supported file formats.
3291 (line 30)
3292 * .bltxml: Supported file formats.
3293 (line 34)
3294 * .bst: Supported file formats.
3295 (line 38)
3296 * .cid: Supported file formats.
3297 (line 68)
3298 * .cmap: Supported file formats.
3299 (line 46)
3300 * .cnf: Supported file formats.
3301 (line 49)
3302 * .dll: Supported file formats.
3303 (line 42)
3304 * .enc: Supported file formats.
3305 (line 61)
3306 * .eps: Supported file formats.
3307 (line 79)
3308 * .epsi: Supported file formats.
3309 (line 79)
3310 * .fea: Supported file formats.
3311 (line 71)
3312 * .fmt: Supported file formats.
3313 (line 64)
3314 * .ist: Supported file formats.
3315 (line 84)
3316 * .lig: Supported file formats.
3317 (line 88)
3318 * .lua: Supported file formats.
3319 (line 94)
3320 * .luatex: Supported file formats.
3321 (line 94)
3322 * .luc: Supported file formats.
3323 (line 94)
3324 * .luctex: Supported file formats.
3325 (line 94)
3326 * .map: Supported file formats.
3327 (line 98)
3328 * .mem: Supported file formats.
3329 (line 101)
3330 * .mf: Supported file formats.
3331 (line 109)
3332 * .mft: Supported file formats.
3333 (line 117)
3334 * .mlbib: Supported file formats.
3335 (line 125)
3336 * .mlbst: Supported file formats.
3337 (line 129)
3338 * .mp: Supported file formats.
3339 (line 133)
3340 * .ocp: Supported file formats.
3341 (line 141)
3342 * .ofm: Supported file formats.
3343 (line 145)
3344 * .opl: Supported file formats.
3345 (line 152)
3346 * .otp: Supported file formats.
3347 (line 155)
3348 * .ovf: Supported file formats.
3349 (line 158)
3350 * .ovp: Supported file formats.
3351 (line 161)
3352 * .pfa: Supported file formats.
3353 (line 215)
3354 * .pfb: Supported file formats.
3355 (line 215)
3356 * .pk: Supported file formats.
3357 (line 168)
3358 * .pool: Supported file formats.
3359 (line 113)
3360 * .pool <1>: Supported file formats.
3361 (line 137)
3362 * .pool <2>: Supported file formats.
3363 (line 199)
3364 * .pro: Supported file formats.
3365 (line 173)
3366 * .profile, (un)writable by TeX: Security. (line 16)
3367 * .PROGNAME qualifier in texmf.cnf: Config files. (line 50)
3368 * .ris: Supported file formats.
3369 (line 177)
3370 * .sfd: Supported file formats.
3371 (line 181)
3372 * .so: Supported file formats.
3373 (line 42)
3374 * .tex: Supported file formats.
3375 (line 184)
3376 * .tex file, included in ls-R: ls-R. (line 39)
3377 * .texlua: Supported file formats.
3378 (line 94)
3379 * .texluc: Supported file formats.
3380 (line 94)
3381 * .tfm: Supported file formats.
3382 (line 203)
3383 * .tlu: Supported file formats.
3384 (line 94)
3385 * .ttc: Supported file formats.
3386 (line 211)
3387 * .ttf: Supported file formats.
3388 (line 211)
3389 * .vf: Supported file formats.
3390 (line 223)
3391 * .w: Supported file formats.
3392 (line 53)
3393 * .web: Supported file formats.
3394 (line 53)
3395 * .web <1>: Supported file formats.
3396 (line 227)
3397 * { expansion: Brace expansion. (line 6)
3398 * / may not be /: Searching overview. (line 13)
3399 * /, trailing in home directory: Tilde expansion. (line 19)
3400 * //: Subdirectory expansion.
3401 (line 6)
3402 * /etc/profile: Unable to find files.
3403 (line 14)
3404 * /etc/profile and aliases: ls-R. (line 25)
3405 * /var/tmp/texfonts: mktex configuration. (line 113)
3406 * \, line continuation in texmf.cnf: Config files. (line 37)
3407 * \openin: Searching overview. (line 31)
3408 * \openout: Security. (line 16)
3409 * \special, suppressing warnings about: Suppressing warnings.
3410 (line 31)
3411 * = omitted in texmf.cnf and misparsing: Config files. (line 86)
3412 * ~ expansion: Tilde expansion. (line 6)
3413 * $ expansion: Variable expansion. (line 6)
3414 * 2602gf: Unable to generate fonts.
3415 (line 36)
3416 * 8.3 filenames, using: mktex configuration. (line 68)
3417 * absolute filenames: Searching overview. (line 58)
3418 * access system call: Casefolding examples.
3419 (line 86)
3420 * access warnings: Searching overview. (line 63)
3421 * AFMFONTS: Supported file formats.
3422 (line 22)
3423 * aliases for fonts: Fontmap. (line 6)
3424 * aliases, for filenames: Filename aliases. (line 6)
3425 * all: Suppressing warnings.
3426 (line 13)
3427 * all matches, finding: Path searching options.
3428 (line 10)
3429 * alphabetical order, not: Subdirectory expansion.
3430 (line 6)
3431 * announcement mailing list: Mailing lists. (line 6)
3432 * API, re-entrant: Programming overview.
3433 (line 16)
3434 * append-only directories and mktexpk: Global font cache and security.
3435 (line 19)
3436 * appendonlydir: mktex configuration. (line 60)
3437 * Apple filesystem, case-insensitive: Casefolding rationale.
3438 (line 6)
3439 * arguments to mktex: mktex script arguments.
3440 (line 6)
3441 * argv[0]: Calling sequence. (line 14)
3442 * autoconf, recommended: Calling sequence. (line 97)
3443 * automounter, and ls-R: ls-R. (line 46)
3444 * auxiliary tasks: Auxiliary tasks. (line 6)
3445 * Bach, Johann Sebastian: Default expansion. (line 41)
3446 * backslash-newline: Config files. (line 37)
3447 * basic glyph lookup: Basic glyph lookup. (line 6)
3448 * Berry, Karl: History. (line 12)
3449 * BIBINPUTS: Supported file formats.
3450 (line 30)
3451 * BIBINPUTS <1>: Supported file formats.
3452 (line 125)
3453 * blank lines, in texmf.cnf: Config files. (line 35)
3454 * BLTXMLINPUTS: Supported file formats.
3455 (line 34)
3456 * brace expansion: Brace expansion. (line 6)
3457 * Breitenlohner, Peter: History. (line 78)
3458 * BSTINPUTS: Supported file formats.
3459 (line 38)
3460 * BSTINPUTS <1>: Supported file formats.
3461 (line 129)
3462 * bug address: Reporting bugs. (line 6)
3463 * bug checklist: Bug checklist. (line 6)
3464 * bug mailing list: Mailing lists. (line 6)
3465 * bugs, reporting: Reporting bugs. (line 6)
3466 * c-*.h: Calling sequence. (line 97)
3467 * c-auto.h: Programming overview.
3468 (line 35)
3469 * cache of fonts, local: Global font cache and security.
3470 (line 6)
3471 * calling sequence: Calling sequence. (line 6)
3472 * casefolding examples: Casefolding examples.
3473 (line 6)
3474 * casefolding fallback rationale: Casefolding rationale.
3475 (line 6)
3476 * casefolding search: Casefolding search. (line 6)
3477 * ChangeLog entry: Bug checklist. (line 52)
3478 * checklist for bug reports: Bug checklist. (line 6)
3479 * checksum: Suppressing warnings.
3480 (line 16)
3481 * circle fonts: Fontmap. (line 19)
3482 * client_path in kpse->format_info: Calling sequence. (line 47)
3483 * CLUAINPUTS: Supported file formats.
3484 (line 42)
3485 * CMAPFONTS: Supported file formats.
3486 (line 46)
3487 * cmr10, as fallback font: Fallback font. (line 15)
3488 * cmr10.vf: Searching overview. (line 31)
3489 * cnf.c: Config files. (line 105)
3490 * cnf.h: Programming with config files.
3491 (line 27)
3492 * comments, in fontmap files: Fontmap. (line 27)
3493 * comments, in texmf.cnf: Config files. (line 27)
3494 * comments, making: Introduction. (line 29)
3495 * common features in glyph lookup: Basic glyph lookup. (line 6)
3496 * common problems: Common problems. (line 6)
3497 * compilation value, source for path: Path sources. (line 23)
3498 * compiler bugs: TeX or Metafont failing.
3499 (line 6)
3500 * compiler bugs, finding: TeX or Metafont failing.
3501 (line 21)
3502 * conditions for use: Introduction. (line 32)
3503 * config files: Config files. (line 6)
3504 * config files, for Kpathsea-using programs: Calling sequence.
3505 (line 47)
3506 * config files, programming with: Programming with config files.
3507 (line 6)
3508 * config.h: Programming overview.
3509 (line 35)
3510 * config.log: Bug checklist. (line 24)
3511 * config.ps: Specially-recognized files.
3512 (line 16)
3513 * config.ps, search path for: Supported file formats.
3514 (line 57)
3515 * config.status: Bug checklist. (line 27)
3516 * configuration bugs: Bug checklist. (line 27)
3517 * configuration file, source for path: Path sources. (line 20)
3518 * configuration of mktex scripts: mktex configuration. (line 6)
3519 * configure options for mktex scripts: mktex configuration. (line 12)
3520 * ConTeXt and (no) security: Security. (line 33)
3521 * context diff: Bug checklist. (line 52)
3522 * continuation character: Config files. (line 37)
3523 * core dumps, reporting: Bug checklist. (line 58)
3524 * crashes of TeX and security: Security. (line 44)
3525 * crashes, reporting: Bug checklist. (line 58)
3526 * CWEBINPUTS: Supported file formats.
3527 (line 53)
3528 * database search: Searching overview. (line 17)
3529 * database, for filenames: Filename database. (line 6)
3530 * database, format of: Database format. (line 6)
3531 * debug.h: Debugging. (line 6)
3532 * debugger: Bug checklist. (line 58)
3533 * debugging: Debugging. (line 6)
3534 * debugging options, in Kpathsea-using program: Calling sequence.
3535 (line 39)
3536 * debugging output: Debugging. (line 27)
3537 * default expansion: Default expansion. (line 6)
3538 * default_texsizes: Fallback font. (line 6)
3539 * device, wrong: Unable to generate fonts.
3540 (line 29)
3541 * directories, making append-only: mktex configuration. (line 61)
3542 * directory permissions: Global font cache and security.
3543 (line 34)
3544 * directory structure, for TeX files: TeX directory structure.
3545 (line 6)
3546 * disabling mktex scripts: mktex configuration. (line 6)
3547 * disk search: Searching overview. (line 22)
3548 * disk searching, avoiding: ls-R. (line 57)
3549 * disk usage, reducing: Logging. (line 6)
3550 * doc files: Supported file formats.
3551 (line 189)
3552 * DOS compatible names: mktex configuration. (line 68)
3553 * dosnames: mktex configuration. (line 67)
3554 * dot files: ls-R. (line 39)
3555 * doubled colons: Default expansion. (line 6)
3556 * dpiNNN directories: mktex configuration. (line 68)
3557 * DVILJMAKEPK: mktex script names. (line 32)
3558 * DVILJSIZES: Fallback font. (line 6)
3559 * dvipdfmx.cfg: Specially-recognized files.
3560 (line 19)
3561 * DVIPSFONTS: Supported file formats.
3562 (line 258)
3563 * DVIPSHEADERS: Supported file formats.
3564 (line 215)
3565 * DVIPSMAKEPK: mktex script names. (line 32)
3566 * DVIPSSIZES: Fallback font. (line 6)
3567 * dynamic creation of files: mktex scripts. (line 6)
3568 * EC fonts, and dynamic source creation: mktex scripts. (line 6)
3569 * elt-dirs.c: Subdirectory expansion.
3570 (line 52)
3571 * elt-dirs.c <1>: Subdirectory expansion.
3572 (line 60)
3573 * enabling mktex scripts: mktex configuration. (line 6)
3574 * ENCFONTS: Supported file formats.
3575 (line 61)
3576 * engine name: Path searching options.
3577 (line 56)
3578 * environment variable, source for path: Path sources. (line 12)
3579 * environment variables for TeX: Supported file formats.
3580 (line 6)
3581 * environment variables in paths: Variable expansion. (line 6)
3582 * environment variables, old: Unable to find files.
3583 (line 14)
3584 * epoch, seconds since: Logging. (line 15)
3585 * error message macros: Calling sequence. (line 22)
3586 * examples, of casefolding searches: Casefolding examples.
3587 (line 6)
3588 * examples, of running kpsewhich: kpsewhich examples. (line 6)
3589 * excessive startup time: Slow path searching. (line 6)
3590 * expand.c: Brace expansion. (line 26)
3591 * expanding symlinks: Calling sequence. (line 31)
3592 * expansion, default: Default expansion. (line 6)
3593 * expansion, path element: Searching overview. (line 49)
3594 * expansion, search path: Path expansion. (line 6)
3595 * expansion, subdirectory: Subdirectory expansion.
3596 (line 6)
3597 * expansion, tilde: Tilde expansion. (line 6)
3598 * expansion, variable: Variable expansion. (line 6)
3599 * explicitly relative filenames: Searching overview. (line 58)
3600 * extensions, filename: File lookup. (line 24)
3601 * externally-built filename database: Filename database. (line 6)
3602 * extra colons: Default expansion. (line 6)
3603 * failed mktex... script invocation: mktex script names. (line 35)
3604 * fallback font: Fallback font. (line 6)
3605 * fallback resolutions: Fallback font. (line 6)
3606 * FAQ, Kpathsea: Common problems. (line 6)
3607 * Farwell, Matthew: Subdirectory expansion.
3608 (line 22)
3609 * file formats, supported: Supported file formats.
3610 (line 6)
3611 * file lookup: File lookup. (line 6)
3612 * file permissions: Global font cache and security.
3613 (line 30)
3614 * file types, registering new: Programming overview.
3615 (line 41)
3616 * filename aliases: Filename aliases. (line 6)
3617 * filename database: Filename database. (line 6)
3618 * filenames, absolute or explicitly relative: Searching overview.
3619 (line 58)
3620 * files, unable to find: Unable to find files.
3621 (line 6)
3622 * filesystem search: Searching overview. (line 22)
3623 * filesystem, case-(in)sensitive: Casefolding rationale.
3624 (line 6)
3625 * Findutils, GNU package: Casefolding examples.
3626 (line 78)
3627 * floating directories: Searching overview. (line 22)
3628 * fmtutil: mktex script names. (line 10)
3629 * fmtutil.cnf: Specially-recognized files.
3630 (line 22)
3631 * fmtutils.cnf: mktex configuration. (line 24)
3632 * font alias files: Fontmap. (line 6)
3633 * font generation failures: Unable to generate fonts.
3634 (line 6)
3635 * font of last resort: Fallback font. (line 6)
3636 * font set, infinite: mktex scripts. (line 6)
3637 * FONTCIDMAPS: Supported file formats.
3638 (line 68)
3639 * FONTFEATURES: Supported file formats.
3640 (line 71)
3641 * fontmap files: Fontmap. (line 6)
3642 * fontmaps: mktex configuration. (line 86)
3643 * fontmaps <1>: mktex configuration. (line 87)
3644 * fontname: mktex configuration. (line 87)
3645 * fontnames, arbitrary length: Fontmap. (line 15)
3646 * FOOINPUTS: Supported file formats.
3647 (line 240)
3648 * FOOINPUTS <1>: Supported file formats.
3649 (line 243)
3650 * fopen, redefined: Debugging. (line 54)
3651 * format of external database: Database format. (line 6)
3652 * ftp.cs.stanford.edu: unixtex.ftp. (line 20)
3653 * ftp.tug.org: unixtex.ftp. (line 6)
3654 * fundamental purpose of Kpathsea: Introduction. (line 6)
3655 * gdb, recommended: Bug checklist. (line 58)
3656 * gf: Supported file formats.
3657 (line 75)
3658 * GFFONTS: Supported file formats.
3659 (line 75)
3660 * globally writable directories: Global font cache and security.
3661 (line 13)
3662 * glyph lookup: Glyph lookup. (line 6)
3663 * glyph lookup bitmap tolerance: Basic glyph lookup. (line 15)
3664 * GLYPHFONTS: Supported file formats.
3665 (line 75)
3666 * GLYPHFONTS <1>: Supported file formats.
3667 (line 168)
3668 * glyphlist.txt: Specially-recognized files.
3669 (line 25)
3670 * GNU C compiler bugs: TeX or Metafont failing.
3671 (line 16)
3672 * GNU General Public License: Introduction. (line 32)
3673 * group-writable directories: Global font cache and security.
3674 (line 23)
3675 * GSFTOPK_DEBUG (128): Debugging. (line 88)
3676 * hash table buckets, printing: Debugging. (line 105)
3677 * hash table routines: Calling sequence. (line 91)
3678 * hash_summary_only variable for debugging: Debugging. (line 105)
3679 * history of Kpathsea: History. (line 6)
3680 * Hoekwater, Taco: History. (line 78)
3681 * home directories in paths: Tilde expansion. (line 6)
3682 * HOME, as ~ expansion: Tilde expansion. (line 6)
3683 * identifiers, characters valid in: Config files. (line 47)
3684 * include fontmap directive: Fontmap. (line 36)
3685 * INDEXSTYLE: Supported file formats.
3686 (line 84)
3687 * input lines, reading: Calling sequence. (line 91)
3688 * interactive query: Path searching options.
3689 (line 155)
3690 * interface, not frozen: Introduction. (line 29)
3691 * introduction: Introduction. (line 6)
3692 * kdebug:: Debugging. (line 105)
3693 * kdefault.c: Default expansion. (line 48)
3694 * Knuth, Donald E.: History. (line 6)
3695 * Knuth, Donald E., archive of programs by: unixtex.ftp. (line 20)
3696 * Kpathsea config file, source for path: Path sources. (line 20)
3697 * kpathsea_cnf_get: Programming with config files.
3698 (line 27)
3699 * KPATHSEA_DEBUG: Calling sequence. (line 28)
3700 * KPATHSEA_DEBUG <1>: Debugging. (line 18)
3701 * kpathsea_find_file: File lookup. (line 37)
3702 * kpathsea_find_file <1>: Calling sequence. (line 63)
3703 * kpathsea_find_glyph: Glyph lookup. (line 26)
3704 * kpathsea_find_glyph <1>: Calling sequence. (line 70)
3705 * kpathsea_finish: Calling sequence. (line 87)
3706 * kpathsea_in_name_ok: Safe filenames. (line 60)
3707 * kpathsea_in_name_ok_extended: Safe filenames. (line 60)
3708 * kpathsea_in_name_ok_silent: Safe filenames. (line 74)
3709 * kpathsea_in_name_ok_silent_extended: Safe filenames. (line 74)
3710 * kpathsea_init_prog: Fallback font. (line 15)
3711 * kpathsea_init_prog <1>: Calling sequence. (line 53)
3712 * kpathsea_new: Calling sequence. (line 9)
3713 * kpathsea_open_file: Calling sequence. (line 79)
3714 * kpathsea_out_name_ok: Safe filenames. (line 51)
3715 * kpathsea_out_name_ok_extended: Safe filenames. (line 56)
3716 * kpathsea_out_name_ok_silent: Safe filenames. (line 74)
3717 * kpathsea_out_name_ok_silent_extended: Safe filenames. (line 74)
3718 * kpathsea_set_program_name: Calling sequence. (line 14)
3719 * kpathsea_var_value: Programming with config files.
3720 (line 10)
3721 * KPATHSEA_WARNING: Config files. (line 18)
3722 * kpathsea.h: Programming overview.
3723 (line 26)
3724 * kpse mode of LuaTeX: Security. (line 33)
3725 * KPSE_BITMAP_TOLERANCE: Basic glyph lookup. (line 15)
3726 * KPSE_DEBUG_EXPAND (16): Debugging. (line 68)
3727 * KPSE_DEBUG_FOPEN (4): Debugging. (line 53)
3728 * KPSE_DEBUG_HASH (2): Debugging. (line 46)
3729 * KPSE_DEBUG_PATHS (8): Debugging. (line 60)
3730 * KPSE_DEBUG_SEARCH (32): Debugging. (line 74)
3731 * KPSE_DEBUG_STAT (1): Debugging. (line 38)
3732 * KPSE_DEBUG_VARS (64): Debugging. (line 83)
3733 * KPSE_DOT expansion: KPSE_DOT expansion. (line 6)
3734 * kpse_format_info_type: Debugging. (line 61)
3735 * kpse->debug: Debugging. (line 6)
3736 * kpse->debug <1>: Debugging. (line 18)
3737 * kpse->debug variable: Calling sequence. (line 39)
3738 * kpse->format_info: Calling sequence. (line 47)
3739 * kpse->invocation_name: Calling sequence. (line 22)
3740 * kpse->invocation_short_name: Calling sequence. (line 22)
3741 * kpse->program_name: Calling sequence. (line 22)
3742 * kpsewhich: Invoking kpsewhich. (line 6)
3743 * kpsewhich examples: kpsewhich examples. (line 6)
3744 * Kpsewhich, and debugging: Debugging. (line 31)
3745 * last-resort font: Fallback font. (line 6)
3746 * lcircle10: Fontmap. (line 19)
3747 * leading colons: Default expansion. (line 6)
3748 * leaf directories wrongly guessed: Unable to find files.
3749 (line 21)
3750 * leaf directory trick: Subdirectory expansion.
3751 (line 22)
3752 * license for using the library: Introduction. (line 32)
3753 * LIGFONTS: Supported file formats.
3754 (line 88)
3755 * lines, reading arbitrary-length: Calling sequence. (line 91)
3756 * Linux File System Standard: mktex configuration. (line 113)
3757 * local cache of fonts: Global font cache and security.
3758 (line 6)
3759 * log file: Logging. (line 6)
3760 * logging successful searches: Logging. (line 6)
3761 * lost+found directory: Searching overview. (line 63)
3762 * lostchar: Suppressing warnings.
3763 (line 19)
3764 * ls-R: Supported file formats.
3765 (line 91)
3766 * ls-R database file: ls-R. (line 6)
3767 * ls-R, simplest build: ls-R. (line 22)
3768 * LUAINPUTS: Supported file formats.
3769 (line 94)
3770 * luaotfload: Safe filenames. (line 26)
3771 * LuaTeX and security: Security. (line 33)
3772 * Mac filesystem, case-insensitive: Casefolding rationale.
3773 (line 6)
3774 * MacKenzie, David: History. (line 44)
3775 * MacKenzie, David <1>: Subdirectory expansion.
3776 (line 22)
3777 * magic characters: Searching overview. (line 13)
3778 * mailing lists: Mailing lists. (line 6)
3779 * MAKETEX_DEBUG (512): Debugging. (line 91)
3780 * MAKETEX_FINE_DEBUG (1024): Debugging. (line 100)
3781 * memory allocation routines: Calling sequence. (line 91)
3782 * metafont driver files: mktex configuration. (line 93)
3783 * Metafont failures: TeX or Metafont failing.
3784 (line 6)
3785 * Metafont installation: Unable to generate fonts.
3786 (line 51)
3787 * Metafont making too-large fonts: Unable to generate fonts.
3788 (line 36)
3789 * Metafont using the wrong device: Unable to generate fonts.
3790 (line 29)
3791 * MFBASES: Supported file formats.
3792 (line 26)
3793 * MFINPUTS: Supported file formats.
3794 (line 109)
3795 * MFPOOL: Supported file formats.
3796 (line 113)
3797 * MFTINPUTS: Supported file formats.
3798 (line 117)
3799 * MISCFONTS: Supported file formats.
3800 (line 121)
3801 * mismatched checksum warnings: Suppressing warnings.
3802 (line 17)
3803 * MISSFONT_LOG: mktex script names. (line 45)
3804 * missfont.log: mktex script names. (line 35)
3805 * missing character warnings: Suppressing warnings.
3806 (line 20)
3807 * mkocp: mktex script names. (line 18)
3808 * mkofm: mktex script names. (line 21)
3809 * mktex script configuration: mktex configuration. (line 6)
3810 * mktex script names: mktex script names. (line 6)
3811 * mktex scripts: mktex scripts. (line 6)
3812 * mktex.cnf: Specially-recognized files.
3813 (line 28)
3814 * mktex.cnf <1>: mktex configuration. (line 29)
3815 * mktex.opt: mktex configuration. (line 29)
3816 * mktex.opt <1>: mktex configuration. (line 39)
3817 * mktexdir: mktex configuration. (line 61)
3818 * mktexfmt: mktex script names. (line 10)
3819 * mktexmf: mktex script names. (line 15)
3820 * mktexpk: mktex script names. (line 24)
3821 * mktexpk can't guess mode: Unable to generate fonts.
3822 (line 12)
3823 * mktextex: mktex script names. (line 27)
3824 * mktextfm: mktex script names. (line 30)
3825 * MLBIBINPUTS: Supported file formats.
3826 (line 125)
3827 * MLBSTINPUTS: Supported file formats.
3828 (line 129)
3829 * mode directory, omitting: mktex configuration. (line 98)
3830 * Morgan, Tim: History. (line 12)
3831 * MPINPUTS: Supported file formats.
3832 (line 133)
3833 * MPMEMS: Supported file formats.
3834 (line 101)
3835 * MPPOOL: Supported file formats.
3836 (line 137)
3837 * MPSUPPORT: Supported file formats.
3838 (line 105)
3839 * MT_FEATURES: mktex configuration. (line 39)
3840 * multiple TeX hierarchies: Brace expansion. (line 20)
3841 * must exist: Searching overview. (line 31)
3842 * names for mktex scripts: mktex script names. (line 6)
3843 * Neumann, Gustaf: History. (line 56)
3844 * NFS and ls-R: ls-R. (line 46)
3845 * nomfdrivers: mktex configuration. (line 92)
3846 * nomode: mktex configuration. (line 97)
3847 * none: Suppressing warnings.
3848 (line 23)
3849 * null pointers, dereferencing: Bug checklist. (line 58)
3850 * numeric debugging values: Debugging. (line 34)
3851 * obtaining TeX: unixtex.ftp. (line 6)
3852 * OCPINPUTS: Supported file formats.
3853 (line 141)
3854 * OFMFONTS: Supported file formats.
3855 (line 145)
3856 * online Metafont display, spurious: Unable to generate fonts.
3857 (line 36)
3858 * openin_any: Safe filenames. (line 60)
3859 * openout_any: Safe filenames. (line 6)
3860 * OPENTYPEFONTS: Supported file formats.
3861 (line 149)
3862 * optimization caveat: TeX or Metafont failing.
3863 (line 12)
3864 * options for debugging: Debugging. (line 6)
3865 * OTPINPUTS: Supported file formats.
3866 (line 155)
3867 * overview of path searching: Searching overview. (line 6)
3868 * overview of programming with Kpathsea: Programming overview.
3869 (line 6)
3870 * OVFFONTS: Supported file formats.
3871 (line 158)
3872 * OVPFONTS: Supported file formats.
3873 (line 161)
3874 * paranoid mode, for output files: Safe filenames. (line 18)
3875 * path expansion: Path expansion. (line 6)
3876 * path searching: Path searching. (line 6)
3877 * path searching options: Path searching options.
3878 (line 6)
3879 * path searching, overview: Searching overview. (line 6)
3880 * path searching, standalone: Invoking kpsewhich. (line 6)
3881 * path sources: Path sources. (line 6)
3882 * pathsearch.h: Programming overview.
3883 (line 26)
3884 * pc Pascal compiler: History. (line 12)
3885 * pdfglyphlist.txt: Specially-recognized files.
3886 (line 31)
3887 * pdftex.cfg: Specially-recognized files.
3888 (line 34)
3889 * PDFTEXCONFIG: Supported file formats.
3890 (line 165)
3891 * pdftexconfig.tex: Specially-recognized files.
3892 (line 34)
3893 * permission denied: Searching overview. (line 63)
3894 * permissions, directory: Global font cache and security.
3895 (line 34)
3896 * permissions, file: Global font cache and security.
3897 (line 30)
3898 * PKFONTS: Supported file formats.
3899 (line 168)
3900 * plain.base: Unable to generate fonts.
3901 (line 46)
3902 * privacy, semblance of: Logging. (line 32)
3903 * problems, common: Common problems. (line 6)
3904 * proginit.h: Calling sequence. (line 53)
3905 * program-varying paths: Supported file formats.
3906 (line 12)
3907 * programming overview: Programming overview.
3908 (line 6)
3909 * programming with config files: Programming with config files.
3910 (line 6)
3911 * programming with Kpathsea: Calling sequence. (line 6)
3912 * programs using the library: Introduction. (line 13)
3913 * proof mode: Unable to generate fonts.
3914 (line 36)
3915 * PSHEADERS: Supported file formats.
3916 (line 173)
3917 * pxp Pascal preprocessor: History. (line 12)
3918 * quoting variable values: Variable expansion. (line 17)
3919 * rationale for casefolding fallback: Casefolding rationale.
3920 (line 6)
3921 * re-entrant API: Programming overview.
3922 (line 16)
3923 * readable: Suppressing warnings.
3924 (line 26)
3925 * reading arbitrary-length lines: Calling sequence. (line 91)
3926 * recording successful searches: Logging. (line 6)
3927 * relative filenames: Searching overview. (line 58)
3928 * reporting bugs: Reporting bugs. (line 6)
3929 * resident.c: Calling sequence. (line 47)
3930 * resolution, setting: Path searching options.
3931 (line 52)
3932 * resolutions, last-resort: Fallback font. (line 6)
3933 * restricted mode, for output files: Safe filenames. (line 15)
3934 * retrieving TeX: unixtex.ftp. (line 6)
3935 * right-hand side of variable assignments: Config files. (line 57)
3936 * RISINPUTS: Supported file formats.
3937 (line 177)
3938 * Rokicki, Tom: History. (line 12)
3939 * root user: Tilde expansion. (line 19)
3940 * runtime configuration files: Config files. (line 6)
3941 * runtime debugging: Debugging. (line 6)
3942 * Sauter fonts, and dynamic source creation: mktex scripts. (line 6)
3943 * scripts for file creation: mktex scripts. (line 6)
3944 * search path, defined: Searching overview. (line 6)
3945 * search, case-insensitive: Casefolding search. (line 6)
3946 * searching for files: File lookup. (line 6)
3947 * searching for glyphs: Glyph lookup. (line 6)
3948 * searching overview: Searching overview. (line 6)
3949 * searching the database: Searching overview. (line 17)
3950 * searching the disk: Searching overview. (line 22)
3951 * security considerations: Security. (line 6)
3952 * SELFAUTODIR: Calling sequence. (line 31)
3953 * SELFAUTOLOC: Calling sequence. (line 31)
3954 * SELFAUTOPARENT: Calling sequence. (line 31)
3955 * sending patches: Bug checklist. (line 52)
3956 * setgid scripts: Global font cache and security.
3957 (line 23)
3958 * SFDFONTS: Supported file formats.
3959 (line 181)
3960 * shell commands, security: Security. (line 24)
3961 * shell variables: Variable expansion. (line 17)
3962 * shell_escape, example for code: Programming with config files.
3963 (line 10)
3964 * site overrides for mktex...: mktex configuration. (line 29)
3965 * skeleton TeX directory: TeX directory structure.
3966 (line 6)
3967 * slow startup time: Slow path searching. (line 6)
3968 * source files: Supported file formats.
3969 (line 192)
3970 * sources for search paths: Path sources. (line 6)
3971 * special: Suppressing warnings.
3972 (line 30)
3973 * st_nlink: Subdirectory expansion.
3974 (line 26)
3975 * stack trace: Bug checklist. (line 58)
3976 * standalone path searching: Invoking kpsewhich. (line 6)
3977 * standard error and debugging output: Debugging. (line 27)
3978 * standard options: Standard options. (line 6)
3979 * startup time, excessive: Slow path searching. (line 6)
3980 * string routines: Calling sequence. (line 91)
3981 * strip: mktex configuration. (line 107)
3982 * stripsupplier: mktex configuration. (line 101)
3983 * striptypeface: mktex configuration. (line 104)
3984 * subdirectory searching: Subdirectory expansion.
3985 (line 6)
3986 * suffixes, filename: File lookup. (line 24)
3987 * suggestions, making: Introduction. (line 29)
3988 * Sun 2: History. (line 12)
3989 * supplier directory, omitting: mktex configuration. (line 102)
3990 * supplier directory, omitting <1>: mktex configuration. (line 108)
3991 * supported file formats: Supported file formats.
3992 (line 6)
3993 * suppressing warnings: Suppressing warnings.
3994 (line 6)
3995 * symbolic links not found: Unable to find files.
3996 (line 21)
3997 * symbolic links, and ls-R: ls-R. (line 44)
3998 * symlinks, resolving: Calling sequence. (line 31)
3999 * system C compiler bugs: TeX or Metafont failing.
4000 (line 16)
4001 * system-dependent casefolding behavior: Casefolding rationale.
4002 (line 6)
4003 * T1FONTS: Supported file formats.
4004 (line 215)
4005 * T1INPUTS: Supported file formats.
4006 (line 215)
4007 * T42FONTS: Supported file formats.
4008 (line 220)
4009 * tcfmgr.map: Specially-recognized files.
4010 (line 46)
4011 * TDS: TeX directory structure.
4012 (line 6)
4013 * TeX directory structure: TeX directory structure.
4014 (line 6)
4015 * TeX environment variables: Supported file formats.
4016 (line 6)
4017 * TeX failures: TeX or Metafont failing.
4018 (line 6)
4019 * TeX file lookup: File lookup. (line 6)
4020 * TeX glyph lookup: Glyph lookup. (line 6)
4021 * TeX support: TeX support. (line 6)
4022 * TeX Users Group: Introduction. (line 42)
4023 * TEX_HUSH: Searching overview. (line 63)
4024 * TEX_HUSH <1>: Suppressing warnings.
4025 (line 6)
4026 * tex-file.c: File lookup. (line 37)
4027 * tex-file.h: Programming overview.
4028 (line 26)
4029 * tex-glyph.c: Glyph lookup. (line 26)
4030 * tex-glyph.h: Programming overview.
4031 (line 26)
4032 * [email protected]: Mailing lists. (line 6)
4033 * [email protected] (bug address): Reporting bugs. (line 6)
4034 * tex.web: unixtex.ftp. (line 20)
4035 * TEXBIB: Supported file formats.
4036 (line 30)
4037 * TEXBIB <1>: Supported file formats.
4038 (line 125)
4039 * TEXCONFIG: Supported file formats.
4040 (line 57)
4041 * TEXDOCS: Supported file formats.
4042 (line 189)
4043 * TEXFONTMAPS: Supported file formats.
4044 (line 98)
4045 * TEXFONTS: Supported file formats.
4046 (line 75)
4047 * TEXFONTS <1>: Supported file formats.
4048 (line 168)
4049 * TEXFONTS <2>: Supported file formats.
4050 (line 203)
4051 * TEXFONTS <3>: Supported file formats.
4052 (line 223)
4053 * texfonts.map: Fontmap. (line 6)
4054 * TEXFORMATS: Supported file formats.
4055 (line 64)
4056 * TEXINDEXSTYLE: Supported file formats.
4057 (line 84)
4058 * TEXINPUTS: Supported file formats.
4059 (line 79)
4060 * TEXINPUTS <1>: Supported file formats.
4061 (line 184)
4062 * TEXMF: TeX directory structure.
4063 (line 6)
4064 * texmf_casefold_search: Casefolding search. (line 12)
4065 * TEXMF_OUTPUT_DIRECTORY, and missfont.log: mktex script names.
4066 (line 39)
4067 * TEXMF_OUTPUT_DIRECTORY, and paranoid output files: Safe filenames.
4068 (line 21)
4069 * texmf.cnf: Specially-recognized files.
4070 (line 38)
4071 * texmf.cnf missing, warning about: Config files. (line 18)
4072 * texmf.cnf, and variable expansion: Variable expansion. (line 6)
4073 * texmf.cnf, definition for: Config files. (line 6)
4074 * texmf.cnf, source for path: Path sources. (line 20)
4075 * TEXMFCNF: Config files. (line 6)
4076 * TEXMFCNF <1>: Supported file formats.
4077 (line 49)
4078 * TEXMFDBS: ls-R. (line 11)
4079 * TEXMFDBS <1>: Supported file formats.
4080 (line 91)
4081 * TEXMFINI: Supported file formats.
4082 (line 26)
4083 * TEXMFINI <1>: Supported file formats.
4084 (line 64)
4085 * TEXMFINI <2>: Supported file formats.
4086 (line 101)
4087 * TEXMFLOG: Logging. (line 10)
4088 * TEXMFOUTPUT, and missfont.log: mktex script names. (line 39)
4089 * TEXMFOUTPUT, and paranoid output files: Safe filenames. (line 21)
4090 * TEXMFSCRIPTS: Supported file formats.
4091 (line 195)
4092 * TEXMFSYSVAR: Safe filenames. (line 26)
4093 * texmfvar: mktex configuration. (line 122)
4094 * TEXMFVAR: mktex configuration. (line 123)
4095 * TEXMFVAR <1>: Safe filenames. (line 26)
4096 * TEXPICTS: Supported file formats.
4097 (line 79)
4098 * TEXPKS: Supported file formats.
4099 (line 168)
4100 * TEXPOOL: Supported file formats.
4101 (line 199)
4102 * TEXPSHEADERS: Supported file formats.
4103 (line 173)
4104 * TEXPSHEADERS <1>: Supported file formats.
4105 (line 215)
4106 * TEXSIZES: Fallback font. (line 6)
4107 * TEXSOURCES: Supported file formats.
4108 (line 192)
4109 * TFMFONTS: Supported file formats.
4110 (line 203)
4111 * tilde expansion: Tilde expansion. (line 6)
4112 * tilde.c: Tilde expansion. (line 25)
4113 * time system call: Logging. (line 15)
4114 * tolerance for glyph lookup: Basic glyph lookup. (line 15)
4115 * trailing / in home directory: Tilde expansion. (line 19)
4116 * trailing colons: Default expansion. (line 6)
4117 * translations, of path searching description: Path searching.
4118 (line 10)
4119 * TRFONTS: Supported file formats.
4120 (line 207)
4121 * trick for detecting leaf directories: Subdirectory expansion.
4122 (line 22)
4123 * trojan horse: Safe filenames. (line 6)
4124 * trojan horse attack: Security. (line 16)
4125 * try_std_extension_first: File lookup. (line 24)
4126 * TTFONTS: Supported file formats.
4127 (line 211)
4128 * tug.org: unixtex.ftp. (line 6)
4129 * typeface directory, omitting: mktex configuration. (line 105)
4130 * typeface directory, omitting <1>: mktex configuration. (line 108)
4131 * unable to find files: Unable to find files.
4132 (line 6)
4133 * unable to generate fonts: Unable to generate fonts.
4134 (line 6)
4135 * uname: Bug checklist. (line 20)
4136 * unixtex.ftp: unixtex.ftp. (line 6)
4137 * unknown special warnings: Suppressing warnings.
4138 (line 31)
4139 * unreadable file warnings: Suppressing warnings.
4140 (line 27)
4141 * unreadable files: Searching overview. (line 63)
4142 * unrestricted mode, for output files: Safe filenames. (line 13)
4143 * unusable ls-R warning: ls-R. (line 51)
4144 * usage patterns, finding: Logging. (line 6)
4145 * USE_TEXMFVAR: mktex configuration. (line 128)
4146 * USE_VARTEXFONTS: mktex configuration. (line 118)
4147 * USERPROFILE, as ~ expansion: Tilde expansion. (line 6)
4148 * varfonts: mktex configuration. (line 112)
4149 * variable expansion: Variable expansion. (line 6)
4150 * variable.c: Variable expansion. (line 32)
4151 * variable.h: Programming with config files.
4152 (line 10)
4153 * VARTEXFONTS: mktex configuration. (line 113)
4154 * VAX 11/750: History. (line 12)
4155 * version numbers, determining: Bug checklist. (line 15)
4156 * VF files, not found: Searching overview. (line 31)
4157 * VFFONTS: Supported file formats.
4158 (line 223)
4159 * Vojta, Paul: History. (line 30)
4160 * Walsh, Norman: History. (line 56)
4161 * warning about unusable ls-R: ls-R. (line 51)
4162 * warning, about missing texmf.cnf: Config files. (line 18)
4163 * warnings, file access: Searching overview. (line 63)
4164 * warnings, suppressing: Suppressing warnings.
4165 (line 6)
4166 * WEB2C: Supported file formats.
4167 (line 231)
4168 * Weber, Olaf: History. (line 73)
4169 * WEBINPUTS: Supported file formats.
4170 (line 227)
4171 * whitespace, in fontmap files: Fontmap. (line 31)
4172 * whitespace, not ignored on continuation lines: Config files.
4173 (line 37)
4174 * Windows and casefolding: Casefolding rationale.
4175 (line 21)
4176 * www.tug.org: unixtex.ftp. (line 6)
4177 * XDvi: Specially-recognized files.
4178 (line 41)
4179 * XDVIFONTS: Supported file formats.
4180 (line 258)
4181 * XDVIMAKEPK: mktex script names. (line 32)
4182 * XDVISIZES: Fallback font. (line 6)
4183 * zuhn, david: History. (line 50)
4184
4185 
4186 Tag Table:
4187 Node: Top1479
4188 Node: Introduction2265
4189 Node: History4372
4190 Node: unixtex.ftp8992
4191 Node: Security10474
4192 Node: Global font cache and security13282
4193 Node: TeX directory structure15263
4194 Node: Path searching19438
4195 Node: Searching overview20396
4196 Node: Path sources24303
4197 Node: Config files25573
4198 Node: Path expansion30621
4199 Node: Default expansion31590
4200 Node: Variable expansion33712
4201 Node: Tilde expansion35181
4202 Node: Brace expansion36229
4203 Node: KPSE_DOT expansion37224
4204 Node: Subdirectory expansion37749
4205 Node: Casefolding search40910
4206 Node: Casefolding rationale41687
4207 Node: Casefolding examples43045
4208 Node: Filename database48267
4209 Node: ls-R49281
4210 Node: Filename aliases53153
4211 Node: Database format54395
4212 Node: Invoking kpsewhich55444
4213 Node: kpsewhich examples56835
4214 Node: Path searching options57723
4215 Node: Specially-recognized files67986
4216 Node: Auxiliary tasks69461
4217 Node: Standard options73605
4218 Node: TeX support73973
4219 Node: Supported file formats75331
4220 Node: File lookup84082
4221 Node: Glyph lookup85887
4222 Node: Basic glyph lookup87035
4223 Node: Fontmap87943
4224 Node: Fallback font90554
4225 Node: Suppressing warnings91490
4226 Node: mktex scripts92653
4227 Node: mktex configuration93896
4228 Node: mktex script names99989
4229 Node: mktex script arguments101672
4230 Node: Programming102587
4231 Node: Programming overview103230
4232 Node: Calling sequence106141
4233 Node: Safe filenames111478
4234 Ref: openout_any111637
4235 Node: Program-specific files115467
4236 Node: Programming with config files116520
4237 Node: Reporting bugs118167
4238 Node: Bug checklist118845
4239 Node: Mailing lists122402
4240 Node: Debugging123079
4241 Node: Logging128336
4242 Node: Common problems130243
4243 Node: Unable to find files130720
4244 Node: Slow path searching133563
4245 Node: Unable to generate fonts134958
4246 Node: TeX or Metafont failing137494
4247 Node: Index138696
4248 
4249 End Tag Table
4250
4251 
4252 Local Variables:
4253 coding: utf-8
4254 End: