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
|
The code in the files
liboctave/kpse.cc
liboctave/kpse-xfns.h
liboctave/kpse-xfns.c
was adapted from the kpathsearch library. We don't use kpathsearch
directly now because it has too many TeX-specific things that are not
necessary for Octave, and it also does not implement all the special
kinds of file searches that Octave needs (mainly for compatibility
with Matlab).
Original authors of the kpathsearch library
-------------------------------------------
Karl Berry wrote all files not otherwise marked, with help from Kathryn
Hargreaves on some of the original versions.
Thomas Esser originated most of the MakeTeX... scripts.
The brace expansion code in expand.c was written by Brian Fox and Chet
Ramey for Bash, the GNU shell.
The implementation of the link trick in pathsearch.c is taken from GNU
find, implemented by David MacKenzie from Matthew Farwell's suggestion.
Debugging
---------
Kpathsea provides a number of runtime debugging options, detailed
below by their names and corresponding numeric values. When the files
you expect aren't being found, the thing to do is enable these options
and examine the output.
You can set these with some runtime argument (e.g., `-d') to the
program; in that case, you should use the numeric values described in
the program's documentation (which, for Dvipsk and Xdvik, are different
than those below). It's best to give the `-d' (or whatever) option
first, for maximal output. Dvipsk and Xdvik have additional
program-specific debugging options as well.
You can also set the environment variable `KPATHSEA_DEBUG'; in this
case, you should use the numbers below. If you run the program under a
debugger and set the variable `kpathsea_debug', also use the numbers
below.
In any case, by far the simplest value to use is `-1', which will
turn on all debugging output. This is usually better than guessing
which particular values will yield the output you need.
Debugging output always goes to standard error, so you can redirect it
easily. For example, in Bourne-compatible shells:
dvips -d -1 ... 2>/tmp/debug
It is sometimes helpful to run the standalone Kpsewhich utility
(*note Invoking kpsewhich::.), instead of the original program.
In any case, you can *not* use the *names* below; you must always use
somebody's numbers. (Sorry.) To set more than one option, just sum
the corresponding numbers.
`KPSE_DEBUG_STAT (1)'
Report `stat'(2) calls. This is useful for verifying that your
directory structure is not forcing Kpathsea to do many additional
file tests (*note Slow path searching::., and *note Subdirectory
expansion::.). If you are using an up-to-date `ls-R' database
(*note Filename database::.), this should produce no output unless
a nonexistent file that must exist is searched for.
`KPSE_DEBUG_HASH (2)'
Report lookups in all hash tables: `ls-R' and `aliases' (*note
Filename database::.); font aliases (*note Fontmap::.); and config
file values (*note Config files::.). Useful when expected values
are not being found, e.g.., file searches are looking at the disk
instead of using `ls-R'.
`KPSE_DEBUG_FOPEN (4)'
Report file openings and closings. Especially useful when your
system's file table is full, for seeing which files have been
opened but never closed. In case you want to set breakpoints in a
debugger: this works by redefining `fopen' (`fclose') to be
`kpse_fopen_trace' (`kpse_fclose_trace').
`KPSE_DEBUG_PATHS (8)'
Report general path information for each file type Kpathsea is
asked to search. This is useful when you are trying to track down
how a particular path got defined--from `texmf.cnf', `config.ps',
an environment variable, the compile-time default, etc. This is
the contents of the `kpse_format_info_type' structure defined in
`tex-file.h'.
`KPSE_DEBUG_EXPAND (16)'
Report the directory list corresponding to each path element
Kpathsea searches. This is only relevant when Kpathsea searches
the disk, since `ls-R' searches don't look through directory lists
in this way.
`KPSE_DEBUG_SEARCH (32)'
Report on each file search: the name of the file searched for, the
path searched in, whether or not the file must exist (when drivers
search for `cmr10.vf', it need not exist), and whether or not we
are collecting all occurrences of the file in the path (as with,
e.g., `texmf.cnf' and `texfonts.map'), or just the first (as with
most lookups). This can help you correlate what Kpathsea is doing
with what is in your input file.
`KPSE_DEBUG_VARS (64)'
Report the value of each variable Kpathsea looks up. This is
useful for verifying that variables do indeed obtain their correct
values.
`GSFTOPK_DEBUG (128)'
Activates debugging printout specific to `gsftopk' program.
`MAKETEX_DEBUG (512)'
If you use the optional `mktex' programs instead of the
traditional shell scripts, this will report the name of the site
file (`mktex.cnf' by default) which is read, directories created by
`mktexdir', the full path of the `ls-R' database built by
`mktexlsr', font map searches, `MT_FEATURES' in effect, parameters
from `mktexnam', filenames added by `mktexupd', and some
subsidiary commands run by the programs.
`MAKETEX_FINE_DEBUG (1024)'
When the optional `mktex' programs are used, this will print
additional debugging info from functions internal to these
programs.
Debugging output from Kpathsea is always written to standard error,
and begins with the string `kdebug:'. (Except for hash table buckets,
which just start with the number, but you can only get that output
running under a debugger. See comments at the `hash_summary_only'
variable in `kpathsea/db.c'.)
Logging
-------
Kpathsea can record the time and filename found for each successful
search. This may be useful in finding good candidates for deletion when
your filesystem is full, or in discovering usage patterns at your site.
To do this, define the environment or config file variable
`TEXMFLOG'. The value is the name of the file to append the
information to. The file is created if it doesn't exist, and appended
to if it does.
Each successful search turns into one line in the log file: two words
separated by a space. The first word is the time of the search, as the
integer number of seconds since "the epoch", i.e., UTC midnight 1
January 1970 (more precisely, the result of the `time' system call).
The second word is the filename.
For example, after `setenv TEXMFLOG /tmp/log', running Dvips on
`story.dvi' appends the following lines:
774455887 /usr/local/share/texmf/dvips/config.ps
774455887 /usr/local/share/texmf/dvips/psfonts.map
774455888 /usr/local/share/texmf/dvips/texc.pro
774455888 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmbx10.600pk
774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmsl10.600pk
774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk
774455889 /usr/local/share/texmf/dvips/texc.pro
Only filenames that are absolute are recorded, to preserve some
semblance of privacy.
|
