1TEXFOT(1) Karl Berry TEXFOT(1)
2
6 texfot - run TeX, filtering online transcript for interesting messages
7
9 texfot [option]... texcmd [texarg...]
10
12 "texfot" invokes texcmd with the given texarg arguments, filtering the
13 online output for ``interesting'' messages. Its exit value is that of
14 texcmd. Examples:
15 # Sample basic invocation:
17 texfot pdflatex file.tex
18 # Ordinarily the full output is copied to /tmp/fot.$UID before
20 # filtering, but that can be omitted, or the filename changed:
21 texfot --tee=/dev/null lualatex file.tex
22 # Example of more complex engine invocation:
24 texfot xelatex --recorder '\nonstopmode\input file'
25 Here is an example of what the output looks like (in its entirety) on
27 an error-free run:
28 /path/to/texfot: invoking: pdflatex hello.ltx
30 This is pdfTeX, Version 3.141592653-2.6-1.40.24 (TeX Live 2022) (preloaded format=pdflatex)
31 Output written on hello.pdf (1 page, 94415 bytes).
32 Aside from its own options, described below, "texfot" just runs the
34 given command with the given arguments (same approach to command line
35 syntax as "env", "nice", "timeout", etc.). Thus, "texfot" works with
36 any engine and any command line options.
37 "texfot" does not look at the log file or any other possible output
39 file(s); it only looks at the standard output and standard error from
40 the command. stdout is processed first, then stderr. Lines from stderr
41 have an identifying prefix. "texfot" writes all accepted lines to its
42 stdout.
43 The messages shown are intended to be those which likely need action by
45 the author: error messages, overfull and underfull boxes, undefined
46 citations, missing characters from fonts, etc.
47
49 Here is the order in which lines of output are checked:
50 1. If the ``next line'' needs to be printed (see below), print it.
52 2. Otherwise, if the line matches any user-supplied list of regexps to
54 accept (given with "--accept", see below), in that order, print it.
55 3. Otherwise, if the line matches the built-in list of regexps to
57 ignore, or any user-supplied list of regexps to ignore (given with
58 "--ignore", see below), in that order, ignore it.
59 4. Otherwise, if the line matches the list of regexps for which the
61 next line (two lines in all) should be shown, show this line and
62 set the ``next line'' flag for the next time around the loop.
63 Examples are the common "!" and "filename:lineno:" error messages,
64 which are generally followed by a line with specific detail about
65 the error.
66 5. Otherwise, if the line matches the list of regexps to show, show
68 it.
69 6. Otherwise, the default: if the line came from stdout, ignore it; if
71 the line came from stderr, print it (to stdout). This distinction
72 is made because TeX engines write relatively few messages to
73 stderr, and it's likely that any such should be considered.
74 Once a particular check matches, the program moves on to process the
76 next line.
77 Don't hesitate to peruse the source to the script, which is essentially
79 a straightforward loop matching against the different lists as above.
80 You can see the exact regexps being matched in the different categories
81 in the source.
82 Incidentally, although nothing in this basic operation is specific to
84 TeX engines, all the regular expressions included in the program are
85 specific to TeX. So in practice the program isn't useful except with
86 TeX engines, although it would be easy enough to adapt it (if there was
87 anything else as verbose as TeX to make that useful).
88
90 The following are the options to "texfot" itself (not the TeX engine
91 being invoked; consult the TeX documentation or the engine's "--help"
92 output for that).
93 The first non-option terminates "texfot"'s option parsing, and the
95 remainder of the command line is invoked as the TeX command, without
96 further parsing. For example, "texfot --debug tex --debug" will output
97 debugging information from both "texfot" and "tex".
98 Options may start with either - or --, and may be unambiguously
100 abbreviated. It is best to use the full option name in scripts, though,
101 to avoid possible collisions with new options in the future.
102 "--accept" regexp
104 Accept lines in the TeX output matching (Perl) regexp. Can be
105 repeated. This list is checked first, so any and all matches will
106 be shown, regardless of other options. These regexps are not
107 automatically anchored (or otherwise altered), simply used as-is.
108 "--debug"
110 "--no-debug"
111 Output (or not) what the program is doing to standard error; off by
112 default.
113 "--ignore" regexp
115 Ignore lines in the TeX output matching (Perl) regexp. Can be
116 repeated. Adds to the default set of ignore regexps rather than
117 replacing. Like the acceptance regexps, these are not automatically
118 anchored (or otherwise altered).
119 "--interactive"
121 "--no-interactive"
122 By default, standard input to the TeX process is closed so that
123 TeX's interactive mode (waiting for input upon error, the "*"
124 prompt, etc.) is never entered. Giving "--interactive" allows
125 interaction to happen.
126 "--quiet"
128 "--no-quiet"
129 By default, the TeX command being invoked is reported on standard
130 output. "--quiet" omits that reporting. To get a completely silent
131 run, redirect standard output: "texfot ... >/dev/null". (The only
132 messages to standard error should be errors from "texfot" itself,
133 so it shouldn't be necessary to redirect that, but of course that
134 can be done as well.)
135 "--stderr"
137 "--no-stderr"
138 The default is for "texfot" to report everything written to stderr
139 by the TeX command (on stdout). "--no-stderr" omits that reporting.
140 (Some programs, "dvisvgm" is one, can be rather verbose on stderr.)
141 "--tee" file
143 By default, the output being filtered is "tee"-ed, before
144 filtering, to make it easy to check the full output in case of
145 problems.
146 The default file is "$TMPDIR/fot."uid; if "TMPDIR" is not set,
148 "TMP" is used if set; if neither is set, the default directory is
149 "/tmp". For example: "/tmp/fot.1001". The uid suffix is the
150 effective userid of the process, appended for basic avoidance of
151 collisions between different users on the same system.
152 This option allows specifying a different file. Use
154 "--tee /dev/null" to discard the original output.
155 "--version"
157 Output version information and exit successfully.
158 "--help"
160 Display this help and exit successfully.
161
163 I wrote this because, in my work as a TUGboat editor
164 (<https://tug.org/TUGboat>, journal submissions always welcome!), I run
165 and rerun many documents, many times each. It was easy to lose warnings
166 I needed to see in the mass of unvarying and uninteresting output from
167 TeX, such as style files being read and fonts being used. I wanted to
168 see all and only those messages which needed some action by me.
169 I found some other programs of a similar nature, the LaTeX package
171 "silence", and plenty of other (La)TeX wrappers, but it seemed none of
172 them did what I wanted. Either they read the log file (I wanted to look
173 at only the online output), or they output more or less than I wanted,
174 or they required invoking TeX differently (I wanted to keep my build
175 process exactly the same, most critically the TeX invocation, which can
176 get complicated). Hence I wrote this little script.
177 Here are some keywords if you want to explore other options:
179 texloganalyser, pydflatex, logfilter, latexmk, rubber, arara, and
180 searching for "log" at <https://ctan.org/search>.
181 "texfot" is written in Perl, and runs on Unix. It may work on Windows
183 if Perl and other software is installed, but I don't use Windows and
184 don't support "texfot" there.
185 The name comes from the "trip.fot" and "trap.fot" files that are part
187 of Knuth's trip and trap torture tests, which record the online output
188 from the programs. I am not sure what "fot" stands for in trip and
189 trap, but I can pretend that it stands for "filter online transcript"
190 in the present case :).
191
193 This script and its documentation were written by Karl Berry and both
194 are released to the public domain. Email "karl@freefriends.org" with
195 bug reports. It has no home page beyond the package page on CTAN:
196 <https://ctan.org/pkg/texfot>.
197 $Id: texfot,v 1.47 2022/09/24 16:38:13 karl Exp $
199texfot 2022-09-24 TEXFOT(1)