|
4378
|
1 The code in the files |
|
|
2 |
|
|
3 liboctave/kpse.cc |
|
|
4 liboctave/kpse-xfns.h |
|
4406
|
5 liboctave/kpse-xfns.c |
|
4378
|
6 |
|
|
7 was adapted from the kpathsearch library. We don't use kpathsearch |
|
|
8 directly now because it has too many TeX-specific things that are not |
|
|
9 necessary for Octave, and it also does not implement all the special |
|
|
10 kinds of file searches that Octave needs (mainly for compatibility |
|
|
11 with Matlab). |
|
|
12 |
|
|
13 Original authors of the kpathsearch library |
|
|
14 ------------------------------------------- |
|
|
15 |
|
|
16 Karl Berry wrote all files not otherwise marked, with help from Kathryn |
|
|
17 Hargreaves on some of the original versions. |
|
|
18 |
|
|
19 Thomas Esser originated most of the MakeTeX... scripts. |
|
|
20 |
|
|
21 The brace expansion code in expand.c was written by Brian Fox and Chet |
|
|
22 Ramey for Bash, the GNU shell. |
|
|
23 |
|
|
24 The implementation of the link trick in pathsearch.c is taken from GNU |
|
|
25 find, implemented by David MacKenzie from Matthew Farwell's suggestion. |
|
|
26 |
|
|
27 Debugging |
|
|
28 --------- |
|
|
29 |
|
|
30 Kpathsea provides a number of runtime debugging options, detailed |
|
|
31 below by their names and corresponding numeric values. When the files |
|
|
32 you expect aren't being found, the thing to do is enable these options |
|
|
33 and examine the output. |
|
|
34 |
|
|
35 You can set these with some runtime argument (e.g., `-d') to the |
|
|
36 program; in that case, you should use the numeric values described in |
|
|
37 the program's documentation (which, for Dvipsk and Xdvik, are different |
|
|
38 than those below). It's best to give the `-d' (or whatever) option |
|
|
39 first, for maximal output. Dvipsk and Xdvik have additional |
|
|
40 program-specific debugging options as well. |
|
|
41 |
|
|
42 You can also set the environment variable `KPATHSEA_DEBUG'; in this |
|
|
43 case, you should use the numbers below. If you run the program under a |
|
|
44 debugger and set the variable `kpathsea_debug', also use the numbers |
|
|
45 below. |
|
|
46 |
|
|
47 In any case, by far the simplest value to use is `-1', which will |
|
|
48 turn on all debugging output. This is usually better than guessing |
|
|
49 which particular values will yield the output you need. |
|
|
50 |
|
|
51 Debugging output always goes to standard error, so you can redirect it |
|
|
52 easily. For example, in Bourne-compatible shells: |
|
|
53 dvips -d -1 ... 2>/tmp/debug |
|
|
54 |
|
|
55 It is sometimes helpful to run the standalone Kpsewhich utility |
|
|
56 (*note Invoking kpsewhich::.), instead of the original program. |
|
|
57 |
|
|
58 In any case, you can *not* use the *names* below; you must always use |
|
|
59 somebody's numbers. (Sorry.) To set more than one option, just sum |
|
|
60 the corresponding numbers. |
|
|
61 |
|
|
62 `KPSE_DEBUG_STAT (1)' |
|
|
63 Report `stat'(2) calls. This is useful for verifying that your |
|
|
64 directory structure is not forcing Kpathsea to do many additional |
|
|
65 file tests (*note Slow path searching::., and *note Subdirectory |
|
|
66 expansion::.). If you are using an up-to-date `ls-R' database |
|
|
67 (*note Filename database::.), this should produce no output unless |
|
|
68 a nonexistent file that must exist is searched for. |
|
|
69 |
|
|
70 `KPSE_DEBUG_HASH (2)' |
|
|
71 Report lookups in all hash tables: `ls-R' and `aliases' (*note |
|
|
72 Filename database::.); font aliases (*note Fontmap::.); and config |
|
|
73 file values (*note Config files::.). Useful when expected values |
|
|
74 are not being found, e.g.., file searches are looking at the disk |
|
|
75 instead of using `ls-R'. |
|
|
76 |
|
|
77 `KPSE_DEBUG_FOPEN (4)' |
|
|
78 Report file openings and closings. Especially useful when your |
|
|
79 system's file table is full, for seeing which files have been |
|
|
80 opened but never closed. In case you want to set breakpoints in a |
|
|
81 debugger: this works by redefining `fopen' (`fclose') to be |
|
|
82 `kpse_fopen_trace' (`kpse_fclose_trace'). |
|
|
83 |
|
|
84 `KPSE_DEBUG_PATHS (8)' |
|
|
85 Report general path information for each file type Kpathsea is |
|
|
86 asked to search. This is useful when you are trying to track down |
|
|
87 how a particular path got defined--from `texmf.cnf', `config.ps', |
|
|
88 an environment variable, the compile-time default, etc. This is |
|
|
89 the contents of the `kpse_format_info_type' structure defined in |
|
|
90 `tex-file.h'. |
|
|
91 |
|
|
92 `KPSE_DEBUG_EXPAND (16)' |
|
|
93 Report the directory list corresponding to each path element |
|
|
94 Kpathsea searches. This is only relevant when Kpathsea searches |
|
|
95 the disk, since `ls-R' searches don't look through directory lists |
|
|
96 in this way. |
|
|
97 |
|
|
98 `KPSE_DEBUG_SEARCH (32)' |
|
|
99 Report on each file search: the name of the file searched for, the |
|
|
100 path searched in, whether or not the file must exist (when drivers |
|
|
101 search for `cmr10.vf', it need not exist), and whether or not we |
|
|
102 are collecting all occurrences of the file in the path (as with, |
|
|
103 e.g., `texmf.cnf' and `texfonts.map'), or just the first (as with |
|
|
104 most lookups). This can help you correlate what Kpathsea is doing |
|
|
105 with what is in your input file. |
|
|
106 |
|
|
107 `KPSE_DEBUG_VARS (64)' |
|
|
108 Report the value of each variable Kpathsea looks up. This is |
|
|
109 useful for verifying that variables do indeed obtain their correct |
|
|
110 values. |
|
|
111 |
|
|
112 `GSFTOPK_DEBUG (128)' |
|
|
113 Activates debugging printout specific to `gsftopk' program. |
|
|
114 |
|
|
115 `MAKETEX_DEBUG (512)' |
|
|
116 If you use the optional `mktex' programs instead of the |
|
|
117 traditional shell scripts, this will report the name of the site |
|
|
118 file (`mktex.cnf' by default) which is read, directories created by |
|
|
119 `mktexdir', the full path of the `ls-R' database built by |
|
|
120 `mktexlsr', font map searches, `MT_FEATURES' in effect, parameters |
|
|
121 from `mktexnam', filenames added by `mktexupd', and some |
|
|
122 subsidiary commands run by the programs. |
|
|
123 |
|
|
124 `MAKETEX_FINE_DEBUG (1024)' |
|
|
125 When the optional `mktex' programs are used, this will print |
|
|
126 additional debugging info from functions internal to these |
|
|
127 programs. |
|
|
128 |
|
|
129 Debugging output from Kpathsea is always written to standard error, |
|
|
130 and begins with the string `kdebug:'. (Except for hash table buckets, |
|
|
131 which just start with the number, but you can only get that output |
|
|
132 running under a debugger. See comments at the `hash_summary_only' |
|
|
133 variable in `kpathsea/db.c'.) |
|
|
134 |
|
|
135 Logging |
|
|
136 ------- |
|
|
137 |
|
|
138 Kpathsea can record the time and filename found for each successful |
|
|
139 search. This may be useful in finding good candidates for deletion when |
|
|
140 your filesystem is full, or in discovering usage patterns at your site. |
|
|
141 |
|
|
142 To do this, define the environment or config file variable |
|
|
143 `TEXMFLOG'. The value is the name of the file to append the |
|
|
144 information to. The file is created if it doesn't exist, and appended |
|
|
145 to if it does. |
|
|
146 |
|
|
147 Each successful search turns into one line in the log file: two words |
|
|
148 separated by a space. The first word is the time of the search, as the |
|
|
149 integer number of seconds since "the epoch", i.e., UTC midnight 1 |
|
|
150 January 1970 (more precisely, the result of the `time' system call). |
|
|
151 The second word is the filename. |
|
|
152 |
|
|
153 For example, after `setenv TEXMFLOG /tmp/log', running Dvips on |
|
|
154 `story.dvi' appends the following lines: |
|
|
155 |
|
|
156 774455887 /usr/local/share/texmf/dvips/config.ps |
|
|
157 774455887 /usr/local/share/texmf/dvips/psfonts.map |
|
|
158 774455888 /usr/local/share/texmf/dvips/texc.pro |
|
|
159 774455888 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmbx10.600pk |
|
|
160 774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmsl10.600pk |
|
|
161 774455889 /usr/local/share/texmf/fonts/pk/ljfour/public/cm/cmr10.600pk |
|
|
162 774455889 /usr/local/share/texmf/dvips/texc.pro |
|
|
163 |
|
|
164 Only filenames that are absolute are recorded, to preserve some |
|
|
165 semblance of privacy. |
|
7088
|
166 |
|
|
167 |
|
|
168 John W. Eaton |
|
|
169 jwe@bevo.che.wisc.edu |
|
|
170 University of Wisconsin-Madison |
|
|
171 Department of Chemical & Biological Engineering |
|
|
172 |
|
|
173 Last updated: Wed, 31 Oct 2007 16:33:13 EDT |
