Debian Codegraph @

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

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\"
56 .\" Required to disable full justification in groff 1.23.0.
57 .if n .ds AD l
58 .\" ========================================================================
59 .\"
60 .IX Title "TEXFOT 1"
61 .TH TEXFOT 1 2026-01-05 texfot "Karl Berry"
62 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
63 .\" way too many mistakes in technical documents.
64 .if n .ad l
65 .nh
66 .SH NAME
67 texfot \- run TeX, filtering online transcript for interesting messages
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 texfot [\fIoption\fR]... \fItexcmd\fR [\fItexarg\fR...]
71 .SH DESCRIPTION
72 .IX Header "DESCRIPTION"
73 \&\f(CW\*(C`texfot\*(C'\fR invokes \fItexcmd\fR with the given \fItexarg\fR arguments,
74 filtering the online output for \`\`interesting\*(Aq\*(Aq messages. Its exit
75 value is that of \fItexcmd\fR. Examples:
76 .PP
77 .Vb 2
78 \& # Sample basic invocation:
79 \& texfot pdflatex file.tex
80 \&
81 \& # Ordinarily the full output is copied to /tmp/fot.$UID before
82 \& # filtering, but that can be omitted, or the filename changed:
83 \& texfot \-\-tee=/dev/null lualatex file.tex
84 \&
85 \& # Example of more complex engine invocation:
86 \& texfot xelatex \-\-recorder \*(Aq\enonstopmode\einput file\*(Aq
87 .Ve
88 .PP
89 Here is an example of what the output looks like (in its entirety) on an
90 error\-free run:
91 .PP
92 .Vb 3
93 \& /path/to/texfot: invoking: pdflatex hello.ltx
94 \& This is pdfTeX, Version 3.141592653\-2.6\-1.40.24 (TeX Live 2022) (preloaded format=pdflatex)
95 \& Output written on hello.pdf (1 page, 94415 bytes).
96 .Ve
97 .PP
98 Aside from its own options, described below, \f(CW\*(C`texfot\*(C'\fR just runs the
99 given command with the given arguments (same approach to command line
100 syntax as \f(CW\*(C`env\*(C'\fR, \f(CW\*(C`nice\*(C'\fR, \f(CW\*(C`timeout\*(C'\fR, etc.). Thus, \f(CW\*(C`texfot\*(C'\fR works with
101 any engine and any command line options.
102 .PP
103 \&\f(CW\*(C`texfot\*(C'\fR does not look at the log file or any other possible output
104 file(s); it only looks at the standard output and standard error from
105 the command. stdout is processed first, then stderr. \f(CW\*(C`texfot\*(C'\fR writes
106 all accepted lines to its stdout.
107 .PP
108 The messages shown are intended to be those which likely need action by
109 the author: error messages, overfull and underfull boxes, undefined
110 citations, missing characters from fonts, etc.
111 .SH "FLOW OF OPERATION"
112 .IX Header "FLOW OF OPERATION"
113 Here is the order in which lines of output are checked:
114 .IP 1. 4
115 If the \`\`next line\*(Aq\*(Aq needs to be printed (see below), print it.
116 .IP 2. 4
117 Otherwise, if the line matches any user\-supplied list of regexps to
118 accept (given with \f(CW\*(C`\-\-accept\*(C'\fR, see below), in that order, print it.
119 .IP 3. 4
120 Otherwise, if the line matches the built\-in list of regexps to ignore,
121 or any user\-supplied list of regexps to ignore (given with \f(CW\*(C`\-\-ignore\*(C'\fR,
122 see below), in that order, ignore it.
123 .IP 4. 4
124 Otherwise, if the line matches the list of regexps for which the next
125 line (two lines in all) should be shown, show this line and set the
126 \&\`\`next line\*(Aq\*(Aq flag for the next time around the loop. Examples are the
127 common \f(CW\*(C`!\*(C'\fR and \f(CW\*(C`filename:lineno:\*(C'\fR error messages, which are generally
128 followed by a line with specific detail about the error.
129 .IP 5. 4
130 Otherwise, if the line matches the list of regexps to show, show it.
131 .IP 6. 4
132 Otherwise, the default: if the line came from stdout, ignore it; if the
133 line came from stderr, print it (to stdout), with the prefix
134 \&\f(CW\*(C`[stderr]\ \*(C'\fR. This distinction is made because TeX engines write
135 relatively few messages to stderr, and it\*(Aqs likely that any such should
136 be considered.
137 .PP
138 Once a particular check matches, the program moves on to process the
139 next line.
140 .PP
141 \&\f(CW\*(C`texfot\*(C'\fR matches exclusively line\-by\-line; however, TeX itself folds
142 output lines, typically at column 79. This means matches might fail
143 because the text being matched was split over two lines. To work around
144 this, you can effectively turn off TeX\*(Aqs folding by setting the
145 \&\f(CW\*(C`max_print_line\*(C'\fR parameter to a large number, either in the environment
146 or on the command:
147 .PP
148 .Vb 2
149 \& # When errors are missed due to TeX\*(Aqs folding of lines:
150 \& texfot pdftex \-\-cnf\-line max_print_line=999 file.tex
151 \&
152 \& # Equivalently:
153 \& env max_print_line=999 texfot pdftex file.tex
154 .Ve
155 .PP
156 Don\*(Aqt hesitate to peruse the source to the script, which is essentially
157 a straightforward loop matching against the different lists as above.
158 You can see the exact regexps being matched in the different categories
159 in the source.
160 .PP
161 Incidentally, although nothing in this basic operation is specific to
162 TeX engines, all the regular expressions included in the program are
163 specific to TeX. So in practice the program isn\*(Aqt useful except with TeX
164 engines, although it would be easy enough to adapt it (if there was
165 anything else as verbose as TeX to make that useful).
166 .SH OPTIONS
167 .IX Header "OPTIONS"
168 The following are the options to \f(CW\*(C`texfot\*(C'\fR itself (not the TeX engine
169 being invoked; consult the engine documentation or \f(CW\*(C`\-\-help\*(C'\fR output for
170 that).
171 .PP
172 The first non\-option terminates \f(CW\*(C`texfot\*(C'\fR\*(Aqs option parsing, and the
173 remainder of the command line is invoked as the TeX command, without
174 further parsing. For example, \f(CW\*(C`texfot \-\-debug tex
175 \&\-\-debug\*(C'\fR will output debugging information from both \f(CW\*(C`texfot\*(C'\fR and
176 \&\f(CW\*(C`tex\*(C'\fR. TeX engines, unlike many standard programs, require that options
177 be specified before the input filename or text.
178 .PP
179 Options may start with either \- or \-\-, and may be unambiguously
180 abbreviated. It is best to use the full option name in scripts, though,
181 to avoid possible collisions with new options in the future.
182 .ie n .IP """\-\-accept"" \fIregexp\fR" 4
183 .el .IP "\f(CW\-\-accept\fR \fIregexp\fR" 4
184 .IX Item "--accept regexp"
185 Accept lines in the TeX output matching (Perl) \fIregexp\fR. Can be
186 repeated. This list is checked first, so any and all matches will be
187 shown, regardless of other options. These regexps are not automatically
188 anchored (or otherwise altered), simply used as\-is.
189 .ie n .IP """\-\-debug""" 4
190 .el .IP \f(CW\-\-debug\fR 4
191 .IX Item "--debug"
192 .PD 0
193 .ie n .IP """\-\-no\-debug""" 4
194 .el .IP \f(CW\-\-no\-debug\fR 4
195 .IX Item "--no-debug"
196 .PD
197 Output (or not) what the program is doing to standard error; off by default.
198 .ie n .IP """\-\-ignore"" \fIregexp\fR" 4
199 .el .IP "\f(CW\-\-ignore\fR \fIregexp\fR" 4
200 .IX Item "--ignore regexp"
201 Ignore lines in the TeX output matching (Perl) \fIregexp\fR. Can be
202 repeated. Adds to the default set of ignore regexps rather than
203 replacing. Like the acceptance regexps, these are not automatically
204 anchored (or otherwise altered).
205 .ie n .IP """\-\-interactive""" 4
206 .el .IP \f(CW\-\-interactive\fR 4
207 .IX Item "--interactive"
208 .PD 0
209 .ie n .IP """\-\-no\-interactive""" 4
210 .el .IP \f(CW\-\-no\-interactive\fR 4
211 .IX Item "--no-interactive"
212 .PD
213 By default, standard input to the TeX process is closed so that TeX\*(Aqs
214 interactive mode (waiting for input upon error, the \f(CW\*(C`*\*(C'\fR prompt, etc.)
215 is never entered. Giving \f(CW\*(C`\-\-interactive\*(C'\fR allows interaction to happen.
216 .ie n .IP """\-\-quiet""" 4
217 .el .IP \f(CW\-\-quiet\fR 4
218 .IX Item "--quiet"
219 .PD 0
220 .ie n .IP """\-\-no\-quiet""" 4
221 .el .IP \f(CW\-\-no\-quiet\fR 4
222 .IX Item "--no-quiet"
223 .PD
224 By default, the TeX command being invoked is reported on standard
225 output; \f(CW\*(C`\-\-quiet\*(C'\fR omits that reporting. To get a completely silent run,
226 redirect standard output: \f(CW\*(C`texfot\ ...\ >/dev/null\*(C'\fR. (The only
227 messages to standard error should be errors from \f(CW\*(C`texfot\*(C'\fR itself, so it
228 shouldn\*(Aqt be necessary to redirect that, but of course that could be
229 done as well.)
230 .ie n .IP """\-\-stderr""" 4
231 .el .IP \f(CW\-\-stderr\fR 4
232 .IX Item "--stderr"
233 .PD 0
234 .ie n .IP """\-\-no\-stderr""" 4
235 .el .IP \f(CW\-\-no\-stderr\fR 4
236 .IX Item "--no-stderr"
237 .PD
238 The default is for \f(CW\*(C`texfot\*(C'\fR to report everything written to stderr by
239 the TeX command (on stdout). \f(CW\*(C`\-\-no\-stderr\*(C'\fR omits that reporting. (Some
240 programs, \f(CW\*(C`dvisvgm\*(C'\fR is one, can be rather verbose on stderr.)
241 .ie n .IP """\-\-tee"" \fIfile\fR" 4
242 .el .IP "\f(CW\-\-tee\fR \fIfile\fR" 4
243 .IX Item "--tee file"
244 By default, the output being filtered is \f(CW\*(C`tee\*(C'\fR\-ed, before filtering, to
245 make it easy to check the full output in case of problems.
246 .Sp
247 The default \fIfile\fR is \f(CW\*(C`$TMPDIR/fot.\*(C'\fR\fIuid\fR; if \f(CW\*(C`TMPDIR\*(C'\fR is not set,
248 \&\f(CW\*(C`TMP\*(C'\fR is used if set; if neither is set, the default directory is
249 \&\f(CW\*(C`/tmp\*(C'\fR. For example: \f(CW\*(C`/tmp/fot.1001\*(C'\fR. The \fIuid\fR suffix is the
250 effective userid of the process, appended for basic avoidance of
251 collisions between different users on the same system.
252 .Sp
253 This option allows specifying a different file. Use \f(CW\*(C`\-\-tee\ /dev/null\*(C'\fR to discard the original output.
254 .ie n .IP """\-\-version""" 4
255 .el .IP \f(CW\-\-version\fR 4
256 .IX Item "--version"
257 Output version information and exit successfully.
258 .ie n .IP """\-\-help""" 4
259 .el .IP \f(CW\-\-help\fR 4
260 .IX Item "--help"
261 Display this help and exit successfully.
262 .SH RATIONALE
263 .IX Header "RATIONALE"
264 I wrote this because, in my work as a TUGboat editor
265 (<https://tug.org/TUGboat>, article submissions always welcome!), I run
266 and rerun many documents, many times each. It was easy to lose warnings
267 I needed to see in the mass of unvarying and uninteresting output from
268 TeX, such as style files being read and fonts being used. I wanted to
269 see all and only those messages which needed some action by me.
270 .PP
271 I found some other programs of a similar nature, the LaTeX package
272 \&\f(CW\*(C`silence\*(C'\fR, and plenty of other (La)TeX wrappers, but it seemed none of
273 them did what I wanted. Either they read the log file (I wanted to look
274 at only the online output), or they output more, or less, than I wanted,
275 or they required invoking TeX differently (I wanted to keep my build
276 process exactly the same, most critically the TeX invocation, which can
277 get complicated). Hence I wrote this little script.
278 .PP
279 Here are some keywords if you want to explore other options:
280 texloganalyser, pydflatex, logfilter, latexmk, rubber, arara, and
281 searching for \f(CW\*(C`log\*(C'\fR at <https://ctan.org/search>.
282 .PP
283 \&\f(CW\*(C`texfot\*(C'\fR is written in Perl, and runs on Unix. It may work on Windows
284 if Perl and other software is installed, but I don\*(Aqt use Windows and
285 don\*(Aqt support \f(CW\*(C`texfot\*(C'\fR there.
286 .PP
287 The name comes from the \f(CW\*(C`trip.fot\*(C'\fR and \f(CW\*(C`trap.fot\*(C'\fR files that are part
288 of Knuth\*(Aqs trip and trap torture tests, which record the online output
289 from the programs. I am not sure what "fot" stands for in trip and trap,
290 but I can pretend that it stands for "filter online transcript" in the
291 present case\ :).
292 .SH "AUTHORS AND COPYRIGHT"
293 .IX Header "AUTHORS AND COPYRIGHT"
294 This script and its documentation were written by Karl Berry and both
295 are released to the public domain. Email \f(CW\*(C`[email protected]\*(C'\fR with
296 bug reports. It has no home page beyond the package page on CTAN:
297 <https://ctan.org/pkg/texfot>.
298 .PP
299 .Vb 1
300 \& $Id: texfot,v 1.54 2026/01/05 17:14:08 karl Exp $
301 .Ve