| 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 |
|