1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
|
\section{A user's guide to Web2C}
\Webc{} is an integrated collection of \TeX-related programs: \TeX{}
itself, \MF{}, \MP, \BibTeX{}, etc. It is the heart of \TL{}.
A bit of history: The original implementation was by Tomas Rokicki who,
in 1987, developed a first \TeX{}-to-C system based on change files
under Unix, which were primarily the original work of Howard Trickey and
Pavel Curtis. Tim Morgan became the maintainer of the system, and
during this period the name changed to Web-to-C\@. In 1990, Karl Berry
took over the work, assisted by dozens of additional contributors, and
in 1997 he handed the baton to Olaf Weber.
The \Webc{} system runs on Unix, 32-bit Windows systems, \MacOSX{}, and
other operating systems. It uses Knuth's original sources for \TeX{} and
other basic programs written in \web{} and translates them into C source
code. The core \TeX{} programs are:
\begin{cmddescription}
\item[bibtex] Maintaining bibliographies.
\item[dmp] \cmdname{troff} to MPX (\MP{} pictures).
\item[dvicopy] Expands virtual font references in \dvi{} files.
\item[dvitomp] \dvi{} to MPX (MetaPost pictures).
\item[dvitype] \dvi{} to human-readable text.
\item[gftodvi] Generic font proofsheets.
\item[gftopk] Generic to packed fonts.
\item[gftype] GF to human-readable text.
\item[makempx] \MP{} label typesetting.
\item[mf] Creating typeface families.
\item[mft] Prettyprinting \MF{} source.
\item[mpost] Creating technical diagrams.
\item[mpto] MetaPost label extraction.
\item[newer] Compare modification times.
\item[patgen] Creating hyphenation patterns.
\item[pktogf] Packed to generic fonts.
\item[pktype] PK to human-readable text.
\item[pltotf] Plain text property list to TFM.
\item[pooltype] Display \web{} pool files.
\item[tangle] \web{} to Pascal.
\item[tex] Typesetting.
\item[tftopl] TFM to plain text property list.
\item[vftovp] Virtual font to virtual property list.
\item[vptovf] Virtual property list to virtual font.
\item[weave] \web{} to \TeX.
\end{cmddescription}
\noindent The precise functions and syntax of these programs are
described in the documentation of the individual packages and of \Webc{}
itself. However, knowing a few principles governing the whole family of
programs will help you take advantage of your \Webc{} installation.
All programs honor these standard \acro{GNU} options:
\begin{ttdescription}
\item[-{}-help] print basic usage summary.
\item[-{}-verbose] print detailed progress report.
\item[-{}-version] print version information, then exit.
\end{ttdescription}
For locating files the \Webc{} programs use the path searching library
\KPS{}. This library uses a combination of environment variables and a
configuration files to optimize searching the (huge) collection of
\TeX{} files. \Webc{} can look at more than one directory tree
simultaneously, which is useful in maintaining \TeX's standard
distribution and local extensions in two distinct trees. To speed up
file searches the root of each tree has a file \file{ls-R}, containing
an entry showing the name and relative pathname for all files under that
root.
\subsection{Kpathsea path searching}
Let us first describe the generic path searching mechanism of the \KPS{}
library.
We call a \emph{search path} a colon- or semicolon\hyph sepa\-rated list
of \emph{path elements}, which are basically directory names. A
search path can come from (a combination of) many sources. To look up
a file \samp{my-file} along a path \samp{.:/dir}, \KPS{} checks each
element of the path in turn: first \file{./my-file}, then
\file{/dir/my-file}, returning the first match (or possibly all
matches).
In order to adapt optimally to all operating systems' conventions, on
non-Unix systems \KPS{} can use filename separators different from
colon (\samp{:}) and slash (\samp{/}).
To check a particular path element \var{p}, \KPS{} first checks if a
prebuilt database (see ``Filename data\-base'' on
page~\pageref{Filename-database}) applies to \var{p}, i.e., if the database
is in a directory that is a prefix of \var{p}. If so, the path
specification is matched against the contents of the database.
If the database does not exist, or does not apply to this path
element, or contains no matches, the filesystem is searched (if this
was not forbidden by a specification starting with \samp{!!}\ and if
the file being searched for must exist). \KPS{} constructs the list
of directories that correspond to this path element, and then checks
in each for the file being sought.
The ``file must exist'' condition comes into play with \samp{.vf} files and
input files read by \TeX's \cs{openin} command. Such files may not
exist (e.g., \file{cmr10.vf}), and so it would be wrong to search the
disk for them. Therefore, if you fail to update \file{ls-R} when you
install a new \samp{.vf} file, it will never be found.
Each path element is checked in turn: first the database, then the
disk. If a match is found, the search stops and the result is
returned.
Although the simplest and most common path element is a directory
name, \KPS{} supports additional features in search paths: layered
default values, environment variable names, config file values, users'
home directories, and recursive subdirectory searching. Thus, we say
that \KPS{} \emph{expands} a path element, meaning it transforms all
the specifications into basic directory name or names. This is
described in the following sections in the same order as it takes
place.
Note that if the filename being searched for is absolute or explicitly
relative, i.e., starts with \samp{/} or \samp{./} or \samp{../},
\KPS{} simply checks if that file exists.
\ifSingleColumn
\else
\begin{figure*}
\verbatiminput{examples/ex5.tex}
\setlength{\abovecaptionskip}{0pt}
\caption{An illustrative configuration file sample}
\label{fig:config-sample}
\end{figure*}
\fi
\subsubsection{Path sources}
\label{Path-sources}
A search path can come from many sources. In the order in which
\KPS{} uses them:
\begin{enumerate}
\item
A user-set environment variable, for instance, \envname{TEXINPUTS}\@.
Environment variables with a period and a program name appended
override; e.g., if \samp{latex} is the name of the program being run,
then \envname{TEXINPUTS.latex} will override \envname{TEXINPUTS}.
\item
A program-specific configuration file, for exam\-ple, a line
\samp{S /a:/b} in \cmdname{dvips}'s \file{config.ps}.
\item A \KPS{} configuration file \file{texmf.cnf}, containing a line like
\samp{TEXINPUTS=/c:/d} (see below).
\item The compile-time default.
\end{enumerate}
\noindent You can see each of these values for a given
search path by using the debugging options (see ``Debugging actions''
on page~\pageref{Debugging}).
\subsubsection{Config files}
\begingroup\tolerance=3500
\KPS{} reads \emph{runtime configuration files} named \file{texmf.cnf}
for search path and other definitions. The search path used to look
for these files is named \envname{TEXMFCNF} (by default such a file lives
in the \file{texmf/web2c} subdirectory). \emph{All}
\file{texmf.cnf} files in the search path will be read and definitions
in earlier files override those in later files. Thus, with a search
path of \verb|.:$TEXMF|, values from \file{./texmf.cnf} override those
from \verb|$TEXMF/texmf.cnf|.
\endgroup
\begin{itemize}
\item
Comments start with \code{\%} and continue to the end of the line.
\item
Blank lines are ignored.
\item
A \bs{} at the end of a line acts as a continuation character,
i.e., the next line is appended. Whitespace at the beginning of
continuation lines is not ignored.
\item
Each remaining line has the form:
\begin{alltt}
\var{variable}[.\var{progname}] [=] \var{value}
\end{alltt}%
where the \samp{=} and surrounding whitespace are optional.
\item
The \ttvar{variable} name may contain any character other
than whitespace, \samp{=}, or \samp{.}, but sticking to
\samp{A-Za-z\_} is safest.
\item
If \samp{.\var{progname}} is present, the definition only
applies if the program that is running is named
\texttt{\var{progname}} or \texttt{\var{progname}.exe}. This allows
different flavors of \TeX{} to have different search paths, for
example.
\item \var{value} may contain any characters except
\code{\%} and \samp{@}. The
\code{\$\var{var}.\var{prog}} feature is not available on the
right-hand side; instead, you must use an additional variable. A
\samp{;}\ in \var{value} is translated to \samp{:}\ if
running under Unix; this is useful to be able to have a single
\file{texmf.cnf} for Unix, \acro{MS-DOS} and Windows systems.
\item
All definitions are read before anything is expanded, so
variables can be referenced before they are defined.
\end{itemize}
A configuration file fragment illustrating most of these points is
\ifSingleColumn
shown below:
\verbatiminput{examples/ex5.tex}
\else
shown in Figure~\ref{fig:config-sample}.
\fi
\subsubsection{Path expansion}
\label{Path-expansion}
\KPS{} recognizes certain special characters and constructions in
search paths, similar to those available in Unix shells. As a
general example, the complex path,
\verb+~$USER/{foo,bar}//baz+, expands to all subdirectories under
directories \file{foo} and \file{bar} in \texttt{\$USER}'s home
directory that contain a directory or file \file{baz}. These
expansions are explained in the sections below.
%$
\subsubsection{Default expansion}
\label{Default-expansion}
\tolerance=2500
If the highest-priority search path (see ``Path sources'' on
page~\pageref{Path-sources}) contains an \emph{extra colon} (i.e.,
leading, trailing, or doubled), \KPS{} inserts at that point the
next-highest-prio\-rity search path that is defined. If that inserted
path has an extra colon, the same happens with the next highest. For
example, given an environment variable setting
\tolerance=1500
\begin{alltt}
> \Ucom{setenv TEXINPUTS /home/karl:}
\end{alltt}
and a \code{TEXINPUTS} value from \file{texmf.cnf} of
\begin{alltt}
.:\$TEXMF//tex
\end{alltt}
then the final value used for searching will be:
\begin{alltt}
/home/karl:.:\$TEXMF//tex
\end{alltt}
Since it would be useless to insert the default value in more than one
place, \KPS{} changes only one extra \samp{:}\ and leaves any others in
place. It checks first for a leading \samp{:}, then a trailing
\samp{:}, then a doubled \samp{:}.
\subsubsection{Brace expansion}
A useful feature is brace expansion, which means that, for instance,
\verb+v{a,b}w+ expands to \verb+vaw:vbw+. Nesting is allowed.
This is used to implement multiple \TeX{} hierarchies, by
assigning a brace list to \code{\$TEXMF}.
For example, in \file{texmf.cnf}, the following definition
(appproximately; there are actually even more trees) is made:
\begin{verbatim}
TEXMF = {$TEXMFHOME,$TEXMFLOCAL,!!$TEXMFVAR,!!$TEXMFMAIN}
\end{verbatim}
Using this you can then write something like
\begin{verbatim}
TEXINPUTS = .;$TEXMF/tex//
\end{verbatim}
%$
which means that, after looking in the current directory, the
\code{\$TEXMFHOME/tex}, \code{\$TEXMFLOCAL/tex}, \code{\$TEXMFVAR/tex}
and \code{\$TEXMFMAIN/tex} trees \emph{only}) will be searched (the
last two use using \file{ls-R} data base files). It is a convenient
way for running two parallel \TeX{} structures, one ``frozen'' (on a
\CD, for instance) and the other being continuously updated with new
versions as they become available. By using the \code{\$TEXMF}
variable in all definitions, one is sure to always search the
up-to-date tree first.
\subsubsection{Subdirectory expansion}
\label{Subdirectory-expansion}
Two or more consecutive slashes in a path element following a directory
\var{d} is replaced by all subdirectories of \var{d}: first those
subdirectories directly under \var{d}, then the subsubdirectories under
those, and so on. At each level, the order in which the directories are
searched is \emph{unspecified}.
If you specify any filename components after the \samp{//}, only
subdirectories with matching components are included. For example,
\samp{/a//b} expands into directories \file{/a/1/b}, \file{/a/2/b},
\file{/a/1/1/b}, and so on, but not \file{/a/b/c} or \file{/a/1}.
Multiple \samp{//} constructs in a path are possible, but
\samp{//} at the beginning of a path is ignored.
\subsubsection{List of special characters and their meaning: a summary}
The following list summarizes the special characters in \KPS{}
configuration files.
% need a wider space for the item labels here.
\newcommand{\CODE}[1]{\makebox[3em][l]{\code{#1}}}
\begin{ttdescription}
\item[\CODE{:}] Separator in path specification; at the beginning or
the end of a path it substitutes the default path expansion.\par
\item[\CODE{;}] Separator on non-Unix systems (acts like \code{:}).
\item[\CODE{\$}] Variable expansion.
\item[\CODE{\string~}] Represents the user's home directory.
\item[\CODE{\char`\{...\char`\}}] Brace expansion.
\item[\CODE{//}] Subdirectory expansion (can occur anywhere in
a path, except at its beginning).
\item[\CODE{\%}] Start of comment.
\item[\CODE{\bs}] Continuation character (allows multi-line entries).
\item[\CODE{!!}] Search \emph{only} database to locate file, \emph{do
not} search the disk.
\end{ttdescription}
\subsection{Filename databases}
\label{Filename-database}
\KPS{} goes to some lengths to minimize disk accesses for searches.
Nevertheless, at installations with enough directories, searching each
possible directory for a given file can take an excessively long time
(this is especially true if many hundreds of font directories have to
be traversed.) Therefore, \KPS{} can use an externally-built plain text
``database'' file named \file{ls-R} that maps files to directories,
thus avoiding the need to exhaustively search the disk.
A second database file \file{aliases} allows you to give additional
names to the files listed in \file{ls-R}. This can be helpful to
confirm to \acro{DOS} 8.3 filename conventions in source files.
\subsubsection{The filename database}
\label{ls-R}
As explained above, the name of the main filename database must be
\file{ls-R}. You can put one at the root of each \TeX{} hierarchy in
your installation that you wish to be searched (\code{\$TEXMF} by
default); most sites have only one hierarchy. \KPS{} looks for
\file{ls-R} files along the \code{TEXMFDBS} path.
The recommended way to create and maintain \samp{ls-R} is to run the
\code{mktexlsr} script included with the distribution. It is invoked
by the various \samp{mktex}\dots\ scripts. In principle, this script
just runs the command
\begin{alltt}
cd \var{/your/texmf/root} && \path|\|ls -1LAR ./ >ls-R
\end{alltt}
presuming your system's \code{ls} produces the right output format
(\acro{GNU} \code{ls} is all right). To ensure that the database is
always up-to-date, it is easiest to rebuild it regularly via
\code{cron}, so that it is automatically updated when the installed
files change, such as after installing or updating a \LaTeX{} package.
If a file is not found in the database, by default \KPS{} goes ahead
and searches the disk. If a particular path element begins with
\samp{!!}, however, \emph{only} the database will be searched for that
element, never the disk.
\subsubsection{kpsewhich: Standalone path searching}
\label{Invoking-kpsewhich}
The \texttt{kpsewhich} program exercises path searching independent of any
particular application. This can be useful as a sort of \code{find}
program to locate files in \TeX{} hierarchies (this is used heavily in
the distributed \samp{mktex}\dots\ scripts).
\begin{alltt}
> \Ucom{kpsewhich \var{option}\dots{} \var{filename}\dots{}}
\end{alltt}
The options specified in \ttvar{option} start with either \samp{-}
or \samp{-{}-}, and any unambiguous abbreviation is accepted.
\KPS{} looks up each non-option argument on the command line as a
filename, and returns the first file found. There is no option to
return all the files with a particular name (you can run the Unix
\samp{find} utility for that).
The more important options are described next.
\begin{ttdescription}
\item[\texttt{-{}-dpi=\var{num}}]\mbox{}
Set the resolution to \ttvar{num}; this only affects \samp{gf}
and \samp{pk} lookups. \samp{-D} is a synonym, for compatibility
with \cmdname{dvips}. Default is 600.
\item[\texttt{-{}-format=\var{name}}]\mbox{}\\
Set the format for lookup to \ttvar{name}. By default, the
format is guessed from the filename. For formats which do not have
an associated unambiguous suffix, such as \MP{} support files and
\cmdname{dvips} configuration files, you have to specify the name as
known to \KPS{}, such as \texttt{tex} or \texttt{enc files}. Run
\texttt{kpsewhich -{}-help} for a list.
\item[\texttt{-{}-mode=\var{string}}]\mbox{}\\
Set the mode name to \ttvar{string}; this only affects \samp{gf}
and \samp{pk} lookups. No default: any mode will be found.
\item[\texttt{-{}-must-exist}]\mbox{}\\
Do everything possible to find the files, notably including
searching the disk. By default, only the \file{ls-R} database is
checked, in the interest of efficiency.
\item[\texttt{-{}-path=\var{string}}]\mbox{}\\
Search along the path \ttvar{string} (colon-separated as usual),
instead of guessing the search path from the filename. \samp{//} and
all the usual expansions are supported. The options \samp{-{}-path}
and \samp{-{}-format} are mutually exclusive.
\item[\texttt{-{}-progname=\var{name}}]\mbox{}\\
Set the program name to \texttt{\var{name}}.
This can affect the search paths via the \texttt{.\var{progname}}
feature.
The default is \cmdname{kpsewhich}.
\item[\texttt{-{}-show-path=\var{name}}]\mbox{}\\
shows the path used for file lookups of file type \texttt{\var{name}}.
Either a filename extension (\code{.pk}, \code{.vf}, etc.) or a
name can be used, just as with \samp{-{}-format} option.
\item[\texttt{-{}-debug=\var{num}}]\mbox{}\\
sets the debugging options to \texttt{\var{num}}.
\end{ttdescription}
\subsubsection{Examples of use}
\label{SExamplesofuse}
Let us now have a look at \KPS{} in action. Here's a straightforward search:
\begin{alltt}
> \Ucom{kpsewhich article.cls}
/usr/local/texmf-dist/tex/latex/base/article.cls
\end{alltt}
We are looking for the file \file{article.cls}. Since the \samp{.cls}
suffix is unambiguous we do not need to specify that we want to look for a
file of type \optname{tex} (\TeX{} source file directories). We find it in
the subdirectory \file{tex/latex/base} below the \samp{texmf-dist} \TL\
directory. Similarly, all of the following are found without problems
thanks to their unambiguous suffix.
\begin{alltt}
> \Ucom{kpsewhich array.sty}
/usr/local/texmf-dist/tex/latex/tools/array.sty
> \Ucom{kpsewhich latin1.def}
/usr/local/texmf-dist/tex/latex/base/latin1.def
> \Ucom{kpsewhich size10.clo}
/usr/local/texmf-dist/tex/latex/base/size10.clo
> \Ucom{kpsewhich small2e.tex}
/usr/local/texmf-dist/tex/latex/base/small2e.tex
> \Ucom{kpsewhich tugboat.bib}
/usr/local/texmf-dist/bibtex/bib/beebe/tugboat.bib
\end{alltt}
That last is a \BibTeX{} bibliography database for \textsl{TUGBoat} articles.
\begin{alltt}
> \Ucom{kpsewhich cmr10.pk}
\end{alltt}
Font bitmap glyph files of type \file{.pk} are used by display
programs like \cmdname{dvips} and \cmdname{xdvi}. Nothing is returned in
this case since there are no pre-generated Computer Modern \samp{.pk}
files in \TL{}\Dash the Type~1 variants are used by default.
\begin{alltt}
> \Ucom{kpsewhich wsuipa10.pk}
\ifSingleColumn /usr/local/texmf-var/fonts/pk/ljfour/public/wsuipa/wsuipa10.600pk
\else /usr/local/texmf-var/fonts/pk/ljfour/public/
... wsuipa/wsuipa10.600pk
\fi\end{alltt}
For these fonts (a phonetic alphabet from the University of Washington)
we had to generate \samp{.pk} files, and since the default \MF{} mode on
our installation is \texttt{ljfour} with a base resolution of 600\dpi{}
(dots per inch), this instantiation is returned.
\begin{alltt}
> \Ucom{kpsewhich -dpi=300 wsuipa10.pk}
\end{alltt}
In this case, when specifying that we are interested in a resolution
of 300\dpi{} (\texttt{-dpi=300}) we see that no such font is available on
the system. A program like \cmdname{dvips} or \cmdname{xdvi} would
go off and actually build the required \texttt{.pk} files
using the script \cmdname{mktexpk}.
Next we turn our attention to \cmdname{dvips}'s header and configuration
files. We first look at one of the commonly used files, the general
prolog \file{tex.pro} for \TeX{} support, before turning our attention
to the generic configuration file (\file{config.ps}) and the \PS{} font
map \file{psfonts.map}\Dash as of 2004, map and encoding files have
their own search paths and new location in \dirname{texmf} trees. As
the \samp{.ps} suffix is ambiguous we have to specify explicitly which
type we are considering (\optname{dvips config}) for the file
\texttt{config.ps}.
\begin{alltt}
> \Ucom{kpsewhich tex.pro}
/usr/local/texmf/dvips/base/tex.pro
> \Ucom{kpsewhich --format="dvips config" config.ps}
/usr/local/texmf/dvips/config/config.ps
> \Ucom{kpsewhich psfonts.map}
/usr/local/texmf/fonts/map/dvips/updmap/psfonts.map
\end{alltt}
We now take a closer look at the \acro{URW} Times \PS{} support
files. The prefix for these in the standard font naming scheme is
\samp{utm}. The first file we look at is the configuration file,
which contains the name of the map file:
\begin{alltt}
> \Ucom{kpsewhich --format="dvips config" config.utm}
/usr/local/texmf-dist/dvips/psnfss/config.utm
\end{alltt}
The contents of that file is
\begin{alltt}
p +utm.map
\end{alltt}
which points to the file \file{utm.map}, which we want to
locate next.
\begin{alltt}
> \Ucom{kpsewhich utm.map}
/usr/local/texmf-dist/fonts/map/dvips/times/utm.map
\end{alltt}
This map file defines the file names of the Type~1 \PS{} fonts in
the URW collection. Its contents look like (we only show part of the
lines):
\begin{alltt}
utmb8r NimbusRomNo9L-Medi ... <utmb8a.pfb
utmbi8r NimbusRomNo9L-MediItal... <utmbi8a.pfb
utmr8r NimbusRomNo9L-Regu ... <utmr8a.pfb
utmri8r NimbusRomNo9L-ReguItal... <utmri8a.pfb
utmbo8r NimbusRomNo9L-Medi ... <utmb8a.pfb
utmro8r NimbusRomNo9L-Regu ... <utmr8a.pfb
\end{alltt}
Let us, for instance, take the Times Roman instance
\file{utmr8a.pfb} and find its position in the \file{texmf} directory
tree with a search for Type~1 font files:
\begin{alltt}
> \Ucom{kpsewhich utmr8a.pfb}
\ifSingleColumn /usr/local/texmf-dist/fonts/type1/urw/times/utmr8a.pfb
\else /usr/local/texmf-dist/fonts/type1/
... urw/utm/utmr8a.pfb
\fi\end{alltt}
It should be evident from these examples how you can easily locate the
whereabouts of a given file. This is especially important if you suspect
that the wrong version of a file is picked up somehow, since
\cmdname{kpsewhich} will show you the first file encountered.
\subsubsection{Debugging actions}
\label{Debugging}
Sometimes it is necessary to investigate how a program resolves file
references. To make this practical, \KPS{} offers various levels of
debugging output:
\begin{ttdescription}
\item[\texttt{\ 1}] \texttt{stat} calls (disk lookups). When running
with an up-to-date \file{ls-R} database this should almost give no
output.
\item[\texttt{\ 2}] References to hash tables (such as \file{ls-R}
databases, map files, configuration files).
\item[\texttt{\ 4}] File open and close operations.
\item[\texttt{\ 8}] General path information for file types
searched by \KPS. This is useful to find out where a particular
path for the file was defined.
\item[\texttt{16}] Directory list for each path element (only relevant
for searches on disk).
\item[\texttt{32}] File searches.
\end{ttdescription}
A value of \texttt{-1} will set all the above options; in practice,
this is usually the most convenient.
Similarly, with the \cmdname{dvips} program, by setting a combination of
debug switches, one can follow in detail where files are being picked up
from. Alternatively, when a file is not found, the debug trace shows in
which directories the program looks for the given file, so that one can
get an indication what the problem~is.
Generally speaking, as most programs call the \KPS{} library
internally, one can select a debug option by using the
\envname{KPATHSEA\_DEBUG} environment variable, and setting it to (a
combination of) values as described in the above list.
(Note for Windows users: it is not easy to redirect
all messages to a file in this system. For diagnostic purposes
you can temporarily \texttt{SET KPATHSEA\_DEBUG\_OUTPUT=err.log}).
Let us consider, as an example, a small \LaTeX{} source file,
\file{hello-world.tex}, which contains the following input.
\begin{verbatim}
\documentclass{article}
\begin{document}
Hello World!
\end{document}
\end{verbatim}
This little file only uses the font \file{cmr10}, so let us look at
how \cmdname{dvips} prepares the \PS{} file (we want to use the Type~1
version of the Computer Modern fonts, hence the option \texttt{-Pcms}).
\begin{alltt}
> \Ucom{dvips -d4100 hello-world -Pcms -o}
\end{alltt}
In this case we have combined \cmdname{dvips}'s debug class 4 (font
paths) with \KPS's path element expansion (see \cmdname{dvips} Reference
Manual, \OnCD{texmf/doc/html/dvips/dvips_toc.html}).
The output (slightly rearranged) appears in
Figure~\ref{fig:dvipsdbga}.
\begin{figure*}[tp]
\centering
\input{examples/ex6a.tex}
\caption{Finding configuration files}\label{fig:dvipsdbga}
\bigskip
\input{examples/ex6b.tex}
\caption{Finding the prolog file}\label{fig:dvipsdbgb}
\bigskip
\input{examples/ex6c.tex}
\caption{Finding the font file}\label{fig:dvipsdbgc}
\end{figure*}
\cmdname{dvips} starts by locating its working files. First,
\file{texmf.cnf} is found, which gives the definitions of the search
paths for the other files, then the file database \file{ls-R} (to
optimize file searching) and the file \file{aliases}, which makes it
possible to declare several names (e.g., a short \acro{DOS}-like 8.3 and
a more natural longer version) for the same file. Then \cmdname{dvips}
goes on to find the generic configuration file \file{config.ps}
before looking for the customization file \file{.dvipsrc} (which, in
this case is \emph{not found}). Finally, \cmdname{dvips} locates the
config file for the Computer Modern \PS{} fonts \file{config.cms}
(this was initiated with the \texttt{-Pcms} option on the \cmdname{dvips}
command). This file contains the list of the map files which
define the relation between the \TeX{}, \PS{} and file system
names of the fonts.
\begin{alltt}
> \Ucom{more /usr/local/texmf/dvips/cms/config.cms}
p +ams.map
p +cms.map
p +cmbkm.map
p +amsbkm.map
\end{alltt}
\cmdname{dvips} thus goes on to find all these files, plus the generic
map file \file{psfonts.map}, which is always loaded (it contains
declarations for commonly used \PS{} fonts; see the last part of
Section \ref{SExamplesofuse} for more details about \PS{} map
file handling).
At this point \cmdname{dvips} identifies itself to the user:
\begin{alltt}
This is dvips(k) 5.92b Copyright 2002 Radical Eye Software (www.radicaleye.com)
\end{alltt}
\ifSingleColumn
Then it goes on to look for the prolog file \file{texc.pro}:
\begin{alltt}\small
kdebug:start search(file=texc.pro, must\_exist=0, find\_all=0,
path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
kdebug:search(texc.pro) => /usr/local/texmf/dvips/base/texc.pro
\end{alltt}
\else
Then it goes on to look for the prolog file \file{texc.pro} (see
Figure~\ref{fig:dvipsdbgb}).
\fi
After having found the file in question, \cmdname{dvips} outputs
date and time, and informs us that it will generate the
file \file{hello-world.ps}, then that it needs the font file
\file{cmr10}, and that the latter is declared as ``resident'' (no
bitmaps needed):
\begin{alltt}\small
TeX output 1998.02.26:1204' -> hello-world.ps
Defining font () cmr10 at 10.0pt
Font cmr10 <CMR10> is resident.
\end{alltt}
Now the search is on for the file \file{cmr10.tfm}, which is found,
then a few more prolog files (not shown) are referenced, and finally
the Type~1 instance \file{cmr10.pfb} of the font is located and
included in the output file (see last line).
\begin{alltt}\small
kdebug:start search(file=cmr10.tfm, must\_exist=1, find\_all=0,
path=.:~/tex/fonts/tfm//:!!/usr/local/texmf/fonts/tfm//:
/var/tex/fonts/tfm//).
kdebug:search(cmr10.tfm) => /usr/local/texmf/fonts/tfm/public/cm/cmr10.tfm
kdebug:start search(file=texps.pro, must\_exist=0, find\_all=0,
...
<texps.pro>
kdebug:start search(file=cmr10.pfb, must\_exist=0, find\_all=0,
path=.:~/tex/dvips//:!!/usr/local/texmf/dvips//:
~/tex/fonts/type1//:!!/usr/local/texmf/fonts/type1//).
kdebug:search(cmr10.pfb) => /usr/local/texmf/fonts/type1/public/cm/cmr10.pfb
<cmr10.pfb>[1]
\end{alltt}
\subsection{Runtime options}
Another useful feature of \Webc{} is its possibility to control a number
of memory parameters (in particular, array sizes) via the runtime file
\file{texmf.cnf} read by \KPS{}. The memory settings can be found in
Part 3 of that file in the \TL{} distribution. The more important
are:
\begin{ttdescription}
\item[\texttt{main\_memory}]
Total words of memory available, for
\TeX{}, \MF{} and \MP. You must make a new format file for each
different setting. For instance, you could generate a ``huge''
version of \TeX{}, and call the format file \texttt{hugetex.fmt}.
Using the standard way of specifying the program name used by \KPS{},
the particular value of the \texttt{main\_memory} variable will then
be read from \file{texmf.cnf}.
\item[\texttt{extra\_mem\_bot}]
Extra space for ``large'' \TeX{} data structures:
boxes, glue, breakpoints, etc. Especially useful if you use
\PiCTeX{}.
\item[\texttt{font\_mem\_size}]
Number of words for font information available for \TeX. This
is more or less the total size of all TFM files read.
\item[\texttt{hash\_extra}]
Additional space for the hash table of control sequence names.
Approximately 10,000 control sequences can be stored in the main
hash table; if you have a large book with numerous cross-references,
this might not be enough. The default value of
\texttt{hash\_extra} is \texttt{50000}.
\end{ttdescription}
\noindent Of course, this facility is no substitute for truly dynamic
arrays and memory allocation, but since these are extremely difficult to
implement in the present \TeX{} source, these runtime parameters provide
a practical compromise allowing some flexibility.
\begin{comment}
\section{Building on a new Unix platform}
If you have a platform for which executables are not included, you will
need to compile \TeX{} and friends. This is not as hard as it
sounds. What you need is all in the directory \texttt{source} in the
distribution.
\subsection{Prerequisites}
You will need at least 100 megabytes of disk space to compile all of
\TeX{} and its support programs. You'll also need an \acro{ANSI} C
compiler, a \cmdname{make} utility, a lexical scanner, and a parser
generator. We recommend the \acro{GNU} version of these programs
(\cmdname{gcc}, \acro{GNU} \cmdname{make}, \cmdname{m4}, \cmdname{flex},
\cmdname{bison}). You may be able to work with other C compilers and
\cmdname{make} programs, but you will need a good understanding of
building Unix programs to sort out problems.
Also, the command \texttt{uname} must return a sensible value.
\subsection{Configuration}
To begin, perform a normal installation of \TL{} to your disk (see
section~\ref{sec:unix-install-disk} on
\p.\pageref{sec:unix-install-disk}). You may wish to skip installing
all of the prebuilt binaries.
Then, unpack the source from the compressed \texttt{tar} file in the
directory \dirname{source} to your disk and change directory to where
you placed it.
Next, run \cmdname{configure} with a command line like this:
\begin{alltt}
> \Ucom{sh configure -prefix=/usr/local/TeX}
\end{alltt}
The \optname{-prefix} directory is the one where you installed the
support tree; the directory layout will be as follows (where \$TEXDIR
stands for the directory you chose):
\noindent
\begin{tabular}{>{\ttfamily}ll@{}}
\dirname{$TEXDIR/share/texmf} & main tree with fonts,\\
& \qquad macros, etc\\
\dirname{$TEXDIR/man} & Unix manual pages\\
\dirname{$TEXDIR/info} & \acro{GNU} style Info manuals\\
\dirname{$TEXDIR/bin/$PLATFORM} & binaries\\
\end{tabular}
%$
If you want to leave out the \dirname{$PLATFORM} directory level,
i.e., put the binaries directly into \dirname{$TEXDIR/bin}, specify
the \verb|--disable-multiplatform| option to \cmdname{configure}.
Have a look at the output of \verb|./configure --help| for more
options you can use. For example, you can skip building of \OMEGA{} and
\eTeX{}.
\subsection{Running \cmdname{make}}
Make sure the shell variable or option \texttt{noclobber} is not set.
Then, run the main \cmdname{make} like this:
\begin{alltt}
> \Ucom{make world}
\end{alltt}
and relax\ldots
Alternatively, you want to log all the output, as in:
\begin{alltt}
> \Ucom{sh -c "make world >world.log 2>\&1" \&}
\end{alltt}
Before you believe that everything went ok, please check the log file
for errors: \acro{GNU} \cmdname{make} always uses the string \samp{***}
whenever a command fails. Also, check if all the programs were built:
\begin{alltt}
> \Ucom{cd \var{TEXDIR}/bin/\var{archname}}
> \Ucom{ls | wc}
\end{alltt}
The result should be over 200 (you can check the exact number with the
\dirname{bin} directory contents in the distribution).
If you need special privileges for \texttt{make install}, you can
separate the \samp{make world} into two different runs, like this:
\begin{alltt}
> \Ucom{make all}
> \Ucom{su}
> \Ucom{make install strip}
\end{alltt}
After you've installed your new binaries, you should follow the normal
post-installation procedures, given in section~\ref{sec:postinstall}
(\p.\pageref{sec:postinstall}).
Also, if you'd like to make your binaries available to others, please
contact us. We'll be happy to put them on the \TL\ web pages.
\end{comment}
|