|
2999
|
1 \input texinfo |
|
|
2 @setfilename kpathsea.info |
|
|
3 @settitle Kpathsea: A library for path searching |
|
|
4 |
|
3172
|
5 @set version 3.2 |
|
|
6 @set month-year October 1997 |
|
2999
|
7 |
|
|
8 @c Define new indices for commands, filenames, and options. |
|
|
9 @defcodeindex cm |
|
|
10 @defcodeindex fl |
|
|
11 @defcodeindex op |
|
|
12 |
|
|
13 @c Put everything in one index (arbitrarily chosen to be the concept index). |
|
|
14 @syncodeindex cm cp |
|
|
15 @syncodeindex fl cp |
|
|
16 @syncodeindex fn cp |
|
|
17 @syncodeindex ky cp |
|
|
18 @syncodeindex op cp |
|
|
19 @syncodeindex pg cp |
|
|
20 @syncodeindex tp cp |
|
|
21 @syncodeindex vr cp |
|
|
22 |
|
|
23 @dircategory TeX |
|
|
24 @direntry |
|
3172
|
25 * Kpathsea: (kpathsea). File lookup along search paths. |
|
|
26 * kpsewhich: (kpathsea)Invoking kpsewhich. TeX file searching. |
|
|
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 * mktexlsr: (kpathsea)Filename database. Update ls-R. |
|
2999
|
32 @end direntry |
|
|
33 |
|
|
34 @ifinfo |
|
|
35 This file documents the Kpathsea library for path searching. |
|
|
36 |
|
3172
|
37 Copyright (C) 1993, 94, 95, 96, 97 K. Berry & O. Weber. |
|
2999
|
38 |
|
|
39 Permission is granted to make and distribute verbatim copies of this |
|
|
40 manual provided the copyright notice and this permission notice are |
|
|
41 preserved on all copies. |
|
|
42 |
|
|
43 @ignore |
|
|
44 Permission is granted to process this file through TeX and print the |
|
|
45 results, provided the printed document carries a copying permission |
|
|
46 notice identical to this one except for the removal of this paragraph |
|
|
47 (this paragraph not being relevant to the printed manual). |
|
|
48 @end ignore |
|
|
49 |
|
|
50 Permission is granted to copy and distribute modified versions of this |
|
|
51 manual under the conditions for verbatim copying, provided that the |
|
|
52 entire resulting derived work is distributed under the terms of a |
|
|
53 permission notice identical to this one. |
|
|
54 |
|
|
55 Permission is granted to copy and distribute translations of this manual |
|
|
56 into another language, under the above conditions for modified versions, |
|
|
57 except that this permission notice may be stated in a translation |
|
|
58 approved by the Free Software Foundation. |
|
|
59 @end ifinfo |
|
|
60 |
|
|
61 |
|
|
62 @titlepage |
|
|
63 |
|
|
64 @title Kpathsea library |
|
|
65 @subtitle for version @value{version} |
|
|
66 @subtitle @value{month-year} |
|
|
67 @author K. Berry (@email{kb@@mail.tug.org}) |
|
3172
|
68 @author O. Weber (@email{infovore@@xs4all.nl}) |
|
2999
|
69 |
|
|
70 @page |
|
|
71 |
|
|
72 @vskip 0pt plus 1filll |
|
3172
|
73 Copyright @copyright{} 1993, 94, 95, 96, 97 K. Berry & O. Weber. |
|
2999
|
74 |
|
|
75 Permission is granted to make and distribute verbatim copies of this |
|
|
76 manual provided the copyright notice and this permission notice are |
|
|
77 preserved on all copies. |
|
|
78 |
|
|
79 Permission is granted to copy and distribute modified versions of this |
|
|
80 manual under the conditions for verbatim copying, provided that the |
|
|
81 entire resulting derived work is distributed under the terms of a |
|
|
82 permission notice identical to this one. |
|
|
83 |
|
|
84 Permission is granted to copy and distribute translations of this manual |
|
|
85 into another language, under the above conditions for modified versions, |
|
|
86 except that this permission notice may be stated in a translation |
|
|
87 approved by the Free Software Foundation. |
|
|
88 @end titlepage |
|
|
89 |
|
|
90 |
|
|
91 @ifinfo |
|
|
92 @node Top |
|
|
93 @top Kpathsea library |
|
|
94 |
|
|
95 This manual documents how to install and use the Kpathsea library for |
|
|
96 filename lookup. It corresponds to version @value{version}, |
|
|
97 released in @value{month-year}. |
|
|
98 |
|
|
99 @menu |
|
|
100 * Introduction:: Overview. |
|
|
101 * Installation:: Compilation, installation, and bug reporting. |
|
|
102 |
|
|
103 * Path searching:: How filename lookups work. |
|
|
104 * TeX support:: Special support for TeX-related file lookups. |
|
|
105 |
|
|
106 * Programming:: How to use Kpathsea features in your program. |
|
|
107 |
|
|
108 * Index:: General index. |
|
|
109 @end menu |
|
|
110 @end ifinfo |
|
|
111 |
|
|
112 |
|
|
113 @node Introduction |
|
|
114 @chapter Introduction |
|
|
115 |
|
|
116 @cindex introduction |
|
|
117 @cindex fundamental purpose of Kpathsea |
|
|
118 |
|
|
119 This manual corresponds to version @value{version} of the Kpathsea |
|
|
120 library, released in @value{month-year}. |
|
|
121 |
|
|
122 The library's fundamental purpose is to return a filename from a list of |
|
|
123 directories specified by the user, similar to what shells do when |
|
|
124 looking up program names to execute. |
|
|
125 |
|
|
126 @cindex programs using the library |
|
3172
|
127 The following software, all of which we maintain, uses this library: |
|
2999
|
128 |
|
|
129 @itemize @bullet |
|
|
130 @item Dviljk (see the @samp{dvilj} man page) |
|
|
131 @item Dvipsk (@pxref{Top, , Introduction, dvips, Dvips: A DVI driver}) |
|
|
132 @item GNU font utilities (@pxref{Top, , Introduction, fontu, GNU font |
|
|
133 utilities}) |
|
|
134 @item Web2c (@pxref{Top, , Introduction, web2c, Web2c: A @TeX{} |
|
|
135 implementation}) |
|
|
136 @item Xdvik (see the @samp{xdvi} man page) |
|
|
137 @end itemize |
|
|
138 |
|
3172
|
139 @noindent Other software that we do not maintain also uses it. |
|
2999
|
140 |
|
|
141 @cindex interface, not frozen |
|
|
142 @cindex comments, making |
|
|
143 @cindex suggestions, making |
|
3172
|
144 We are still actively maintaining the library (and probably always will |
|
|
145 be, despite our hopes). If you have comments or suggestions, please send |
|
|
146 them to us (@pxref{Reporting bugs}). |
|
2999
|
147 |
|
|
148 @cindex conditions for use |
|
|
149 @cindex license for using the library |
|
|
150 @cindex GNU General Public License |
|
3172
|
151 We distribute the library under the GNU Library General Public License |
|
2999
|
152 (LGPL), with one exception (see below). In short, this means if you |
|
|
153 write a program using the library, you must (offer to) distribute the |
|
|
154 source to the library, along with any changes you have made, and allow |
|
|
155 anyone to modify the library source and distribute their modifications. |
|
|
156 It does not mean you have to distribute the source to your program, |
|
3172
|
157 although we hope you will. |
|
2999
|
158 |
|
|
159 The exception is the part of the file @file{expand.c} which implements |
|
3172
|
160 brace expansion. We took this from Bash, which is covered by the GNU |
|
2999
|
161 General Public License (GPL). Therefore, if you wish to redistribute |
|
|
162 the library under the LGPL, you must remove this code. (If you write a |
|
3172
|
163 replacement we can distribute, we hope you'll share it with us.) See the |
|
2999
|
164 files @file{COPYING} and @file{COPYING.LIB} for the text of the GNU licenses. |
|
|
165 |
|
|
166 @cindex @TeX{} Users Group |
|
|
167 If you know enough about @TeX{} to be reading this manual, then you (or |
|
|
168 your institution) should consider joining the @TeX{} Users Group (if |
|
|
169 you're already a member, great!). TUG produces the periodical |
|
|
170 @cite{TUGboat}, sponsors an annual meeting and publishes the |
|
|
171 proceedings, and arranges courses on @TeX{} for all levels of users |
|
|
172 throughout the world. Anyway, here is the address: |
|
|
173 |
|
|
174 @flindex tug@@tug.org |
|
|
175 @display |
|
|
176 @TeX{} Users Group |
|
3172
|
177 P.O. Box 1239 |
|
|
178 Three Rivers, CA 93271-1239 |
|
|
179 USA |
|
|
180 phone: 1 209 561 0112 |
|
|
181 fax: 1 209 561 4584 |
|
2999
|
182 email: @email{tug@@tug.org} |
|
|
183 @end display |
|
|
184 |
|
|
185 @menu |
|
|
186 * History:: |
|
|
187 @end menu |
|
|
188 |
|
|
189 |
|
|
190 @node History |
|
|
191 @section History |
|
|
192 |
|
|
193 @cindex history of Kpathsea |
|
|
194 |
|
|
195 @cindex Knuth, Donald E. |
|
|
196 (This section is for those people who are curious about how the library |
|
3172
|
197 came about.) (If you like to read historical accounts of software, we |
|
2999
|
198 urge you to seek out the GNU Autoconf manual and the ``Errors of |
|
|
199 @TeX{}'' paper by Don Knuth, published in @cite{Software---Practice and |
|
|
200 Experience} 19(7), July 1989.) |
|
|
201 |
|
|
202 @cindex Morgan, Tim |
|
|
203 @cindex Rokicki, Tom |
|
3172
|
204 @cindex Berry, Karl |
|
2999
|
205 @cindex VAX 11/750 |
|
|
206 @cindex Sun 2 |
|
|
207 @pindex pxp @r{Pascal preprocessor} |
|
|
208 @pindex pc @r{Pascal compiler} |
|
3172
|
209 [Karl writes.] My first ChangeLog entry for Web2c seems to be February |
|
|
210 1990, but I may have done some work before then. In any case, Tim |
|
|
211 Morgan and I were jointly maintaining it for a time. (I should mention |
|
|
212 here that Tim had made Web2c into a real distribution long before I had |
|
|
213 ever used it or even heard of it, and Tom Rokicki did the original |
|
|
214 implementation. I was using @code{pxp} and @code{pc} on VAX 11/750's |
|
|
215 and the hot new Sun 2 machines.) |
|
2999
|
216 |
|
|
217 It must have been later in 1990 and 1991 that I started working on |
|
|
218 @cite{@TeX{} for the Impatient}. Dvips, Xdvi, Web2c, and the GNU |
|
|
219 fontutils (which I was also writing at the time) all used different |
|
|
220 environment variables, and, more importantly, had different bugs in |
|
|
221 their path searching. This became extremely painful, as I was stressing |
|
|
222 everything to the limit working on the book. I also desperately wanted |
|
|
223 to implement subdirectory searching, since I couldn't stand putting |
|
|
224 everything in one big directory, and also couldn't stand having to |
|
|
225 explicitly specify @file{cm}, @file{pandora}, @dots{} in a path. |
|
|
226 |
|
|
227 @cindex Vojta, Paul |
|
|
228 In the first incarnation, I just hacked separately on each |
|
|
229 program---that was the original subdirectory searching code in both Xdvi |
|
|
230 and Dvips, though I think Paul Vojta has completely rewritten Xdvi's |
|
|
231 support by now. That is, I tried to go with the flow in each program, |
|
|
232 rather than changing the program's calling sequences to conform to |
|
|
233 common routines. |
|
|
234 |
|
|
235 Then, as bugs inevitably appeared, I found I was fixing the same thing |
|
|
236 three times (Web2c and fontutils were always sharing code, since I |
|
|
237 maintained those---there was no Dvipsk or Xdvik or Dviljk at this |
|
|
238 point). After a while, I finally started sharing source files. They |
|
|
239 weren't yet a library, though. I just kept things up to date with shell |
|
|
240 scripts. (I was developing on a 386 running ISC 2.2 at the time, and so |
|
|
241 didn't have symbolic links. An awful experience.) |
|
|
242 |
|
|
243 @cindex MacKenzie, David |
|
|
244 The ChangeLogs for Xdvik and Dvipsk record initial releases of those |
|
|
245 distributions in May and June 1992. I think it was because I was tired |
|
|
246 of the different configuration strategies of each program, not so much |
|
|
247 because of the path searching. (Autoconf was being developed by David |
|
|
248 MacKenzie and others, and I was adapting it to @TeX{} and friends.) |
|
|
249 |
|
|
250 @cindex zuhn, david |
|
|
251 I started to make a separate library that other programs could link with |
|
|
252 on my birthday in April 1993, according to the ChangeLog. I don't |
|
|
253 remember exactly why I finally took the time to make it a separate |
|
|
254 library; a conversation with david zuhn that initiated it. Just seemed |
|
|
255 like it was time. |
|
|
256 |
|
|
257 @cindex Walsh, Norman |
|
|
258 @cindex Neumann, Gustaf |
|
|
259 Dviljk got started in March 1994 after I bought a Laserjet 4. (Kpathsea |
|
|
260 work got suspended while Norm Walsh and I, with Gustaf Neumann's help, |
|
|
261 implemented a way for @TeX{} to get at all those neat builtin LJ4 fonts |
|
|
262 @dots{} such a treat to have something to typeset in besides Palatino!) |
|
|
263 |
|
|
264 By spring of 1995, I had implemented just about all the path-searching |
|
|
265 features in Kpathsea that I plan to, driven beyond my initial goals by |
|
|
266 Thomas Esser and others. I then started to integrate Web2c with |
|
|
267 Kpathsea. After the release of a stable Web2c, I hope to be able to stop |
|
|
268 development, and turn most of my attention back to making fonts for GNU. |
|
|
269 (Always assuming Micros**t hasn't completely obliterated Unix by then, |
|
|
270 or that software patents haven't stopped software development by anybody |
|
|
271 smaller than a company with a million-dollar-a-year legal budget. Which |
|
|
272 is actually what I think is likely to happen, but that's another |
|
|
273 story@dots{}) |
|
|
274 |
|
3172
|
275 @cindex Weber, Olaf |
|
|
276 [Olaf writes.] At the end of 1997, UNIX is still alive and kicking, |
|
|
277 individuals still develop software, and Web2c development still |
|
|
278 continues. Karl had been looking for some time for someone to take up |
|
|
279 part of the burden, and I volunteered. |
|
|
280 |
|
|
281 |
|
2999
|
282 @include install.texi |
|
|
283 @include hier.texi |
|
|
284 @include unixtex.texi |
|
|
285 @include bugs.texi |
|
|
286 |
|
|
287 |
|
|
288 @node Path searching |
|
|
289 @chapter Path searching |
|
|
290 |
|
|
291 @cindex path searching |
|
|
292 |
|
|
293 This chapter describes the generic path searching mechanism Kpathsea |
|
|
294 provides. For information about searching for particular file types |
|
|
295 (e.g., @TeX{} fonts), see the next chapter. |
|
|
296 |
|
|
297 @menu |
|
|
298 * Searching overview:: Basic scheme for searching. |
|
|
299 * Path sources:: Where search paths can be defined. |
|
|
300 * Path expansion:: Special constructs in search paths. |
|
|
301 * Filename database:: Using an externally-built list to search. |
|
|
302 * Invoking kpsewhich:: Standalone path lookup. |
|
|
303 @end menu |
|
|
304 |
|
|
305 |
|
|
306 @node Searching overview |
|
|
307 @section Searching overview |
|
|
308 |
|
|
309 @cindex searching overview |
|
|
310 @cindex path searching, overview |
|
|
311 @cindex overview of path searching |
|
|
312 |
|
|
313 @cindex search path, defined |
|
|
314 A @dfn{search path} is a colon-separated list of @dfn{path elements}, |
|
|
315 which are directory names with a few extra frills. A search path can |
|
|
316 come from (a combination of) many sources; see below. To look up a file |
|
|
317 @samp{foo} along a path @samp{.:/dir}, Kpathsea checks each element of |
|
|
318 the path in turn: first @file{./foo}, then @file{/dir/foo}, returning |
|
|
319 the first match (or possibly all matches). |
|
|
320 |
|
|
321 @cindex magic characters |
|
|
322 @kindex : @r{may not be :} |
|
|
323 @kindex / @r{may not be /} |
|
|
324 The ``colon'' and ``slash'' mentioned here aren't necessarily @samp{:} |
|
|
325 and @samp{/} on non-Unix systems. Kpathsea tries to adapt to other |
|
|
326 operating systems' conventions. |
|
|
327 |
|
|
328 @cindex database search |
|
|
329 @cindex searching the database |
|
|
330 To check a particular path element @var{e}, Kpathsea first sees if a |
|
|
331 prebuilt database (@pxref{Filename database}) applies to @var{e}, i.e., |
|
|
332 if the database is in a directory that is a prefix of @var{e}. If so, |
|
|
333 the path specification is matched against the contents of the database. |
|
|
334 |
|
|
335 @cindex floating directories |
|
|
336 @cindex filesystem search |
|
|
337 @cindex disk search |
|
|
338 @cindex searching the disk |
|
|
339 If the database does not exist, or does not apply to this path element, |
|
|
340 or contains no matches, the filesystem is searched (if this was not |
|
|
341 forbidden by the specification with @samp{!!} and if the file being |
|
|
342 searched for must exist). Kpathsea constructs the list of directories |
|
|
343 that correspond to this path element, and then checks in each for the |
|
|
344 file being searched for. (To help speed future lookups of files in the |
|
|
345 same directory, the directory in which a file is found is floated to the |
|
|
346 top of the directory list.) |
|
|
347 |
|
|
348 @cindex must exist |
|
|
349 @cindex VF files, not found |
|
|
350 @flindex cmr10.vf |
|
|
351 @findex \openin |
|
|
352 The ``file must exist'' condition comes into play with VF files and |
|
|
353 input files read by the @TeX{} @samp{\openin} command. These files may |
|
|
354 not exist (consider @file{cmr10.vf}), and so it would be wrong to search |
|
|
355 the disk for them. Therefore, if you fail to update @file{ls-R} when |
|
|
356 you install a new VF file, it will never be found. |
|
|
357 |
|
|
358 Each path element is checked in turn: first the database, then the disk. |
|
|
359 If a match is found, the search stops and the result is returned. This |
|
|
360 avoids possibly-expensive processing of path specifications that are |
|
|
361 never needed on a particular run. (Unless the search explicitly |
|
|
362 requested all matches.) |
|
|
363 |
|
|
364 @cindex expansion, path element |
|
|
365 Although the simplest and most common path element is a directory name, |
|
|
366 Kpathsea supports additional features in search paths: layered default |
|
|
367 values, environment variable names, config file values, users' home |
|
|
368 directories, and recursive subdirectory searching. Thus, we say that |
|
3172
|
369 Kpathsea @dfn{expands} a path element, meaning transforming all the |
|
2999
|
370 magic specifications into the basic directory name or names. This |
|
|
371 process is described in the sections below. It happens in the same |
|
|
372 order as the sections. |
|
|
373 |
|
|
374 @cindex absolute filenames |
|
|
375 @cindex relative filenames |
|
|
376 @cindex explicitly relative filenames |
|
|
377 @cindex filenames, absolute or explicitly relative |
|
|
378 Exception to all of the above: If the filename being searched for is |
|
|
379 absolute or explicitly relative, i.e., starts with @samp{/} or @samp{./} |
|
|
380 or @samp{../}, Kpathsea simply checks if that file exists. |
|
|
381 |
|
|
382 @cindex permission denied |
|
|
383 @cindex unreadable files |
|
|
384 @cindex access warnings |
|
|
385 @cindex warnings, file access |
|
|
386 @flindex lost+found @r{directory} |
|
|
387 @vindex TEX_HUSH |
|
|
388 Ordinarily, if Kpathsea tries to access a file or directory that cannot |
|
|
389 be read, it gives a warning. This is so you will be alerted to |
|
|
390 directories or files that accidentally lack read permission (for |
|
|
391 example, a @file{lost+found}). If you prefer not to see these warnings, |
|
|
392 include the value @samp{readable} in the @code{TEX_HUSH} environment |
|
|
393 variable or config file value. |
|
|
394 |
|
|
395 This generic path searching algorithm is implemented in |
|
|
396 @file{kpathsea/pathsearch.c}. It is employed by a higher-level |
|
|
397 algorithm when searching for a file of a particular type (@pxref{File |
|
|
398 lookup}, and @ref{Glyph lookup}). |
|
|
399 |
|
|
400 |
|
|
401 @node Path sources |
|
|
402 @section Path sources |
|
|
403 |
|
|
404 @cindex path sources |
|
|
405 @cindex sources for search paths |
|
|
406 |
|
|
407 A search path can come from many sources. In the order in which |
|
|
408 Kpathsea uses them: |
|
|
409 |
|
|
410 @enumerate |
|
|
411 @item |
|
|
412 @cindex environment variable, source for path |
|
|
413 A user-set environment variable, e.g., @code{TEXINPUTS}. |
|
|
414 Environment variables with an underscore and the program name appended |
|
|
415 override; for example, @code{TEXINPUTS_latex} overrides @code{TEXINPUTS} |
|
|
416 if the program being run is named @samp{latex}. |
|
|
417 |
|
|
418 @item |
|
|
419 A program-specific configuration file, e.g., an @samp{S /a:/b} line in |
|
|
420 Dvips' @file{config.ps} (@pxref{Config files,,, dvips, Dvips}). |
|
|
421 |
|
|
422 @item |
|
|
423 @cindex configuration file, source for path |
|
|
424 @cindex Kpathsea config file, source for path |
|
|
425 @flindex texmf.cnf@r{, source for path} |
|
|
426 A line in a Kpathsea configuration file @file{texmf.cnf}, e.g., |
|
|
427 @samp{TEXINPUTS=/c:/d} (see below). |
|
|
428 |
|
|
429 @item |
|
|
430 @cindex compilation value, source for path |
|
|
431 The compile-time default (specified in @file{kpathsea/paths.h}). |
|
|
432 @end enumerate |
|
|
433 |
|
|
434 You can see each of these values for a given search path by using the |
|
|
435 debugging options (@pxref{Debugging}). |
|
|
436 |
|
|
437 These sources may be combined via default expansion (@pxref{Default |
|
|
438 expansion}). |
|
|
439 |
|
|
440 @menu |
|
|
441 * Config files:: Kpathsea's runtime config files (texmf.cnf). |
|
|
442 @end menu |
|
|
443 |
|
|
444 |
|
|
445 @node Config files |
|
|
446 @subsection Config files |
|
|
447 |
|
|
448 @cindex config files |
|
|
449 @flindex texmf.cnf@r{, definition for} |
|
|
450 |
|
|
451 @cindex runtime configuration files |
|
|
452 @vindex TEXMFCNF |
|
|
453 As mentioned above, Kpathsea reads @dfn{runtime configuration files} |
|
|
454 named @file{texmf.cnf} for search path and other definitions. The |
|
|
455 search path used to look for these configuration files is named |
|
|
456 @code{TEXMFCNF}, and is constructed in the usual way, as described |
|
|
457 above, except that configuration files cannot be used to define the |
|
|
458 path, naturally; also, an @file{ls-R} database is not used to search for |
|
|
459 them. |
|
|
460 |
|
|
461 Kpathsea reads @emph{all} @file{texmf.cnf} files in the search path, not |
|
|
462 just the first one found; definitions in earlier files override those in |
|
3172
|
463 later files. Thus, if the search path is @samp{.:$TEXMF}, values from |
|
2999
|
464 @file{./texmf.cnf} override those from @file{$TEXMF/texmf.cnf}. |
|
|
465 |
|
|
466 While (or instead of) reading this description, you may find it helpful |
|
|
467 to look at the distributed @file{texmf.cnf}, which uses or at least |
|
|
468 mentions most features. The format of @file{texmf.cnf} files follows: |
|
|
469 |
|
|
470 @itemize @bullet |
|
|
471 @item |
|
|
472 @cindex comments, in @file{texmf.cnf} |
|
|
473 Comments start with @samp{%} and continue to the end of the line. |
|
|
474 |
|
|
475 @item |
|
|
476 @cindex blank lines, in @file{texmf.cnf} |
|
|
477 Blank lines are ignored. |
|
|
478 |
|
|
479 @item |
|
|
480 @cindex backslash-newline |
|
|
481 @cindex continuation character |
|
|
482 @cindex whitespace, not ignored on continuation lines |
|
|
483 @kindex \@r{, line continuation in @file{texmf.cnf}} |
|
|
484 A @samp{\} at the end of a line acts as a continuation character, i.e., |
|
|
485 the next line is appended. Whitespace at the beginning of continuation |
|
|
486 lines is not ignored. |
|
|
487 |
|
|
488 @item Each remaining line must look like |
|
|
489 |
|
|
490 @example |
|
|
491 @var{variable} @r{[}. @var{progname}@r{]} @r{[}=@r{]} @var{value} |
|
|
492 @end example |
|
|
493 |
|
|
494 @noindent where the @samp{=} and surrounding whitespace is optional. |
|
|
495 |
|
|
496 @item |
|
|
497 @cindex identifiers, characters valid in |
|
|
498 The @var{variable} name may contain any character other than whitespace, |
|
|
499 @samp{=}, or @samp{.}, but sticking to @samp{A-Za-z_} is safest. |
|
|
500 |
|
|
501 @item If @samp{.@var{progname}} is present, the definition only |
|
|
502 applies if the program that is running is named (i.e., the last |
|
|
503 component of @code{argv[0]} is) @var{progname} or |
|
|
504 @file{@var{progname}.exe}. This allows different flavors of @TeX{} to |
|
|
505 have different search paths, for example. |
|
|
506 |
|
|
507 @item |
|
|
508 @cindex right-hand side of variable assignments |
|
|
509 @var{value} may contain any characters except @samp{%} and @samp{@@}. |
|
|
510 (These restrictions are only necessary because of the processing done on |
|
|
511 @file{texmf.cnf} at build time, so you can stick those characters in |
|
|
512 after installation if you have to.) The @samp{$@var{var}.@var{prog}} |
|
|
513 feature is not available on the right-hand side; instead, you must use |
|
|
514 an additional variable (see below for example). A @samp{;} in |
|
|
515 @var{value} is translated to @samp{:} if running under Unix; this is |
|
|
516 useful to write a single @file{texmf.cnf} which can be used under both |
|
|
517 Unix and NT. (If you really want @samp{;}'s in your filenames, add |
|
|
518 @samp{-DALLOW_SEMICOLON_IN_FILENAMES} to @code{CFLAGS}.) |
|
|
519 |
|
|
520 @item All definitions are read before anything is expanded, so you can |
|
|
521 use variables before they are defined (like Make, unlike most other |
|
|
522 programs). |
|
|
523 @end itemize |
|
|
524 |
|
|
525 @noindent Here is a configuration file fragment illustrating most of |
|
|
526 these points: |
|
|
527 |
|
|
528 @example |
|
|
529 % TeX input files -- i.e., anything to be found by \input or \openin ... |
|
|
530 latex209_inputs = .:$TEXMF/tex/latex209//:$TEXMF/tex// |
|
|
531 latex2e_inputs = .:$TEXMF/tex/latex//:$TEXMF/tex// |
|
|
532 TEXINPUTS = .:$TEXMF/tex// |
|
|
533 TEXINPUTS.latex209 = $latex209_inputs |
|
|
534 TEXINPUTS.latex2e = $latex2e_inputs |
|
|
535 TEXINPUTS.latex = $latex2e_inputs |
|
|
536 @end example |
|
|
537 |
|
|
538 @cindex shell scripts as configuration files |
|
|
539 @cindex configuration files as shell scripts. |
|
|
540 Although this format has obvious similarities to Bourne shell |
|
|
541 scripts---change the comment character to @code{#}, disallow spaces |
|
|
542 around the @code{=}, and get rid of the @code{.@var{name}} convention, |
|
|
543 and it could be run through the shell. But there seemed little |
|
|
544 advantage to doing this, since all the information would have to passed |
|
|
545 back to Kpathsea and parsed there anyway, since the @code{sh} process |
|
|
546 couldn't affect its parent's environment. |
|
|
547 |
|
|
548 @flindex cnf.c |
|
|
549 The implementation of all this is in @file{kpathsea/cnf.c}. |
|
|
550 |
|
|
551 |
|
|
552 @node Path expansion |
|
|
553 @section Path expansion |
|
|
554 |
|
|
555 @cindex path expansion |
|
|
556 @cindex expansion, search path |
|
|
557 |
|
|
558 Kpathsea recognizes certain special characters and constructions in |
|
|
559 search paths, similar to that in shells. As a general example: |
|
|
560 @samp{~$USER/@{foo,bar@}//baz} expands to all subdirectories under |
|
|
561 directories @file{foo} and @file{bar} in @t{$USER}'s home directory that |
|
|
562 contain a directory or file @file{baz}. These expansions are explained |
|
|
563 in the sections below. |
|
|
564 |
|
|
565 @menu |
|
|
566 * Default expansion:: a: or :a or a::b expands to a default. |
|
|
567 * Variable expansion:: $foo and $@{foo@} expand to environment values. |
|
|
568 * Tilde expansion:: ~ and ~user expand to home directories. |
|
|
569 * Brace expansion:: a@{foo,bar@}b expands to afoob abarb. |
|
3172
|
570 * KPSE_DOT expansion:: . is replaced with $KPSE_DOT if it is defined. |
|
2999
|
571 * Subdirectory expansion:: a// and a//b recursively expand to subdirs. |
|
|
572 @end menu |
|
|
573 |
|
|
574 |
|
|
575 @node Default expansion |
|
|
576 @subsection Default expansion |
|
|
577 |
|
|
578 @kindex :: @r{expansion} |
|
|
579 @cindex doubled colons |
|
|
580 @cindex leading colons |
|
|
581 @cindex trailing colons |
|
|
582 @cindex extra colons |
|
|
583 @cindex default expansion |
|
|
584 @cindex expansion, default |
|
|
585 |
|
|
586 If the highest-priority search path (@pxref{Path sources}) contains an |
|
|
587 @dfn{extra colon} (i.e., leading, trailing, or doubled), Kpathsea |
|
|
588 inserts at that point the next-highest-priority search path that is |
|
|
589 defined. If that inserted path has an extra colon, the same happens |
|
|
590 with the next-highest. (An extra colon in the compile-time default |
|
|
591 value has unpredictable results, so installers beware.) |
|
|
592 |
|
|
593 For example, given an environment variable setting |
|
|
594 |
|
|
595 @example |
|
|
596 setenv TEXINPUTS /home/karl: |
|
|
597 @end example |
|
|
598 |
|
|
599 @noindent and a @code{TEXINPUTS} value from @file{texmf.cnf} of |
|
|
600 |
|
|
601 @example |
|
|
602 .:$TEXMF//tex |
|
|
603 @end example |
|
|
604 |
|
|
605 @noindent then the final value used for searching will be: |
|
|
606 |
|
|
607 @example |
|
|
608 /home/karl:.:$TEXMF//tex |
|
|
609 @end example |
|
|
610 |
|
|
611 Since Kpathsea looks for multiple configuration files, it would be |
|
|
612 natural to expect that (for example) an extra colon in |
|
|
613 @file{./texmf.cnf} would expand to the path in @file{$TEXMF/texmf.cnf}. |
|
|
614 Or, with Dvips' configuration files, that an extra colon in |
|
|
615 @file{config.$PRINTER} would expand to the path in @file{config.ps}. |
|
|
616 This doesn't happen. It's not clear this would be desirable in all |
|
|
617 cases, and trying to devise a way to specify the path to which the extra |
|
|
618 colon should expand seemed truly baroque. |
|
|
619 @cindex Bach, Johann Sebastian |
|
|
620 |
|
|
621 Technicality: Since it would be useless to insert the default value in |
|
|
622 more than one place, Kpathsea changes only one extra @samp{:} and leaves |
|
3172
|
623 any others in place (they will eventually be ignored). Kpathsea checks |
|
|
624 first for a leading @samp{:}, then a trailing @samp{:}, then a doubled |
|
|
625 @samp{:}. |
|
2999
|
626 |
|
|
627 @flindex kdefault.c |
|
|
628 You can trace this by debugging ``paths'' (@pxref{Debugging}). |
|
|
629 Default expansion is implemented in the source file |
|
|
630 @file{kpathsea/kdefault.c}. |
|
|
631 |
|
|
632 |
|
|
633 @node Variable expansion |
|
|
634 @subsection Variable expansion |
|
|
635 |
|
|
636 @kindex $ @r{expansion} |
|
|
637 @cindex environment variables in paths |
|
|
638 @cindex variable expansion |
|
|
639 @cindex expansion, variable |
|
|
640 @flindex texmf.cnf@r{, and variable expansion} |
|
|
641 |
|
|
642 @samp{$foo} or @samp{$@{foo@}} in a path element is replaced by (1) the |
|
|
643 value of an environment variable @samp{foo} (if defined); (2) the value |
|
|
644 of @samp{foo} from @file{texmf.cnf} (if defined); (3) the empty string. |
|
|
645 |
|
|
646 If the character after the @samp{$} is alphanumeric or @samp{_}, the |
|
|
647 variable name consists of all consecutive such characters. If the |
|
|
648 character after the @samp{$} is a @samp{@{}, the variable name consists |
|
3172
|
649 of everything up to the next @samp{@}} (braces may not be nested around |
|
|
650 variable names). Otherwise, Kpathsea gives a warning and ignores the |
|
|
651 @samp{$} and its following character. |
|
2999
|
652 |
|
|
653 @cindex quoting variable values |
|
|
654 @cindex shell variables |
|
|
655 You must quote the @t{$}'s and braces as necessary for your shell. |
|
|
656 @emph{Shell} variable values cannot be seen by Kpathsea, i.e., ones |
|
|
657 defined by @code{set} in C shells and without @code{export} in Bourne |
|
|
658 shells. |
|
|
659 |
|
|
660 For example, given |
|
|
661 @example |
|
|
662 setenv tex /home/texmf |
|
|
663 setenv TEXINPUTS .:$tex:$@{tex@}prev |
|
|
664 @end example |
|
|
665 @noindent the final @code{TEXINPUTS} path is the three directories: |
|
|
666 @example |
|
|
667 .:/home/texmf:/home/texmfprev |
|
|
668 @end example |
|
|
669 |
|
|
670 The @samp{.@var{progname}} suffix on variables and |
|
|
671 @samp{_@var{progname}} on environment variable names are not implemented |
|
|
672 for general variable expansions. These are only recognized when search |
|
|
673 paths are initialized (@pxref{Path sources}). |
|
|
674 |
|
|
675 @flindex variable.c |
|
|
676 Variable expansion is implemented in the source file |
|
|
677 @file{kpathsea/variable.c}. |
|
|
678 |
|
|
679 |
|
|
680 @node Tilde expansion |
|
|
681 @subsection Tilde expansion |
|
|
682 |
|
|
683 @kindex ~ @r{expansion} |
|
|
684 @cindex home directories in paths |
|
|
685 @cindex tilde expansion |
|
|
686 @cindex expansion, tilde |
|
|
687 |
|
|
688 @vindex HOME@r{, as ~ expansion} |
|
|
689 A leading @samp{~} in a path element is replaced by the value of the |
|
|
690 environment variable @code{HOME}, or @file{.} if @code{HOME} is not set. |
|
|
691 |
|
|
692 A leading @samp{~@var{user}} in a path element is replaced by |
|
|
693 @var{user}'s home directory from the system @file{passwd} database. |
|
|
694 |
|
|
695 For example, |
|
|
696 @example |
|
|
697 setenv TEXINPUTS ~/mymacros: |
|
|
698 @end example |
|
|
699 |
|
|
700 @noindent will prepend a directory @file{mymacros} in your home |
|
|
701 directory to the default path. |
|
|
702 |
|
|
703 @cindex @t{root} user |
|
|
704 @cindex trailing @samp{/} in home directory |
|
|
705 @kindex /@r{, trailing in home directory} |
|
|
706 As a special case, if a home directory ends in @samp{/}, the trailing |
|
|
707 slash is dropped, to avoid inadvertently creating a @samp{//} construct |
|
|
708 in the path. For example, if the home directory of the user @samp{root} |
|
|
709 is @samp{/}, the path element @samp{~root/mymacros} expands to just |
|
|
710 @samp{/mymacros}, not @samp{//mymacros}. |
|
|
711 |
|
|
712 @flindex tilde.c |
|
|
713 Tilde expansion is implemented in the source file @file{kpathsea/tilde.c}. |
|
|
714 |
|
|
715 |
|
|
716 @node Brace expansion |
|
|
717 @subsection Brace expansion |
|
|
718 |
|
|
719 @kindex @{ @r{expansion} |
|
|
720 @cindex brace expansion |
|
|
721 |
|
3172
|
722 @samp{x@{@var{a}:@var{b}@}y} expands to @samp{x@var{a}y:x@var{b}y}. |
|
2999
|
723 For example: |
|
|
724 |
|
|
725 @example |
|
3172
|
726 foo/@{1:2@}/baz |
|
2999
|
727 @end example |
|
|
728 |
|
3172
|
729 @noindent expands to @samp{foo/1/baz:foo/2/baz}. @samp{:} is the path |
|
2999
|
730 separator on the current system; e.g., on a DOS system, it's @samp{;}. |
|
|
731 |
|
3172
|
732 Braces can be nested; for example, @samp{x@{A:B@{1:2@}@}y} expands to |
|
|
733 @samp{xAy:xB1y:xB2y}. |
|
|
734 |
|
|
735 Multiple non-nested braces are expanded from right to left; for example, |
|
|
736 @samp{x@{A:B@}@{1:2@}y} expands to @samp{x@{A:B@}1y:x@{A:B@}2y}, which |
|
|
737 expands to @samp{xA1y:xB1y:xA2y:xB2:y}. |
|
2999
|
738 |
|
|
739 @cindex multiple @TeX{} hierarchies |
|
|
740 This feature can be used to implement multiple @TeX{} hierarchies, by |
|
|
741 assigning a brace list to @code{$TEXMF}, as mentioned in |
|
3172
|
742 @file{texmf.in}. |
|
|
743 |
|
|
744 In old versions of the library you had to use a comma. While this usage |
|
|
745 is deprecated, it is still supported for backwards compatibility with |
|
|
746 old configurations. The last example could have been written |
|
|
747 @samp{x@{A,B@}@{1,2@}y}. |
|
2999
|
748 |
|
|
749 @flindex expand.c |
|
|
750 Brace expansion is implemented in the source file |
|
3172
|
751 @file{kpathsea/expand.c}. It is a modification of the Bash sources, and |
|
|
752 is thus covered by the GNU General Public License, rather than the |
|
|
753 Library General Public License that covers the rest of Kpathsea. |
|
|
754 |
|
|
755 |
|
|
756 @node KPSE_DOT expansion |
|
|
757 @subsection @code{KPSE_DOT} expansion |
|
|
758 |
|
|
759 @kindex KPSE_DOT @r{expansion} |
|
|
760 |
|
|
761 When @code{KPSE_DOT} is defined in the environment, it names a directory |
|
|
762 that should be considered the current directory for the purpose of |
|
|
763 looking up files in the search paths. This feature is needed by the |
|
|
764 @samp{mktex@dots{}} scripts @ref{mktex scripts}, because these |
|
|
765 change the working directory. You should not ever define it yourself. |
|
2999
|
766 |
|
|
767 |
|
|
768 @node Subdirectory expansion |
|
|
769 @subsection Subdirectory expansion |
|
|
770 |
|
|
771 @kindex // |
|
|
772 @cindex subdirectory searching |
|
|
773 @cindex expansion, subdirectory |
|
|
774 |
|
|
775 @cindex alphabetical order, not |
|
|
776 Two or more consecutive slashes in a path element following a directory |
|
|
777 @var{d} is replaced by all subdirectories of @var{d}: first those |
|
|
778 subdirectories directly under @var{d}, then the subsubdirectories under |
|
|
779 those, and so on. At each level, the order in which the directories are |
|
|
780 searched is unspecified. (It's ``directory order'', and definitely not |
|
|
781 alphabetical.) |
|
|
782 |
|
|
783 If you specify any filename components after the @samp{//}, only |
|
|
784 subdirectories which match those components are included. For example, |
|
|
785 @samp{/a//b} would expand into directories @file{/a/1/b}, @file{/a/2/b}, |
|
|
786 @file{/a/1/1/b}, and so on, but not @file{/a/b/c} or @file{/a/1}. |
|
|
787 |
|
|
788 You can include multiple @samp{//} constructs in the path. |
|
|
789 |
|
|
790 @samp{//} at the beginning of a path is ignored; you didn't really want |
|
|
791 to search every directory on the system, did you? |
|
|
792 |
|
|
793 @cindex trick for detecting leaf directories |
|
|
794 @cindex leaf directory trick |
|
|
795 @cindex Farwell, Matthew |
|
|
796 @cindex MacKenzie, David |
|
|
797 I should mention one related implementation trick, which I took from GNU |
|
|
798 find. Matthew Farwell suggested it, and David MacKenzie implemented it. |
|
|
799 |
|
|
800 @vindex st_nlink |
|
|
801 The trick is that in every real Unix implementation (as opposed to the |
|
|
802 POSIX specification), a directory which contains no subdirectories will |
|
|
803 have exactly two links (namely, one for @file{.} and one for @file{..}). |
|
|
804 That is to say, the @code{st_nlink} field in the @samp{stat} structure |
|
|
805 will be two. Thus, we don't have to stat everything in the bottom-level |
|
|
806 (leaf) directories---we can just check @code{st_nlink}, notice it's two, |
|
|
807 and do no more work. |
|
|
808 |
|
|
809 But if you have a directory that contains a single subdirectory and 500 |
|
|
810 regular files, @code{st_nlink} will be 3, and Kpathsea has to stat every |
|
|
811 one of those 501 entries. Therein lies slowness. |
|
|
812 |
|
|
813 @vindex UNIX_ST_LINK |
|
|
814 You can disable the trick by undefining @code{UNIX_ST_LINK} in |
|
|
815 @file{kpathsea/config.h}. (It is undefined by default except under Unix.) |
|
|
816 |
|
|
817 @flindex elt-dirs.c |
|
|
818 Unfortunately, in some cases files in leaf directories are |
|
|
819 @code{stat}'d: if the path specification is, say, |
|
|
820 @samp{$TEXMF/fonts//pk//}, then files in a subdirectory |
|
|
821 @samp{@dots{}/pk}, even if it is a leaf, are checked. The reason cannot |
|
|
822 be explained without reference to the implementation, so read |
|
|
823 @file{kpathsea/elt-dirs.c} (search for @samp{may descend}) if you are |
|
|
824 curious. And if you can find a way to @emph{solve} the problem, please |
|
|
825 let me know. |
|
|
826 |
|
|
827 @flindex elt-dirs.c |
|
|
828 Subdirectory expansion is implemented in the source file |
|
|
829 @file{kpathsea/elt-dirs.c}. |
|
|
830 |
|
|
831 |
|
|
832 @node Filename database |
|
|
833 @section Filename database (@code{ls-R}) |
|
|
834 |
|
|
835 @cindex filename database |
|
|
836 @cindex database, for filenames |
|
|
837 @cindex externally-built filename database |
|
|
838 |
|
|
839 Kpathsea goes to some lengths to minimize disk accesses for searches |
|
|
840 (@pxref{Subdirectory expansion}). Nevertheless, at installations with |
|
|
841 enough directories, searching each possible directory for a given file |
|
|
842 can take an excessively long time (depending on the speed of the disk, |
|
|
843 whether it's NFS-mounted, how patient you are, etc.). |
|
|
844 |
|
|
845 In practice, a font tree containing the standard PostScript and PCL |
|
|
846 fonts is large enough for searching to be noticeably slow on typical |
|
|
847 systems these days. Therefore, Kpathsea can use an externally-built |
|
|
848 ``database'' file named @file{ls-R} that maps files to directories, thus |
|
|
849 avoiding the need to exhaustively search the disk. |
|
|
850 |
|
|
851 A second database file @file{aliases} allows you to give additional |
|
|
852 names to the files listed in @file{ls-R}. This can be helpful to adapt |
|
|
853 to ``8.3'' filename conventions in source files. |
|
|
854 |
|
|
855 The @file{ls-R} and @file{aliases} features are implemented in the |
|
|
856 source file @file{kpathsea/db.c}. |
|
|
857 |
|
|
858 @menu |
|
|
859 * ls-R:: The main filename database. |
|
|
860 * Filename aliases:: Aliases for those names. |
|
|
861 * Database format:: Syntax details of the database file. |
|
|
862 @end menu |
|
|
863 |
|
|
864 |
|
|
865 @node ls-R |
|
|
866 @subsection @file{ls-R} |
|
|
867 |
|
|
868 @flindex ls-R @r{database file} |
|
|
869 @vindex TEXMFDBS |
|
|
870 |
|
|
871 As mentioned above, you must name the main filename database |
|
|
872 @file{ls-R}. You can put one at the root of each @TeX{} installation |
|
|
873 hierarchy you wish to search (@code{$TEXMF} by default); most sites have |
|
|
874 only one hierarchy. Kpathsea looks for @file{ls-R} files along the |
|
|
875 @code{TEXMFDBS} path, so that should presumably match the list of |
|
|
876 hierarchies. |
|
|
877 |
|
|
878 The recommended way to create and maintain @samp{ls-R} is to run the |
|
3172
|
879 @code{mktexlsr} script, which is installed in @samp{$(bindir)} |
|
2999
|
880 (@file{/usr/local/bin} by default). That script goes to some trouble to |
|
|
881 follow symbolic links as necessary, etc. It's also invoked by the |
|
3172
|
882 distributed @samp{mktex@dots{}} scripts. |
|
2999
|
883 |
|
|
884 @flindex ls-R@r{, simplest build} |
|
|
885 At its simplest, though, you can build @file{ls-R} with the command |
|
|
886 @example |
|
|
887 cd @var{/your/texmf/root} && ls -LAR ./ >ls-R |
|
|
888 @end example |
|
|
889 |
|
|
890 @noindent |
|
|
891 @opindex --color=tty |
|
|
892 @flindex /etc/profile @r{and aliases} |
|
|
893 presuming your @code{ls} produces the right output format (see the |
|
|
894 section below). GNU @code{ls}, for example, outputs in this format. |
|
|
895 Also presuming your @code{ls} hasn't been aliased in a system file |
|
|
896 (e.g., @file{/etc/profile}) to something problematic, e.g., @samp{ls |
|
|
897 --color=tty}. In that case, you will have to disable the alias before |
|
|
898 generating @file{ls-R}. For the precise definition of the file format, |
|
3172
|
899 see @ref{Database format}. |
|
2999
|
900 |
|
|
901 Regardless of whether you use the supplied script or your own, you will |
|
|
902 almost certainly want to invoke it via @code{cron}, so when you make |
|
|
903 changes in the installed files (say if you install a new La@TeX{} |
|
|
904 package), @file{ls-R} will be automatically updated. |
|
|
905 |
|
|
906 @opindex -A @r{option to @code{ls}} |
|
|
907 @cindex dot files |
|
|
908 @flindex . @r{files} |
|
|
909 @flindex . @r{directories, ignored} |
|
|
910 @flindex .tex @r{file, included in @file{ls-R}} |
|
|
911 The @samp{-A} option to @code{ls} includes files beginning with @samp{.} |
|
|
912 (except for @file{.} and @file{..}), such as the file @file{.tex} |
|
|
913 included with the La@TeX{} tools package. (On the other hand, |
|
|
914 @emph{directories} whose names begin with @samp{.} are always ignored.) |
|
|
915 |
|
|
916 @cindex symbolic links, and @file{ls-R} |
|
|
917 @opindex -L @r{option to @code{ls}} |
|
|
918 If your system does not support symbolic links, omit the @samp{-L}. |
|
|
919 |
|
|
920 @cindex automounter, and @file{ls-R} |
|
|
921 @cindex NFS and @file{ls-R} |
|
|
922 @code{ls -LAR @var{/your/texmf/root}} will also work. But using |
|
|
923 @samp{./} avoids embedding absolute pathnames, so the hierarchy can be |
|
|
924 easily transported. It also avoids possible trouble with automounters |
|
|
925 or other network filesystem conventions. |
|
|
926 |
|
|
927 @cindex warning about unusable @file{ls-R} |
|
|
928 @cindex unusable @file{ls-R} warning |
|
|
929 Kpathsea warns you if it finds an @file{ls-R} file, but the file does |
|
|
930 not contain any usable entries. The usual culprit is running plain |
|
|
931 @samp{ls -R} instead of @samp{ls -LR ./} or @samp{ls -R |
|
|
932 @var{/your/texmf/root}}. Another possibility is some system directory |
|
|
933 name starting with a @samp{.} (perhaps if you are using AFS); Kpathsea |
|
|
934 ignores everything under such directories. |
|
|
935 |
|
|
936 @kindex !! @r{in path specifications} |
|
|
937 @cindex disk searching, avoiding |
|
|
938 Because the database may be out-of-date for a particular run, if a file |
|
|
939 is not found in the database, by default Kpathsea goes ahead and |
|
|
940 searches the disk. If a particular path element begins with @samp{!!}, |
|
|
941 however, @emph{only} the database will be searched for that element, |
|
|
942 never the disk. If the database does not exist, nothing will be |
|
|
943 searched. Because this can surprise users (``I see the font |
|
|
944 @file{foo.tfm} when I do an @code{ls}; why can't Dvips find it?''), it |
|
|
945 is not in any of the default search paths. |
|
|
946 |
|
|
947 |
|
|
948 @node Filename aliases |
|
|
949 @subsection Filename aliases |
|
|
950 |
|
|
951 @cindex filename aliases |
|
|
952 @cindex aliases, for filenames |
|
|
953 |
|
|
954 In some circumstances, you may wish to find a file under several names. |
|
|
955 For example, suppose a @TeX{} document was created using a DOS system |
|
|
956 and tries to read @file{longtabl.sty}. But now it's being run on a Unix |
|
|
957 system, and the file has its original name, @file{longtable.sty}. The |
|
|
958 file won't be found. You need to give the actual file |
|
|
959 @file{longtable.sty} an alias @samp{longtabl.sty}. |
|
|
960 |
|
|
961 @c As another example, suppose you are creating a @TeX{} distribution on a |
|
|
962 @c CD-ROM or a DOS system; then the file @file{mf.base} gets stored as |
|
|
963 @c @file{mf.bas}. But Metafont on Unix wants to find @file{mf.base}. Here |
|
|
964 @c you need to give the actual file @file{mf.bas} an alias @samp{mf.base}. |
|
|
965 |
|
|
966 You can handle this by creating a file @file{aliases} as a companion to |
|
|
967 the @file{ls-R} for the hierarchy containing the file in question. (You |
|
|
968 must have an @file{ls-R} for the alias feature to work.) |
|
|
969 |
|
|
970 The format of @file{aliases} is simple: two whitespace-separated words |
|
|
971 per line; the first is the real name @file{longtable.sty}, and second is |
|
|
972 the alias (@file{longtabl.sty}). These must be base filenames, with no |
|
|
973 directory components. @file{longtable.sty} must be in the sibling |
|
|
974 @file{ls-R}. |
|
|
975 |
|
|
976 Also, blank lines and lines starting with @samp{%} or @samp{#} are |
|
|
977 ignored in @file{aliases}, to allow for comments. |
|
|
978 |
|
|
979 If a real file @file{longtabl.sty} exists, it is used regardless of any |
|
|
980 aliases. |
|
|
981 |
|
|
982 |
|
|
983 @node Database format |
|
|
984 @subsection Database format |
|
|
985 |
|
|
986 @cindex format of external database |
|
|
987 @cindex database, format of |
|
|
988 |
|
|
989 The ``database'' read by Kpathsea is a line-oriented file of plain |
|
|
990 text. The format is that generated by GNU (and most other) @code{ls} |
|
|
991 programs given the @samp{-R} option, as follows. |
|
|
992 |
|
|
993 @itemize @bullet |
|
|
994 @item |
|
|
995 Blank lines are ignored. |
|
|
996 |
|
|
997 @item |
|
|
998 If a line begins with @samp{/} or @samp{./} or @samp{../} and ends with |
|
|
999 a colon, it's the name of a directory. (@samp{../} lines aren't useful, |
|
|
1000 however, and should not be generated.) |
|
|
1001 |
|
|
1002 @item |
|
|
1003 All other lines define entries in the most recently seen directory. |
|
|
1004 @t{/}'s in such lines will produce possibly-strange results. |
|
|
1005 |
|
|
1006 @item |
|
|
1007 Files with no preceding directory line are ignored. |
|
|
1008 @end itemize |
|
|
1009 |
|
|
1010 For example, here's the first few lines of @file{ls-R} (which totals |
|
|
1011 about 30K bytes) on my system: |
|
|
1012 |
|
|
1013 @example |
|
|
1014 bibtex |
|
|
1015 dvips |
|
|
1016 fonts |
|
|
1017 ls-R |
|
|
1018 metafont |
|
|
1019 metapost |
|
|
1020 tex |
|
|
1021 web2c |
|
|
1022 |
|
|
1023 ./bibtex: |
|
|
1024 bib |
|
|
1025 bst |
|
|
1026 doc |
|
|
1027 |
|
|
1028 ./bibtex/bib: |
|
|
1029 asi.bib |
|
|
1030 btxdoc.bib |
|
|
1031 @dots{} |
|
|
1032 @end example |
|
|
1033 |
|
|
1034 |
|
|
1035 @node Invoking kpsewhich |
|
|
1036 @section @code{kpsewhich}: Standalone path searching |
|
|
1037 |
|
|
1038 @pindex kpsewhich |
|
|
1039 @cindex path searching, standalone |
|
|
1040 @cindex standalone path searching |
|
|
1041 |
|
|
1042 The Kpsewhich program exercises the path searching functionality |
|
|
1043 independent of any particular application. This can also be useful as a |
|
|
1044 sort of @code{find} program to locate files in your @TeX{} hierarchies, |
|
|
1045 perhaps in administrative scripts. It is used heavily in the |
|
3172
|
1046 distributed @samp{mktex@dots{}} scripts. |
|
2999
|
1047 |
|
|
1048 Synopsis: |
|
|
1049 @example |
|
|
1050 kpsewhich @var{option}@dots{} @var{filename}@dots{} |
|
|
1051 @end example |
|
|
1052 |
|
|
1053 The options and filename(s) to look up can be intermixed. |
|
|
1054 Options can start with either @samp{-} or @samp{--}, and any unambiguous |
|
|
1055 abbreviation is accepted. |
|
|
1056 |
|
|
1057 @menu |
|
|
1058 * Path searching options:: Changing the mode, resolution, etc. |
|
|
1059 * Auxiliary tasks:: Path and variable expansion. |
|
|
1060 * Standard options:: --help and --version. |
|
|
1061 @end menu |
|
|
1062 |
|
|
1063 |
|
|
1064 @node Path searching options |
|
|
1065 @subsection Path searching options |
|
|
1066 |
|
|
1067 @cindex path searching options |
|
|
1068 |
|
|
1069 Kpsewhich looks up each non-option argument on the command line as a |
|
|
1070 filename, and returns the first file found. There is no option to |
|
|
1071 return all the files with a particular name (you can run the Unix |
|
|
1072 @samp{find} utility for that, @pxref{Invoking find,,, findutils, GNU |
|
|
1073 find utilities}). |
|
|
1074 |
|
|
1075 Various options alter the path searching behavior: |
|
|
1076 |
|
|
1077 @table @samp |
|
|
1078 @item --dpi=@var{num} |
|
|
1079 @opindex --dpi=@var{num} |
|
|
1080 @opindex -D @var{num} |
|
|
1081 @cindex resolution, setting |
|
|
1082 Set the resolution to @var{num}; this only affects @samp{gf} and |
|
|
1083 @samp{pk} lookups. @samp{-D} is a synonym, for compatibility with |
|
|
1084 Dvips. Default is 600. |
|
|
1085 |
|
|
1086 @item --format=@var{name} |
|
|
1087 @opindex --format=@var{name} |
|
|
1088 Set the format for lookup to @var{name}. By default, the format is |
|
3172
|
1089 guessed from the filename, with @samp{tex} being used if nothing else |
|
|
1090 fits. The recognized filename extensions (including any leading |
|
|
1091 @samp{.}) are also allowable @var{name}s. |
|
2999
|
1092 |
|
3172
|
1093 All formats also have a name, which is the only way to specify formats |
|
|
1094 with no associated suffix. For example, for Dvips configuration files |
|
|
1095 you can use @samp{--format="dvips config"}. (The quotes are for the |
|
|
1096 sake of the shell.) |
|
2999
|
1097 |
|
3172
|
1098 Here's the current list of recognized names and the associated suffixes. |
|
2999
|
1099 @xref{Supported file formats}, for more information on each of these. |
|
|
1100 @example |
|
3172
|
1101 gf: gf |
|
|
1102 pk: pk |
|
|
1103 bitmap font |
|
|
1104 afm: .afm |
|
|
1105 base: .base |
|
|
1106 bib: .bib |
|
|
1107 bst: .bst |
|
|
1108 cnf: .cnf |
|
|
1109 ls-R: ls-R |
|
|
1110 fmt: .fmt |
|
|
1111 map: .map |
|
|
1112 mem: .mem |
|
|
1113 mf: .mf |
|
|
1114 mfpool: .pool |
|
|
1115 mft: .mft |
|
|
1116 mp: .mp |
|
|
1117 mppool: .pool |
|
|
1118 MetaPost support |
|
|
1119 ocp: .ocp |
|
|
1120 ofm: .ofm .tfm |
|
|
1121 opl: .opl |
|
|
1122 otp: .otp |
|
|
1123 ovf: .ovf |
|
|
1124 ovp: .ovp |
|
|
1125 graphic/figure: .eps .epsi |
|
|
1126 tex: .tex |
|
|
1127 TeX system documentation |
|
|
1128 texpool: .pool |
|
|
1129 TeX system sources |
|
|
1130 PostScript header/font: .pro |
|
|
1131 Troff fonts |
|
|
1132 tfm: .tfm |
|
|
1133 type1 fonts: .pfa .pfb |
|
|
1134 vf: .vf |
|
|
1135 dvips config |
|
|
1136 ist: .ist |
|
|
1137 truetype fonts: .ttf .ttc |
|
|
1138 type42 fonts |
|
|
1139 web2c files |
|
|
1140 other text files |
|
|
1141 other binary files |
|
2999
|
1142 @end example |
|
|
1143 |
|
|
1144 This option and @samp{--path} are mutually exclusive. |
|
|
1145 |
|
|
1146 @item --interactive |
|
|
1147 @opindex --interactive |
|
|
1148 @cindex interactive query |
|
|
1149 After processing the command line, read additional filenames to look up |
|
|
1150 from standard input. |
|
|
1151 |
|
3172
|
1152 @item -mktex=@var{filetype} |
|
|
1153 @itemx -no-mktex=@var{filetype} |
|
|
1154 @opindex -mktex=@var{filetype} |
|
|
1155 @opindex -no-mktex=@var{filetype} |
|
|
1156 Turn on or off the @samp{mktex} script associated with @var{filetype}. |
|
2999
|
1157 The only values that make sense for @var{filetype} are @samp{pk}, |
|
|
1158 @samp{mf}, @samp{tex}, and @samp{tfm}. By default, all are off in |
|
3172
|
1159 Kpsewhich. @xref{mktex scripts}. |
|
2999
|
1160 |
|
|
1161 @item --mode=@var{string} |
|
|
1162 @opindex --mode=@var{string} |
|
|
1163 Set the mode name to @var{string}; this also only affects @samp{gf} and |
|
3172
|
1164 @samp{pk} lookups. No default: any mode will be found. @xref{mktex |
|
2999
|
1165 script arguments}. |
|
|
1166 |
|
|
1167 @item --must-exist |
|
|
1168 @opindex --must-exist |
|
|
1169 Do everything possible to find the files, notably including searching |
|
|
1170 the disk. By default, only the @file{ls-R} database is checked, in the |
|
|
1171 interest of efficiency. |
|
|
1172 |
|
|
1173 @item --path=@var{string} |
|
|
1174 @opindex --path=@var{string} |
|
|
1175 Search along the path @var{string} (colon-separated as usual), instead |
|
|
1176 of guessing the search path from the filename. @samp{//} and all the |
|
|
1177 usual expansions are supported (@pxref{Path expansion}). This option |
|
|
1178 and @samp{--format} are mutually exclusive. To output the complete |
|
|
1179 directory expansion of a path, instead of doing a one-shot lookup, see |
|
3172
|
1180 @samp{--expand-path} in the following section. |
|
2999
|
1181 |
|
|
1182 @item --progname=@var{name} |
|
|
1183 @opindex --progname=@var{name} |
|
|
1184 Set the program name to @var{name}; default is @samp{kpsewhich}. This |
|
|
1185 can affect the search paths via the @samp{.@var{prognam}} feature in |
|
|
1186 configuration files (@pxref{Config files}). |
|
|
1187 @end table |
|
|
1188 |
|
|
1189 |
|
|
1190 @node Auxiliary tasks |
|
|
1191 @subsection Auxiliary tasks |
|
|
1192 |
|
|
1193 @cindex auxiliary tasks |
|
|
1194 |
|
|
1195 Kpsewhich provides some additional features not strictly related to path |
|
|
1196 lookup: |
|
|
1197 |
|
|
1198 @itemize @bullet |
|
|
1199 @item |
|
|
1200 @opindex --debug=@var{num} |
|
|
1201 @samp{--debug=@var{num}} sets the debugging options to @var{num}. |
|
|
1202 @xref{Debugging}. |
|
|
1203 |
|
|
1204 @item |
|
3172
|
1205 @opindex --expand-braces=@var{string} |
|
|
1206 @samp{--expand-braces=@var{string}} outputs the variable and brace |
|
|
1207 expansion of @var{string}. @xref{Path expansion}. |
|
|
1208 |
|
|
1209 @item |
|
2999
|
1210 @opindex --expand-var=@var{string} |
|
|
1211 @samp{--expand-var=@var{string}} outputs the variable expansion of |
|
3172
|
1212 @var{string}. For example, the @samp{mktex@dots{}} scripts run |
|
2999
|
1213 @samp{kpsewhich --expand-var='$TEXMF'} to find the root of the @TeX{} system |
|
|
1214 hierarchy. @xref{Path expansion}. |
|
|
1215 |
|
|
1216 @item |
|
|
1217 @opindex --expand-path=@var{string} |
|
|
1218 @samp{--expand-path=@var{string}} outputs the complete expansion of |
|
|
1219 @var{string} as a colon-separated path. This is useful to construct a |
|
|
1220 search path for a program that doesn't accept recursive subdirectory |
|
3172
|
1221 specifications. |
|
2999
|
1222 |
|
|
1223 For one-shot uses of an arbitrary (not built in to Kpathsea) path, see |
|
|
1224 @samp{--path} in the previous section. |
|
|
1225 |
|
|
1226 @item |
|
|
1227 @opindex --show-path=@var{name} |
|
|
1228 @samp{--show-path=@var{name}} shows the path that would be used for file |
|
|
1229 lookups of file type @var{name}. Either a filename extension |
|
|
1230 (@samp{pk}, @samp{.vf}, etc.) or an integer can be used, just as with |
|
|
1231 @samp{--format}, described in the previous section. |
|
|
1232 @end itemize |
|
|
1233 |
|
|
1234 |
|
|
1235 @node Standard options |
|
|
1236 @subsection Standard options |
|
|
1237 |
|
|
1238 @cindex standard options |
|
|
1239 |
|
|
1240 Kpsewhich accepts the standard GNU options: |
|
|
1241 |
|
|
1242 @itemize @bullet |
|
|
1243 @item |
|
|
1244 @opindex --help |
|
|
1245 @samp{--help} prints a help message on standard output and exits. |
|
|
1246 |
|
|
1247 @item |
|
|
1248 @opindex --version |
|
|
1249 @samp{--version} prints the Kpathsea version number and exits. |
|
|
1250 @end itemize |
|
|
1251 |
|
|
1252 |
|
|
1253 @node TeX support |
|
|
1254 @chapter @TeX{} support |
|
|
1255 |
|
|
1256 @cindex @TeX{} support |
|
|
1257 |
|
|
1258 Although the basic features in Kpathsea can be used for any type of path |
|
|
1259 searching, it came about (like all libraries) with a specific |
|
|
1260 application in mind: I wrote Kpathsea specifically for @TeX{} system |
|
|
1261 programs. I had been struggling with the programs I was using (Dvips, |
|
|
1262 Xdvi, and @TeX{} itself) having slightly different notions of how to |
|
|
1263 specify paths; and debugging was painful, since no code was shared. |
|
|
1264 |
|
|
1265 Therefore, Kpathsea provides some @TeX{}-specific formats and features. |
|
|
1266 Indeed, many of the supposedly generic path searching features were |
|
|
1267 provided because they seemed useful in that con@TeX{}t (font lookup, |
|
|
1268 particularly). |
|
|
1269 |
|
|
1270 Kpathsea provides a standard way to search for files of any of the |
|
|
1271 supported file types; glyph fonts are a bit different than all the rest. |
|
|
1272 Searches are based solely on filenames, not file contents---if a GF |
|
|
1273 file is named @file{cmr10.600pk}, it will be found as a PK file. |
|
|
1274 |
|
|
1275 @menu |
|
|
1276 * Supported file formats:: File types Kpathsea knows about. |
|
|
1277 * File lookup:: Searching for most kinds of files. |
|
|
1278 * Glyph lookup:: Searching for bitmap fonts. |
|
|
1279 * Suppressing warnings:: Avoiding warnings via TEX_HUSH. |
|
|
1280 @end menu |
|
|
1281 |
|
|
1282 |
|
|
1283 @node Supported file formats |
|
|
1284 @section Supported file formats |
|
|
1285 |
|
|
1286 @cindex supported file formats |
|
|
1287 @cindex file formats, supported |
|
|
1288 |
|
|
1289 @cindex environment variables for @TeX{} |
|
|
1290 @cindex @TeX{} environment variables |
|
|
1291 |
|
|
1292 Kpathsea has support for a number of file types. Each file type has a |
|
|
1293 list of environment and config file variables that are checked to define |
|
|
1294 the search path, and most have a default suffix that plays a role in |
|
|
1295 finding files (see the next section). Some also define additional |
|
|
1296 suffixes, and/or a program to be run to create missing files on the fly. |
|
|
1297 |
|
|
1298 @cindex program-varying paths |
|
|
1299 Since environment variables containing periods, such as |
|
|
1300 @samp{TEXINPUTS.latex}, are not allowed on some systems, Kpathsea looks |
|
|
1301 for environment variables with an underscore, e.g., |
|
|
1302 @samp{TEXINPUTS_latex} (@pxref{Config files}). |
|
|
1303 |
|
|
1304 The following table lists the above information. |
|
|
1305 |
|
|
1306 @table @samp |
|
3172
|
1307 @item afm |
|
2999
|
1308 @flindex .afm |
|
|
1309 @vindex AFMFONTS |
|
|
1310 (Adobe font metrics, @pxref{Metric files,,, dvips, Dvips}) |
|
3172
|
1311 @code{AFMFONTS}; |
|
|
1312 suffix @samp{.afm}. |
|
2999
|
1313 |
|
3172
|
1314 @item base |
|
2999
|
1315 @flindex .base |
|
|
1316 @vindex MFBASES |
|
|
1317 @vindex TEXMFINI |
|
|
1318 (Metafont memory dump, @pxref{Memory dumps,,, web2c, Web2c}) |
|
3172
|
1319 @code{MFBASES}, @code{TEXMFINI}; |
|
|
1320 suffix @samp{.base}. |
|
2999
|
1321 |
|
3172
|
1322 @item bib |
|
2999
|
1323 @flindex .bib |
|
|
1324 @vindex BIBINPUTS |
|
|
1325 @vindex TEXBIB |
|
|
1326 (Bib@TeX{} bibliography source, @pxref{bibtex invocation,,, web2c, Web2c}) |
|
3172
|
1327 @code{BIBINPUTS}, @code{TEXBIB}; |
|
|
1328 suffix @samp{.bib}. |
|
2999
|
1329 |
|
3172
|
1330 @item bst |
|
2999
|
1331 @flindex .bst |
|
|
1332 @vindex BSTINPUTS |
|
|
1333 (Bib@TeX{} style file, @pxref{Basic BibTeX style files,, Basic Bib@TeX{} |
|
|
1334 style files, web2c, Web2c}) |
|
3172
|
1335 @code{BSTINPUTS}; |
|
|
1336 suffix @samp{.bst}. |
|
2999
|
1337 |
|
3172
|
1338 @item cnf |
|
2999
|
1339 @flindex .cnf |
|
|
1340 @vindex TEXMFCNF |
|
|
1341 (Runtime configuration files, @pxref{Config files}) |
|
3172
|
1342 @code{TEXMFCNF}; |
|
|
1343 suffix @samp{.cnf}. |
|
|
1344 |
|
|
1345 @item dvips config |
|
|
1346 @vindex TEXCONFIG |
|
|
1347 @flindex config.ps@r{, search path for} |
|
|
1348 (Dvips @samp{config.*} files, such as @file{config.ps}, @pxref{Config |
|
|
1349 files,,, dvips, Dvips}) |
|
|
1350 @code{TEXCONFIG}. |
|
|
1351 |
|
|
1352 @item fmt |
|
|
1353 @flindex .fmt |
|
|
1354 @vindex TEXFORMATS |
|
|
1355 @vindex TEXMFINI |
|
|
1356 (@TeX{} memory dump, @pxref{Memory dumps,,, web2c, Web2c}) |
|
|
1357 @code{TEXFORMATS}, @code{TEXMFINI}; |
|
|
1358 suffix @samp{.fmt}. |
|
|
1359 |
|
|
1360 @item gf |
|
|
1361 @flindex gf |
|
|
1362 @vindex GFFONTS |
|
|
1363 @vindex GLYPHFONTS |
|
|
1364 @vindex TEXFONTS |
|
|
1365 (generic font bitmap, @pxref{Glyph files,,, dvips, Dvips}) |
|
|
1366 @code{@var{program}FONTS}, @code{GFFONTS}, @code{GLYPHFONTS}, @code{TEXFONTS}; |
|
|
1367 suffix @samp{gf}. |
|
|
1368 |
|
|
1369 @item graphic/figure |
|
|
1370 @flindex .eps |
|
|
1371 @flindex .epsi |
|
|
1372 @vindex TEXPICTS |
|
|
1373 @vindex TEXINPUTS |
|
|
1374 (Encapsulated PostScript figures, @pxref{PostScript figures,,, dvips, Dvips}) |
|
|
1375 @code{TEXPICTS}, @code{TEXINPUTS}; |
|
|
1376 additional suffixes: @samp{.eps}, @samp{.epsi}. |
|
|
1377 |
|
|
1378 @item ist |
|
|
1379 @flindex .ist |
|
|
1380 @vindex TEXINDEXSTYLE |
|
|
1381 @vindex INDEXSTYLE |
|
|
1382 (makeindex style files) |
|
|
1383 @code{TEXINDEXSTYLE}, @code{INDEXSTYLE}; |
|
|
1384 suffix @samp{.ist}. |
|
2999
|
1385 |
|
|
1386 @item ls-R |
|
|
1387 @flindex ls-R |
|
|
1388 @vindex TEXMFDBS |
|
|
1389 (Filename databases, @pxref{Filename database}) |
|
|
1390 @code{TEXMFDBS}. |
|
|
1391 |
|
3172
|
1392 @item map |
|
2999
|
1393 @flindex .map |
|
|
1394 @vindex TEXFONTMAPS |
|
|
1395 (Fontmaps, @pxref{Fontmap}) |
|
3172
|
1396 @code{TEXFONTMAPS}; |
|
|
1397 suffix @samp{.map}. |
|
2999
|
1398 |
|
3172
|
1399 @item mem |
|
2999
|
1400 @flindex .mem |
|
|
1401 @vindex MPMEMS |
|
|
1402 @vindex TEXMFINI |
|
|
1403 (MetaPost memory dump, @pxref{Memory dumps,,, web2c, Web2c}) |
|
3172
|
1404 @code{MPMEMS}, @code{TEXMFINI}; |
|
|
1405 suffix @samp{.mem}. |
|
2999
|
1406 |
|
3172
|
1407 @item @r{MetaPost support} |
|
|
1408 @vindex MPSUPPORT |
|
|
1409 (MetaPost support files, used by DMP; @pxref{dmp invocation,,, web2c, Web2c}) |
|
|
1410 @code{MPSUPPORT}. |
|
|
1411 |
|
|
1412 @item mf |
|
2999
|
1413 @flindex .mf |
|
|
1414 @vindex MFINPUTS |
|
|
1415 (Metafont source, @pxref{mf invocation,,, web2c, Web2c}) |
|
|
1416 @code{MFINPUTS}; |
|
3172
|
1417 suffix @samp{.mf}; |
|
|
1418 dynamic creation program: @code{mktexmf}. |
|
2999
|
1419 |
|
3172
|
1420 @item mfpool |
|
2999
|
1421 @flindex .pool |
|
|
1422 @vindex MFPOOL |
|
|
1423 (Metafont program strings, @pxref{pooltype invocation,,, web2c, Web2c}) |
|
3172
|
1424 @code{MFPOOL}, @code{TEXMFINI}; |
|
|
1425 suffix @samp{.pool}. |
|
2999
|
1426 |
|
3172
|
1427 @item mft |
|
|
1428 @flindex .mft |
|
|
1429 @vindex MFTINPUTS |
|
|
1430 (@code{MFT} style file, @pxref{mft invocation,,, web2c, Web2c}) |
|
|
1431 @code{MFTINPUTS}; |
|
|
1432 suffix @samp{.mft}. |
|
|
1433 |
|
|
1434 @item mp |
|
2999
|
1435 @flindex .mp |
|
|
1436 @vindex MPINPUTS |
|
|
1437 (MetaPost source, @pxref{mpost invocation,,, web2c, Web2c}) |
|
3172
|
1438 @code{MPINPUTS}; |
|
|
1439 suffix @samp{.mp}. |
|
2999
|
1440 |
|
3172
|
1441 @item mppool |
|
2999
|
1442 @flindex .pool |
|
|
1443 @vindex MPPOOL |
|
|
1444 (MetaPost program strings, @pxref{pooltype invocation,,, web2c, Web2c}) |
|
3172
|
1445 @code{MPPOOL}, @code{TEXMFINI}; |
|
|
1446 suffix @samp{.pool}. |
|
2999
|
1447 |
|
3172
|
1448 @item ocp |
|
2999
|
1449 @flindex .ocp |
|
|
1450 @vindex OCPINPUTS |
|
|
1451 (Omega compiled process files) |
|
|
1452 @code{OCPINPUTS}; @* |
|
3172
|
1453 suffix @samp{.ocp}; |
|
2999
|
1454 dynamic creation program: @code{MakeOmegaOCP}. |
|
|
1455 |
|
3172
|
1456 @item ofm |
|
2999
|
1457 @flindex .ofm |
|
|
1458 @vindex OFMFONTS |
|
|
1459 (Omega font metrics) |
|
|
1460 @code{OFMFONTS}, @code{TEXFONTS}; @* |
|
3172
|
1461 suffixes @samp{.ofm}, @samp{.tfm}; |
|
2999
|
1462 dynamic creation program: @code{MakeOmegaOFM}. |
|
|
1463 |
|
3172
|
1464 @item opl |
|
2999
|
1465 @flindex .opl |
|
|
1466 (Omega property lists) |
|
3172
|
1467 @code{OPLFONTS}, @code{TEXFONTS}; |
|
|
1468 suffix @samp{.opl}. |
|
2999
|
1469 |
|
3172
|
1470 @item otp |
|
2999
|
1471 @flindex .otp |
|
|
1472 @vindex OTPINPUTS |
|
|
1473 (Omega translation process files) |
|
3172
|
1474 @code{OTPINPUTS}; |
|
|
1475 suffix @samp{.otp}. |
|
2999
|
1476 |
|
3172
|
1477 @item ovf |
|
2999
|
1478 @flindex .ovf |
|
|
1479 @vindex OVFFONTS |
|
|
1480 (Omega virtual fonts) |
|
3172
|
1481 @code{OVFFONTS}, @code{TEXFONTS}; |
|
|
1482 suffix @samp{.ovf}. |
|
2999
|
1483 |
|
3172
|
1484 @item ovp |
|
2999
|
1485 @flindex .ovp |
|
|
1486 @vindex OVPFONTS |
|
|
1487 (Omega virtual property lists) |
|
3172
|
1488 @code{OVPFONTS}, @code{TEXFONTS}; |
|
|
1489 suffix @samp{.ovp}. |
|
2999
|
1490 |
|
|
1491 @item pk |
|
|
1492 @flindex .pk |
|
|
1493 @vindex PKFONTS |
|
|
1494 @vindex TEXPKS |
|
|
1495 @vindex GLYPHFONTS |
|
|
1496 @vindex TEXFONTS |
|
|
1497 (packed bitmap fonts, @pxref{Glyph files,,, dvips, Dvips}) |
|
|
1498 @code{@var{PROGRAM}FONTS} (@var{program} being @samp{XDVI}, etc.), |
|
|
1499 @code{PKFONTS}, @code{TEXPKS}, @code{GLYPHFONTS}, @code{TEXFONTS}; |
|
3172
|
1500 suffix @samp{pk}; |
|
|
1501 dynamic creation program: @code{mktexpk}. |
|
2999
|
1502 |
|
3172
|
1503 @item PostScript header |
|
2999
|
1504 @flindex .pro |
|
|
1505 @vindex TEXPSHEADERS |
|
|
1506 @vindex PSHEADERS |
|
|
1507 (downloadable PostScript, @pxref{Header files,,, dvips, Dvips}) |
|
3172
|
1508 @code{TEXPSHEADERS}, @code{PSHEADERS}; |
|
|
1509 additional suffix @samp{.pro}. |
|
2999
|
1510 |
|
3172
|
1511 @item tex |
|
2999
|
1512 @flindex .tex |
|
|
1513 @vindex TEXINPUTS |
|
|
1514 (@TeX{} source, @pxref{tex invocation,,, web2c, Web2c}) |
|
|
1515 @code{TEXINPUTS}; |
|
3172
|
1516 suffix @samp{.tex}; |
|
|
1517 additional suffixes: none, because such a list cannot be complete; |
|
|
1518 dynamic creation program: @code{mktextex}. |
|
2999
|
1519 |
|
3172
|
1520 @item TeX system documentation |
|
2999
|
1521 @flindex doc files |
|
|
1522 @vindex TEXDOCS |
|
|
1523 (Documentation files for the @TeX{} system) |
|
|
1524 @code{TEXDOCS}. |
|
|
1525 |
|
3172
|
1526 @item TeX system sources |
|
2999
|
1527 @flindex source files |
|
|
1528 @vindex TEXSOURCES |
|
|
1529 (Source files for the @TeX{} system) |
|
|
1530 @code{TEXSOURCES}. |
|
|
1531 |
|
3172
|
1532 @item texpool |
|
|
1533 @flindex .pool |
|
|
1534 @vindex TEXPOOL |
|
|
1535 (@TeX{} program strings, @pxref{pooltype invocation,,, web2c, Web2c}) |
|
|
1536 @code{TEXPOOL}, @code{TEXMFINI}; |
|
|
1537 suffix @samp{.pool}. |
|
|
1538 |
|
|
1539 @item tfm |
|
2999
|
1540 @flindex .tfm |
|
|
1541 @vindex TFMFONTS |
|
|
1542 @vindex TEXFONTS |
|
|
1543 (@TeX{} font metrics, @pxref{Metric files,,, dvips, Dvips}) |
|
|
1544 @code{TFMFONTS}, @code{TEXFONTS}; |
|
3172
|
1545 suffix @samp{.tfm}; |
|
|
1546 dynamic creation program: @code{mktextfm}. |
|
2999
|
1547 |
|
3172
|
1548 @item Troff fonts |
|
2999
|
1549 @vindex TRFONTS |
|
|
1550 (Troff fonts, used by DMP; @pxref{DMP invocation,,, web2c, Web2c}) |
|
|
1551 @code{TRFONTS}. |
|
|
1552 |
|
3172
|
1553 @item truetype fonts |
|
|
1554 @flindex .ttf |
|
|
1555 @flindex .ttc |
|
|
1556 @vindex TTFONTS |
|
|
1557 (TrueType outline fonts) @code{TTFONTS}; suffixes @samp{.ttf}, |
|
|
1558 @samp{.ttc}. |
|
|
1559 |
|
|
1560 @item type1 fonts |
|
2999
|
1561 @flindex .pfa |
|
|
1562 @flindex .pfb |
|
|
1563 @vindex T1FONTS |
|
|
1564 @vindex T1INPUTS |
|
|
1565 @vindex TEXPSHEADERS |
|
|
1566 @vindex DVIPSHEADERS |
|
|
1567 (Type 1 PostScript outline fonts, @pxref{Glyph files,,, dvips, Dvips}) |
|
3172
|
1568 @code{T1FONTS}, @code{T1INPUTS}, @code{TEXPSHEADERS}, @code{DVIPSHEADERS}; |
|
|
1569 suffixes @samp{.pfa}, @samp{.pfb}. |
|
2999
|
1570 |
|
3172
|
1571 @item type42 fonts |
|
|
1572 @vindex T42FONTS |
|
|
1573 (Type 42 PostScript outline fonts) @code{T42FONTS}. |
|
|
1574 |
|
|
1575 @item vf |
|
2999
|
1576 @flindex .vf |
|
|
1577 @vindex VFFONTS |
|
|
1578 @vindex TEXFONTS |
|
|
1579 (virtual fonts, @pxref{Virtual fonts,,, dvips, Dvips}) |
|
3172
|
1580 @code{VFFONTS}, @code{TEXFONTS}; |
|
|
1581 suffix @samp{.vf}. |
|
|
1582 @end table |
|
|
1583 |
|
|
1584 There are two special cases, because the paths and environment variables |
|
|
1585 always depend on the name of the program: the variable name is |
|
|
1586 constructed by converting the program name to upper case, and then |
|
|
1587 appending @samp{INPUTS}. Assuming the program is called @samp{foo}, |
|
|
1588 this gives us the following table. |
|
2999
|
1589 |
|
3172
|
1590 @table @samp |
|
|
1591 @item other text files |
|
|
1592 @vindex FOOINPUTS |
|
|
1593 (text files used by @samp{foo}) |
|
|
1594 @code{FOOINPUTS}. |
|
|
1595 |
|
|
1596 @item other binary files |
|
|
1597 @vindex FOOINPUTS |
|
|
1598 (binary files used by @samp{foo}) |
|
|
1599 @code{FOOINPUTS}. |
|
2999
|
1600 @end table |
|
|
1601 |
|
|
1602 If an environment variable by these names are set, the corresponding |
|
|
1603 @file{texmf.cnf} definition won't be looked at (unless, as usual, the |
|
|
1604 environment variable value has an extra @samp{:}). @xref{Default |
|
|
1605 expansion}. |
|
|
1606 |
|
|
1607 For the font variables, the intent is that: |
|
|
1608 @itemize @bullet |
|
|
1609 @item |
|
|
1610 @code{TEXFONTS} is the default for everything. |
|
|
1611 |
|
|
1612 @item |
|
|
1613 @code{GLYPHFONTS} is the default for bitmap (or, more precisely, |
|
|
1614 non-metric) files. |
|
|
1615 |
|
|
1616 @item |
|
|
1617 Each font format has a variable of its own. |
|
|
1618 |
|
|
1619 @item |
|
|
1620 @vindex XDVIFONTS |
|
|
1621 @vindex DVIPSFONTS |
|
|
1622 Each program has its own font override path as well; e.g., |
|
|
1623 @code{DVIPSFONTS} for Dvipsk. Again, this is for bitmaps, not metrics. |
|
|
1624 |
|
|
1625 @end itemize |
|
|
1626 |
|
|
1627 |
|
|
1628 @node File lookup |
|
|
1629 @section File lookup |
|
|
1630 |
|
|
1631 @cindex file lookup |
|
|
1632 @cindex searching for files |
|
|
1633 @cindex @TeX{} file lookup |
|
|
1634 |
|
|
1635 This section describes how Kpathsea searches for most files (bitmap font |
|
|
1636 searches are the exception, as described in the next section). |
|
|
1637 |
|
|
1638 Here is the search strategy for a file @var{name}: |
|
|
1639 @enumerate |
|
|
1640 @item |
|
3172
|
1641 If the file format defines default suffixes, and the suffix of |
|
|
1642 @var{name} name is not already a known suffix for that format, try the |
|
|
1643 name with each default appended, and use alternative names found in the |
|
|
1644 fontmaps if necessary. We postpone searching the disk as long as |
|
|
1645 possible. Example: given @samp{foo.sty}, look for @samp{foo.sty.tex} |
|
|
1646 before @samp{foo.sty}. This is unfortunate, but allows us to find |
|
|
1647 @samp{foo.bar.tex} before @samp{foo.bar} if both exist and we were given |
|
|
1648 @samp{foo.bar}. |
|
2999
|
1649 |
|
|
1650 @item |
|
3172
|
1651 Search for @var{name}, and if necssary for alternative names found in |
|
|
1652 the fontmaps. Again we avoid searching the disk if possible. Example: |
|
|
1653 given @samp{foo}, we look for @samp{foo}. |
|
2999
|
1654 |
|
|
1655 @item |
|
|
1656 If the file format defines a program to invoke to create missing files, |
|
3172
|
1657 run it (@pxref{mktex scripts}). |
|
2999
|
1658 @end enumerate |
|
|
1659 |
|
|
1660 @flindex tex-file.c |
|
|
1661 @findex kpse_find_file |
|
|
1662 This is implemented in the routine @code{kpse_find_file} in |
|
|
1663 @file{kpathsea/tex-file.c}. You can watch it in action with the |
|
|
1664 debugging options (@pxref{Debugging}). |
|
|
1665 |
|
|
1666 |
|
|
1667 @node Glyph lookup |
|
|
1668 @section Glyph lookup |
|
|
1669 |
|
|
1670 @cindex glyph lookup |
|
|
1671 @cindex searching for glyphs |
|
|
1672 @cindex @TeX{} glyph lookup |
|
|
1673 |
|
|
1674 This section describes how Kpathsea searches for a bitmap font in GF or |
|
|
1675 PK format (or either) given a font name (e.g., @samp{cmr10}) and a |
|
|
1676 resolution (e.g., 600). |
|
|
1677 |
|
|
1678 Here is an outline of the search strategy (details in the sections |
|
|
1679 below) for a file @var{name} at resolution @var{dpi}. The search stops |
|
|
1680 at the first successful lookup. |
|
|
1681 |
|
|
1682 @enumerate |
|
|
1683 @item |
|
|
1684 Look for an existing file @var{name}.@var{dpi}@var{format} in the |
|
|
1685 specified format(s). |
|
|
1686 |
|
|
1687 @item If @var{name} is an alias for a file @var{f} in the fontmap |
|
|
1688 file @file{texfonts.map}, look for @var{f}.@var{dpi}. |
|
|
1689 |
|
3172
|
1690 @item Run an external program (typically named @samp{mktexpk}) to |
|
|
1691 generate the font (@pxref{mktex scripts}) |
|
2999
|
1692 |
|
|
1693 @item Look for @var{fallback}.@var{dpi}, where @var{fallback} is some |
|
|
1694 last-resort font (typically @samp{cmr10}). |
|
|
1695 @end enumerate |
|
|
1696 |
|
|
1697 @flindex tex-glyph.c |
|
|
1698 @findex kpse_find_glyph_format |
|
|
1699 This is implemented in @code{kpse_find_glyph_format} in |
|
|
1700 @file{kpathsea/tex-glyph.c}. |
|
|
1701 |
|
|
1702 @menu |
|
|
1703 * Basic glyph lookup:: Features common to all glyph lookups. |
|
|
1704 * Fontmap:: Aliases for fonts. |
|
|
1705 * Fallback font:: Resolutions and fonts of last resort. |
|
|
1706 @end menu |
|
|
1707 |
|
|
1708 |
|
|
1709 @node Basic glyph lookup |
|
|
1710 @subsection Basic glyph lookup |
|
|
1711 |
|
|
1712 @cindex basic glyph lookup |
|
|
1713 @cindex common features in glyph lookup |
|
|
1714 |
|
|
1715 When Kpathsea looks for a bitmap font @var{name} at resolution @var{dpi} |
|
|
1716 in a format @var{format}, it first checks each directory in the search |
|
|
1717 path for a file @samp{@var{name}.@var{dpi}@var{format}}; for example, |
|
|
1718 @samp{cmr10.600pk}. Kpathsea looks for a PK file first, then a GF file. |
|
|
1719 |
|
|
1720 If that fails, Kpathsea looks for |
|
|
1721 @samp{dpi@var{dpi}/@var{name}.@var{format}}; for example, |
|
|
1722 @samp{dpi600/cmr10.pk}. This is how fonts are typically stored on |
|
|
1723 filesystems (such as DOS) that permit only three-character extensions. |
|
|
1724 |
|
|
1725 @cindex tolerance for glyph lookup |
|
|
1726 @cindex glyph lookup bitmap tolerance |
|
|
1727 @findex KPSE_BITMAP_TOLERANCE |
|
|
1728 If that fails, Kpathsea looks for a font with a close-enough @var{dpi}. |
|
|
1729 ``Close enough'' is defined by the macro @code{KPSE_BITMAP_TOLERANCE} in |
|
|
1730 @file{kpathsea/tex-glyph.h} to be @code{@var{dpi} / 500 + 1}. This is |
|
|
1731 slightly more than the 0.2% minimum allowed by the DVI standard |
|
|
1732 (@url{@var{CTAN:}/dviware/driv-standard/level-0}). |
|
|
1733 |
|
|
1734 |
|
|
1735 @node Fontmap |
|
|
1736 @subsection Fontmap |
|
|
1737 |
|
|
1738 @cindex fontmap files |
|
|
1739 @cindex font alias files |
|
|
1740 @cindex aliases for fonts |
|
|
1741 |
|
|
1742 @flindex texfonts.map |
|
|
1743 If a bitmap font or metric file is not found with the original name (see |
|
|
1744 the previous section), Kpathsea looks through any @dfn{fontmap} files |
|
|
1745 for an @dfn{alias} for the original font name. These files are named |
|
|
1746 @file{texfonts.map} and searched for along the @code{TEXFONTMAPS} |
|
|
1747 environment/config file variable. All @file{texfonts.map} files that |
|
|
1748 are found are read; earlier definitions override later ones. |
|
|
1749 |
|
|
1750 This feature is intended to help in two respects: |
|
|
1751 |
|
|
1752 @enumerate |
|
|
1753 |
|
|
1754 @item |
|
|
1755 @cindex fontnames, arbitrary length |
|
|
1756 An alias name is limited in length only by available memory, not by your |
|
|
1757 filesystem. Therefore, if you want to ask for @samp{Times-Roman} |
|
|
1758 instead of @file{ptmr}, you can (you get @samp{ptmr8r}). |
|
|
1759 |
|
|
1760 @item |
|
|
1761 @cindex circle fonts |
|
|
1762 @flindex lcircle10 |
|
|
1763 A few fonts have historically had multiple names: specifically, |
|
|
1764 La@TeX{}'s ``circle font'' has variously been known as @file{circle10}, |
|
|
1765 @file{lcircle10}, and @file{lcirc10}. Aliases can make all the names |
|
|
1766 equivalent, so that it no longer matters what the name of the installed |
|
|
1767 file is; @TeX{} documents will find their favorite name. |
|
|
1768 |
|
|
1769 @end enumerate |
|
|
1770 |
|
|
1771 The format of fontmap files is straightforward: |
|
|
1772 |
|
|
1773 @itemize @bullet |
|
|
1774 @cindex comments, in fontmap files |
|
|
1775 @item Comments start with @samp{%} and continue to the end of the line. |
|
|
1776 @cindex whitespace, in fontmap files |
|
|
1777 @item Blank lines are ignored. |
|
|
1778 @item Each nonblank line is broken up into a series of @dfn{words}: |
|
|
1779 a sequence of non-whitespace characters. |
|
|
1780 @findex include @r{fontmap directive} |
|
|
1781 @item If the first word is @samp{include}, the second word is used as |
|
|
1782 a filename, and it is searched for and read. |
|
|
1783 @item Otherwise, the first word on each line is the true filename; |
|
|
1784 @item the second word is the alias; |
|
|
1785 @item subsequent words are ignored. |
|
|
1786 @end itemize |
|
|
1787 |
|
|
1788 If an alias has an extension, it matches only those files with that |
|
|
1789 extension; otherwise, it matches anything with the same root, regardless |
|
|
1790 of extension. For example, an alias @samp{foo.tfm} matches only when |
|
|
1791 @file{foo.tfm} is being searched for; but an alias @samp{foo} matches |
|
|
1792 @file{foo.vf}, @file{foo.600pk}, etc. |
|
|
1793 |
|
|
1794 As an example, here is an excerpt from the @file{texfonts.map} in the |
|
|
1795 Web2c distribution. It makes the circle fonts equivalent and includes |
|
|
1796 automatically generated maps for most PostScript fonts available from |
|
|
1797 various font suppliers. |
|
|
1798 |
|
|
1799 @example |
|
|
1800 circle10 lcircle10 |
|
|
1801 circle10 lcirc10 |
|
|
1802 lcircle10 circle10 |
|
|
1803 lcircle10 lcirc10 |
|
|
1804 lcirc10 circle10 |
|
|
1805 lcirc10 lcircle10 |
|
|
1806 @dots{} |
|
|
1807 include adobe.map |
|
|
1808 include apple.map |
|
|
1809 include bitstrea.map |
|
|
1810 @dots{} |
|
|
1811 @end example |
|
|
1812 |
|
|
1813 Fontmaps are implemented in the file @file{kpathsea/fontmap.c}. |
|
|
1814 The Fontname distribution has much more information on font naming |
|
|
1815 (@pxref{Introduction,,, fontname, Filenames for @TeX{} fonts}). |
|
|
1816 |
|
|
1817 |
|
|
1818 @node Fallback font |
|
|
1819 @subsection Fallback font |
|
|
1820 |
|
|
1821 @cindex fallback font |
|
|
1822 @cindex fallback resolutions |
|
|
1823 @cindex font of last resort |
|
|
1824 @cindex resolutions, last-resort |
|
|
1825 @cindex last-resort font |
|
|
1826 |
|
|
1827 @vindex DVIPSSIZES |
|
|
1828 @vindex XDVISIZES |
|
|
1829 @vindex DVILJSIZES |
|
|
1830 @vindex TEXSIZES |
|
|
1831 @vindex default_texsizes |
|
|
1832 If a bitmap font cannot be found or created at the requested size, |
|
|
1833 Kpathsea looks for the font at a set of @dfn{fallback resolutions}. You |
|
|
1834 specify these resolutions as a colon-separated list (like search paths). |
|
|
1835 Kpathsea looks first for a program-specific environment variable (e.g., |
|
|
1836 @code{DVIPSSIZES} for Dvipsk), then the environment variable |
|
|
1837 @code{TEXSIZES}, then a default specified at compilation time (the Make |
|
|
1838 variable @code{default_texsizes}). You can set this list to be empty if |
|
|
1839 you prefer to find fonts at their stated size or not at all. |
|
|
1840 |
|
|
1841 @flindex cmr10@r{, as fallback font} |
|
|
1842 @vindex kpse_fallback_font |
|
|
1843 Finally, if the font cannot be found even at the fallback resolutions, |
|
|
1844 Kpathsea looks for a fallback font, typically @file{cmr10}. Programs |
|
|
1845 must enable this feature by assigning to the global variable |
|
|
1846 @code{kpse_fallback_font} or calling @code{kpse_init_prog} |
|
|
1847 (@pxref{Calling sequence}); the default is no fallback font. |
|
|
1848 |
|
|
1849 |
|
|
1850 @node Suppressing warnings |
|
|
1851 @section Suppressing warnings |
|
|
1852 |
|
|
1853 @cindex warnings, suppressing |
|
|
1854 @cindex suppressing warnings |
|
|
1855 |
|
|
1856 @vindex TEX_HUSH |
|
|
1857 Kpathsea provides a way to suppress selected usually-harmless warnings; |
|
|
1858 this is useful at large sites where most users are not administrators, |
|
|
1859 and thus the warnings are merely a source of confusion, not a help. To |
|
|
1860 do this, you set the environment variable or configuration file value |
|
|
1861 @code{TEX_HUSH} to a colon-separated list of values. Here are the |
|
|
1862 possibilities: |
|
|
1863 |
|
|
1864 @vtable @samp |
|
|
1865 @item all |
|
|
1866 Suppress everything possible. |
|
|
1867 |
|
|
1868 @item checksum |
|
|
1869 @cindex mismatched checksum warnings |
|
|
1870 Suppress mismatched font checksum warnings. |
|
|
1871 |
|
|
1872 @item lostchar |
|
|
1873 @cindex missing character warnings |
|
|
1874 Suppress warnings when a character is missing from a font that a DVI or |
|
|
1875 VF file tries to typeset. |
|
|
1876 |
|
|
1877 @item readable |
|
|
1878 @cindex unreadable file warnings |
|
|
1879 Suppress warnings about attempts to access a file whose permissions |
|
|
1880 render it unreadable. |
|
|
1881 |
|
|
1882 @item special |
|
|
1883 @cindex unknown special warnings |
|
|
1884 @findex \special@r{, suppressing warnings about} |
|
|
1885 Suppresses warnings about an unimplemented or unparsable |
|
|
1886 @samp{\special} command. |
|
|
1887 @end vtable |
|
|
1888 |
|
|
1889 @noindent @file{tex-hush.c} defines the function that checks the |
|
|
1890 variable value. Each driver implements its own checks where |
|
|
1891 appropriate. |
|
|
1892 |
|
|
1893 |
|
|
1894 @node Programming |
|
|
1895 @chapter Programming |
|
|
1896 |
|
|
1897 This chapter is for programmers who wish to use Kpathsea. |
|
|
1898 @xref{Introduction}, for the conditions under which you may do so. |
|
|
1899 |
|
|
1900 @menu |
|
|
1901 * Overview: Programming overview. Introduction. |
|
|
1902 * Calling sequence:: Specifics of what to call. |
|
3172
|
1903 * Program-specific files:: How to handle these. |
|
2999
|
1904 * Config: Programming with config files. Getting info from texmf.cnf. |
|
|
1905 @end menu |
|
|
1906 |
|
|
1907 |
|
|
1908 @node Programming overview |
|
|
1909 @section Programming overview |
|
|
1910 |
|
|
1911 @cindex programming overview |
|
|
1912 @cindex overview of programming with Kpathsea |
|
|
1913 |
|
|
1914 Aside from this manual, your best source of information is the source to |
|
|
1915 the programs I've modified to use Kpathsea (@pxref{Introduction}). Of |
|
|
1916 those, Dviljk is probably the simplest, and hence a good place to start. |
|
|
1917 Xdvik adds VF support and the complication of X resources. Dvipsk adds |
|
|
1918 the complication of its own config files. Web2c is source code I also |
|
|
1919 maintain, so it uses Kpathsea rather straightforwardly, but is of course |
|
|
1920 complicated by the Web to C translation. Finally, Kpsewhich is a small |
|
|
1921 utility program whose sole purpose is to exercise the main |
|
|
1922 path-searching functionality. |
|
|
1923 |
|
|
1924 @flindex pathsearch.h |
|
|
1925 @flindex tex-file.h |
|
|
1926 @flindex tex-glyph.h |
|
|
1927 @flindex kpathsea.h |
|
|
1928 Beyond these examples, the @file{.h} files in the Kpathsea source |
|
|
1929 describe the interfaces and functionality (and of course the @file{.c} |
|
|
1930 files define the actual routines, which are the ultimate documentation). |
|
|
1931 @file{pathsearch.h} declares the basic searching routine. |
|
|
1932 @file{tex-file.h} and @file{tex-glyph.h} define the interfaces for |
|
|
1933 looking up particular kinds of files. You may wish to use |
|
|
1934 @code{#include <kpathsea/kpathsea.h>}, which includes every Kpathsea header. |
|
|
1935 |
|
|
1936 @cindex file types, registering new |
|
|
1937 The library provides no way for an external program to register new file |
|
|
1938 types: @file{tex-file.[ch]} must be modified to do this. For example, |
|
|
1939 Kpathsea has support for looking up Dvips config files, even though no |
|
|
1940 program other than Dvips will likely ever want to do so. I felt this |
|
|
1941 was acceptable, since along with new file types should also come new |
|
|
1942 defaults in @file{texmf.cnf} (and its descendant @file{paths.h}), since |
|
|
1943 it's simplest for users if they can modify one configuration file for |
|
|
1944 all kinds of paths. |
|
|
1945 |
|
|
1946 Kpathsea does not parse any formats itself; it barely opens any files. |
|
|
1947 Its primary purpose is to return filenames. The GNU font utilities does |
|
|
1948 contain libraries to read TFM, GF, and PK files, as do the programs |
|
|
1949 above, of course. |
|
|
1950 |
|
|
1951 |
|
|
1952 @node Calling sequence |
|
|
1953 @section Calling sequence |
|
|
1954 |
|
|
1955 @cindex programming with Kpathsea |
|
|
1956 @cindex calling sequence |
|
|
1957 |
|
|
1958 The typical way to use Kpathsea in your program goes something like this: |
|
|
1959 |
|
|
1960 @enumerate |
|
|
1961 |
|
|
1962 @item |
|
3172
|
1963 @findex kpse_set_program_name |
|
2999
|
1964 @vindex argv[0] |
|
3172
|
1965 Call @code{kpse_set_program_name} with @code{argv[0]} as the first |
|
|
1966 argument; the second argument is a string or @code{NULL}. The second |
|
|
1967 argument is used by Kpathsea as the program name for the |
|
|
1968 @code{.@var{program}} feature of config files (@pxref{Config files}). |
|
|
1969 If the second argument is @code{NULL}, the value of the first argument |
|
|
1970 is used. This function must be called before any other use of the |
|
|
1971 Kpathsea library. |
|
2999
|
1972 |
|
|
1973 @vindex program_invocation_name |
|
|
1974 @vindex program_invocation_short_name |
|
3172
|
1975 @vindex kpse_program_name |
|
2999
|
1976 @vindex KPATHSEA_DEBUG |
|
|
1977 @cindex SELFAUTOLOC |
|
|
1978 @cindex SELFAUTODIR |
|
|
1979 @cindex SELFAUTOPARENT |
|
|
1980 @cindex error message macros |
|
|
1981 @cindex symlinks, resolving |
|
|
1982 @cindex expanding symlinks |
|
3172
|
1983 If necessary, @code{kpse_set_program_name} sets the global variables |
|
2999
|
1984 @code{program_invocation_name} and @code{program_invocation_short_name}. |
|
|
1985 These variables are used in the error message macros defined in |
|
3172
|
1986 @file{kpathsea/lib.h}. It sets the global variable |
|
|
1987 @code{kpse_program_name} to the program name it uses. It also |
|
|
1988 initializes debugging options based on the environment variable |
|
|
1989 @code{KPATHSEA_DEBUG} (if that is set). Finally, it sets the variables |
|
|
1990 @code{SELFAUTOLOC}, @code{SELFAUTODIR} and @code{SELFAUTOPARENT} to the |
|
|
1991 location, parent and grandparent directory of the executable, removing |
|
|
1992 @file{.} and @file{..} path elements and resolving symbolic links. |
|
|
1993 These are used in the default configuration file to allow people to |
|
|
1994 invoke TeX from anywhere, specifically from a mounted CD-ROM. (You can |
|
|
1995 use @samp{--expand-var=\$SELFAUTOLOC}, etc., to see the values finds.) |
|
|
1996 |
|
|
1997 @item |
|
|
1998 @findex kpse_set_progname |
|
|
1999 @vindex argv[0] |
|
|
2000 The @code{kpse_set_progname} is deprecated. A call to |
|
|
2001 @code{kpse_set_progname} with @code{argv[0]} is equivalent to a call of |
|
|
2002 @code{kpse_set_program_name} with first argument @code{argv[0]} and |
|
|
2003 second argument @code{NULL}. The function is deprecated because it |
|
|
2004 cannot ensure that the @code{.@var{program}} feature of config files |
|
|
2005 will always work (@pxref{Config files}). |
|
2999
|
2006 |
|
|
2007 @item |
|
|
2008 @vindex kpathsea_debug @r{variable} |
|
|
2009 @cindex debugging options, in Kpathsea-using program |
|
|
2010 Set debugging options. @xref{Debugging}. If your program doesn't have a |
|
|
2011 debugging option already, you can define one and set |
|
|
2012 @code{kpathsea_debug} to the number that the user supplies (as in Dviljk |
|
|
2013 and Web2c), or you can just omit this altogether (people can always set |
|
|
2014 @code{KPATHSEA_DEBUG}). If you do have runtime debugging already, you |
|
|
2015 need to merge Kpathsea's options with yours (as in Dvipsk and Xdvik). |
|
|
2016 |
|
|
2017 @item |
|
|
2018 @vindex client_path @r{in @code{kpse_format_info}} |
|
|
2019 @vindex kpse_format_info |
|
|
2020 @flindex resident.c |
|
|
2021 @cindex config files, for Kpathsea-using programs |
|
|
2022 If your program has its own configuration files that can define search |
|
|
2023 paths, you should assign those paths to the @code{client_path} member in |
|
|
2024 the appropriate element of the @code{kpse_format_info} array. (This |
|
|
2025 array is indexed by file type; see @file{tex-file.h}.) See |
|
|
2026 @file{resident.c} in Dvipsk for an example. |
|
|
2027 |
|
|
2028 @item |
|
|
2029 @findex kpse_init_prog |
|
|
2030 @flindex proginit.h |
|
|
2031 Call @code{kpse_init_prog} (see @file{proginit.c}). It's useful for the |
|
|
2032 DVI drivers, at least, but for other programs it may be simpler to |
|
|
2033 extract the parts of it that actually apply. This does not initialize |
|
|
2034 any paths, it just looks for (and sets) certain environment variables |
|
|
2035 and other random information. (A search path is always initialized at |
|
|
2036 the first call to find a file of that type; this eliminates much useless |
|
|
2037 work, e.g., initializing the Bib@TeX{} search paths in a DVI driver.) |
|
|
2038 |
|
|
2039 @item |
|
|
2040 @findex kpse_find_* |
|
3172
|
2041 @findex kpse_find_file |
|
2999
|
2042 The routine to actually find a file of type @var{format} is |
|
|
2043 @code{kpse_find_@var{format}}, defined in @file{tex-file.h}. These are |
|
|
2044 macros that expand to a call to @file{kpse_find_file}. You can call, |
|
|
2045 say, @code{kpse_find_tfm} after doing only the first of the |
|
|
2046 initialization steps above---Kpathsea automatically reads the |
|
|
2047 @file{texmf.cnf} generic config files, looks for environment variables, |
|
|
2048 and does expansions at the first lookup. |
|
|
2049 |
|
|
2050 @item |
|
|
2051 To find PK and/or GF bitmap fonts, the routines are @code{kpse_find_pk}, |
|
|
2052 @code{kpse_find_gf} and @code{kpse_find_glyph}, defined in |
|
|
2053 @file{tex-glyph.h}. These return a structure in addition to the |
|
|
2054 resultant filename, because fonts can be found in so many ways. See the |
|
|
2055 documentation in the source. |
|
|
2056 |
|
|
2057 @item |
|
|
2058 @findex kpse_open_file |
|
|
2059 To actually open a file, not just return a filename, call |
|
|
2060 @code{kpse_open_file}. This function takes the name to look up and a |
|
|
2061 Kpathsea file format as arguments, and returns the usual @code{FILE *}. |
|
|
2062 It always assumes the file must exist, and thus will search the disk if |
|
|
2063 necessary (unless the search path specified @samp{!!}, etc.). In other |
|
|
2064 words, if you are looking up a VF or some other file that need not |
|
|
2065 exist, don't use this. |
|
|
2066 |
|
|
2067 @end enumerate |
|
|
2068 |
|
|
2069 @cindex hash table routines |
|
|
2070 @cindex memory allocation routines |
|
|
2071 @cindex string routines |
|
|
2072 @cindex reading arbitrary-length lines |
|
|
2073 @cindex input lines, reading |
|
|
2074 @cindex lines, reading arbitrary-length |
|
|
2075 Kpathsea also provides many utility routines. Some are generic: hash |
|
|
2076 tables, memory allocation, string concatenation and copying, string |
|
|
2077 lists, reading input lines of arbitrary length, etc. Others are |
|
|
2078 filename-related: default path, tilde, and variable expansion, |
|
|
2079 @code{stat} calls, etc. (Perhaps someday I'll move the former to a |
|
|
2080 separate library.) |
|
|
2081 |
|
|
2082 @flindex c-*.h |
|
|
2083 @pindex autoconf@r{, recommended} |
|
|
2084 The @file{c-*.h} header files can also help your program adapt to many |
|
|
2085 different systems. You will almost certainly want to use Autoconf for |
|
|
2086 configuring your software if you use Kpathsea; I strongly recommend |
|
|
2087 using Autoconf regardless. It is available from |
|
3285
|
2088 @url{ftp://ftp.gnu.org/pub/gnu/autoconf}. |
|
2999
|
2089 |
|
|
2090 |
|
3172
|
2091 @node Program-specific files |
|
|
2092 @section Program-specific files |
|
|
2093 |
|
|
2094 Many programs will need to find some configuration files. Kpathsea |
|
|
2095 contains some support to make it easy to place them in their own |
|
|
2096 directories. The Standard @TeX{} directory structure (@pxref{Top,, |
|
|
2097 Introduction, tds, A Directory Structure for @TeX{} files}), specifies |
|
|
2098 that such files should go into a subdirectory named after the program, |
|
|
2099 like @samp{texmf/ttf2pk}. |
|
|
2100 |
|
|
2101 Two special formats, @samp{kpse_program_text_format} and |
|
|
2102 @samp{kpse_program_binary_format} exist, which use |
|
|
2103 @code{.:$TEXMF/@var{program}//} as their compiled-in search path. To |
|
|
2104 override this default, you can use the variable |
|
|
2105 @code{@var{PROGRAM}INPUTS} in the environment and/or @samp{texmf.cnf}. |
|
|
2106 That is to say, the name of the variable is constructed by converting |
|
|
2107 the name of the program to upper case, and appending @code{INPUTS}. |
|
|
2108 |
|
|
2109 The only difference between these two formats is whether |
|
|
2110 @code{kpse_open_file} will open the files it finds in text or binary |
|
|
2111 mode. |
|
|
2112 |
|
|
2113 |
|
2999
|
2114 @node Programming with config files |
|
|
2115 @section Programming with config files |
|
|
2116 |
|
|
2117 @cindex programming with config files |
|
|
2118 @cindex config files, programming with |
|
|
2119 |
|
|
2120 You can (and probably should) use the same @code{texmf.cnf} |
|
|
2121 configuration file that Kpathsea uses for your program. This helps |
|
|
2122 installers by keeping all configuration in one place. |
|
|
2123 |
|
3172
|
2124 @findex kpse_var_value |
|
2999
|
2125 @flindex variable.h |
|
|
2126 @vindex shell_escape@r{, example for code} |
|
|
2127 To retrieve a value @var{var} from config files, the best way is to call |
|
|
2128 @code{kpse_var_value} on the string @code{@var{var}}. This will look |
|
|
2129 first for an environment variable @var{var}, then a config file value. |
|
|
2130 The result will be the value found or @samp{NULL}. This function is |
|
|
2131 declared in @file{kpathsea/variable.h}. For an example, see the |
|
|
2132 @code{shell_escape} code in @file{web2c/lib/texmfmp.c}. |
|
|
2133 |
|
|
2134 The routine to do variable expansion in the context of a search path (as |
|
|
2135 opposed to simply retrieving a value) is @code{kpse_var_expand}, also |
|
|
2136 declared in @file{kpathsea/variable.h}. It's generally only necessary |
|
|
2137 to set the search path structure components as explained in the previous |
|
|
2138 section, rather than using this yourself. |
|
|
2139 |
|
|
2140 @findex kpse_cnf_get |
|
|
2141 @flindex cnf.h |
|
|
2142 If for some reason you want to retrieve a value @emph{only} from a |
|
|
2143 config file, not automatically looking for a corresponding environment |
|
|
2144 variable, call @code{kpse_cnf_get} (declared in @file{kpathsea/cnf.h}) |
|
|
2145 with the string @var{var}. |
|
|
2146 |
|
|
2147 No initialization calls are needed. |
|
|
2148 |
|
|
2149 |
|
|
2150 @node Index |
|
|
2151 @unnumbered Index |
|
|
2152 |
|
|
2153 @printindex cp |
|
|
2154 |
|
|
2155 @contents |
|
|
2156 |
|
|
2157 @bye |
