Debian Codegraph @

texmf-dist/doc/man/man1/texprof.1

raw
1 .TH TEXPROF 1 "2 September 2024" "Version 1.0"
2 .\"=====================================================================
3 .if n .ds MF Metafont
4 .if t .ds MF Metafont
5 .if t .ds TX \fRT\\h'-0.1667m'\\v'0.20v'E\\v'-0.20v'\\h'-0.125m'X\fP
6 .if n .ds TX TeX
7 .ie t .ds OX \fIT\v'+0.25m'E\v'-0.25m'X\fP
8 .el .ds OX TeX
9 .\" BX definition must follow TX so BX can use TX
10 .if t .ds BX \fRB\s-2IB\s0\fP\*(TX
11 .if n .ds BX BibTeX
12 .\" LX definition must follow TX so LX can use TX
13 .if t .ds LX \fRL\\h'-0.36m'\\v'-0.15v'\s-2A\s0\\h'-0.15m'\\v'0.15v'\fP\*(TX
14 .if n .ds LX LaTeX
15 .if t .ds AX \fRA\\h'-0.1667m'\\v'0.20v'M\\v'-0.20v'\\h'-0.125m'S\fP\*(TX
16 .if n .ds AX AmSTeX
17 .if t .ds AY \fRA\\h'-0.1667m'\\v'0.20v'M\\v'-0.20v'\\h'-0.125m'S\fP\*(LX
18 .if n .ds AY AmSLaTeX
19 .if n .ds WB Web
20 .if t .ds WB W\s-2EB\s0
21 .\"=====================================================================
22 .SH NAME
23 texprof \- A profiler for TeX source files
24 .SH SYNOPSIS
25 .B texprof
26 .RI [ options ]
27 .RI [ \fB&\fPformat ]
28 .RI [ file | \fB\e\fPcommands ]
29 .\"=====================================================================
30 .SH DESCRIPTION
31 Run the \*(TX profiler on
32 .IR file ,
33 usually creating
34 .IR file.dvi
35 and
36 .IR file.tprof .
37 If the
38 .IR file
39 argument has no extension, ".tex" will be appended to it.
40 Instead of a file name, a list of \*(TX commands can be given, the first
41 of which must start with a backslash.
42 With a
43 .BI & format
44 argument, the \*(TX profiler uses a different set of precompiled commands,
45 contained in
46 .IR format\fB.fmt\fP ;
47 it is usually better to use the
48 .B -fmt
49 .I format
50 option instead.
51 .PP
52 The \*(TX profiler is a version of \*(TX that measures the time
53 \*(TX needs to execute individual input lines or macros.
54 It writes the collected data to a file with extension
55 .IR .tprof .
56 A separate program,
57 .B texprofile
58 (see
59 .BR texprofile (1)),
60 is used to display the content of a
61 .IR .tprof
62 file in a readable form.
63
64 .PP
65 The typical use of the \*(TX profiler is with pre generated formats.
66 The
67 .B texprof
68 command uses the equivalent of the plain \*(TX format, and the
69 .B latexprof
70 command uses the equivalent of the \*(LX format. To investigate
71 the timing of macros targeted to
72 .B pdftex
73 or
74 .B pdflatex,
75 you can use
76 .B pdftexprof
77 or
78 .B pdflatexprof.
79
80 .PP
81 The \*(TX profiler's handling of its command-line arguments is similar
82 to that of the other \*(TX programs in the
83 .I web2c
84 implementation.
85
86 .\"=====================================================================
87 .SH OPTIONS
88 This version of the \*(TX profiler understands the following command line
89 options.
90 .TP
91 .BI -cnf-line \ string
92 Parse
93 .I string
94 as a
95 .I texmf.cnf
96 configuration line. See the Kpathsea manual.
97 .TP
98 .B -etex
99 Enable the e-\*(TX extensions. This option is only effective in
100 combination with
101 .BR -ini .
102 See
103 .BR etex (1).
104 .TP
105 .B -file-line-error
106 Print error messages in the form
107 .I file:line:error
108 which is similar to the way many compilers format them.
109 .TP
110 .B -no-file-line-error
111 Disable printing error messages in the
112 .I file:line:error
113 style.
114 .TP
115 .BI -fmt \ format
116 Use
117 .I format
118 as the name of the format to be used, instead of the name by which
119 the \*(TX profiler was called or a
120 .I %&
121 line.
122 .TP
123 .B -help
124 Print help message and exit.
125 .TP
126 .B -ini
127 Start in
128 .I INI
129 mode, which is used to dump formats. The
130 .I INI
131 mode can be used for typesetting, but no format is preloaded, and
132 basic initializations like setting catcodes may be required.
133 .TP
134 .BI -interaction \ mode
135 Sets the interaction mode. The mode can be either
136 .IR batchmode ,
137 .IR nonstopmode ,
138 .IR scrollmode ,
139 and
140 .IR errorstopmode .
141 The meaning of these modes is the same as that of the corresponding
142 \ecommands.
143 .TP
144 .BI -jobname \ name
145 Use
146 .I name
147 for the job name, instead of deriving it from the name of the input file.
148 .TP
149 .BI -kpathsea-debug \ bitmask
150 Sets path searching debugging flags according to the bitmask. See the
151 .I Kpathsea
152 manual for details.
153 .TP
154 .B -ltx
155 Enable the \*(LX extensions. This option is only effective in
156 combination with
157 .BR -ini .
158 See
159 .BR latex (1).
160 .TP
161 .BI -mktex \ fmt
162 Enable
163 .RI mktex fmt ,
164 where
165 .I fmt
166 must be either
167 .IR tex ,
168 .IR tfm ,
169 .IR fmt ,
170 or
171 .IR pk .
172 .TP
173 .BI -no-mktex \ fmt
174 Disable
175 .RI mktex fmt ,
176 where
177 .I fmt
178 must be either
179 .IR tex ,
180 .IR tfm ,
181 .IR fmt ,
182 or
183 .IR pk .
184 .TP
185 .BI -output-directory \ directory
186 Write output files in
187 .I directory
188 instead of the current directory. Look up input files in
189 .I directory
190 first, then along the normal search path.
191 .TP
192 .B -parse-first-line
193 If the first line of the main input file begins with
194 .I %&
195 parse it to look for a dump name.
196 .TP
197 .B -no-parse-first-line
198 Disable parsing of the first line of the main input file.
199 .TP
200 .B -pdf
201 Enable the simulation of common
202 .B pdftex
203 primitives. This option requires the
204 .BR -ini
205 option and implies the
206 .BR -ltx
207 option.
208 See
209 .BR pdftex (1).
210 .TP
211 .B -prof
212 Enable profiling as soon as \*(TX enters the main loop. If tis option
213 it not used, profiling needs to switched on using the \eprofileon
214 primitive. Profiling can be switched of with the \eprofileoff
215 primitive.
216 .TP
217 .BI -progname \ name
218 Pretend to be program
219 .IR name .
220 This affects both the format used and the search paths.
221 .TP
222 .B -version
223 Print version information and exit.
224 .\"=====================================================================
225 .SH ENVIRONMENT
226 See the Kpathsea library documentation (e.g., the `Path specifications'
227 node) for precise details of how the environment variables are used.
228 The
229 .B kpsewhich
230 utility can be used to query the values of the variables.
231 .PP
232 .TP
233 .B TEXMFOUTPUT
234 Normally, \*(TX puts its output files in the current directory. If
235 any output file cannot be opened there, it tries to open it in the
236 directory specified in the environment variable TEXMFOUTPUT.
237 There is no default value for that variable. For example, if you say
238 .I texprof paper
239 and the current directory is not writable and TEXMFOUTPUT has
240 the value
241 .IR /tmp ,
242 \*(TX attempts to create
243 .I /tmp/paper.log ,
244 .I /tmp/paper.dvi ,
245 and
246 .I /tmp/paper.tprof .
247 TEXMFOUTPUT is also checked for input
248 files, as \*(TX often generates files that need to be subsequently
249 read; for input, no suffixes (such as ``.tex'') are added by default,
250 the input name is simply checked as given.
251 .TP
252 .B TEXINPUTS
253 Search path for
254 .I \einput
255 and
256 .I \eopenin
257 files.
258 This normally starts with ``.'', so
259 that user files are found before system files. An empty path
260 component will be replaced with the paths defined in the
261 .I texmf.cnf
262 file. For example, set TEXINPUTS to ".:/home/user/tex:" to prepend the
263 current directory and ``/home/user/tex'' to the standard search path.
264 .TP
265 .B TEXFORMATS
266 Search path for format files.
267 .TP
268 .B TFMFONTS
269 Search path for font metric
270 .RI ( .tfm )
271 files.
272 .TP
273 .B SOURCE_DATE_EPOCH
274 If set, its value, taken to be in epoch-seconds, will be used for the
275 creation date and as the reference moment for the time related
276 primitives of \*(LX. This is useful for making reproducible builds.
277 .TP
278 .B FORCE_SOURCE_DATE
279 If set to the value "1", the time-related \*(TX primitives
280 .RI ( \eyear ,
281 .IR \emonth ,
282 .IR \eday ,
283 .IR \etime )
284 are also initialized from the value of SOURCE_DATE_EPOCH. This is not
285 recommended if there is any viable alternative.
286 .PP
287 Many, many more environment variables may be consulted related to path
288 searching. See the Kpathsea manual.
289 .\"=====================================================================
290 .SH FILES
291 The location of the files mentioned below varies from system to
292 system. Use the
293 .B kpsewhich
294 utility to find their locations.
295 .TP
296 .I *.tfm
297 Metric files for \*(TX's fonts.
298 .TP
299 .I *.fmt
300 Predigested \*(TX format files.
301 .TP
302 .I *.pk *.pfb
303 Font files used by \*(TX.
304 .\"=====================================================================
305 .SH NOTES
306 This manual page is not meant to be exhaustive. The complete
307 documentation for the \*(TX profiler can be found in
308 .IR texprof.pdf .
309 Further information can be found in the manual of the
310 .IR "Kpathsea library" .
311 .\"=====================================================================
312 .SH BUGS
313 This version of the \*(TX profiler does not implement all of the
314 primitives that pdftex provides, and further, it will not produce
315 the same side effects.
316 .\"=====================================================================
317 .SH AVAILABILITY
318 The \*(TX profiler should compile on a large variety of machine architectures
319 and operating systems. The function to obtain timing information id POSIX
320 specific.
321 .PP
322 The sources of the \*(TX profiler are hosted at
323 .BR https://github.com/ruckertm/HINT
324 .\"=====================================================================
325 .SH "SEE ALSO"
326 .BR texprofiler (1),
327 .BR tex (1),
328 .BR latex (1),
329 .BR pdftex (1),
330 .BR pdflatex (1), and
331 .BR kpsewhich (1).
332 .\"=====================================================================
333 .SH AUTHORS
334 The primary author of the \*(TX profiler is Martin Ruckert,
335 with e\*(TX extensions by Peter Breitenlohner,
336 \*(LX extensions by Thierry Laronde,
337 and
338 the kpathsearch library by Karl Berry.
339 .PP
340 \*(TX was designed by Donald E. Knuth,
341 who implemented it using his \*(WB system for Pascal programs.
342 .PP
343 Many, many more contributed to the typesetting system now known as \*(TX;
344 far too many to name all of them here.
345 .\" vim: syntax=nroff