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 all output is copied to /tmp/fot before filtering;
20 # that can be omitted:
21 texfot pdflatex --tee=/dev/null file.tex
22 # Example of more complex engine invocation:
24 texfot lualatex --recorder '\nonstopmode\input file'
25 Aside from its own options, described below, "texfot" just runs the
27 given command with the given arguments (same approach to command line
28 syntax as "env", "nice", "time", "timeout", etc.). Thus, "texfot"
29 works with any engine and any command line options.
30 "texfot" does not look at the log file or any other possible output
32 file(s); it only looks at the standard output and standard error from
33 the command. stdout is processed first, then stderr. Lines from
34 stderr have an identifying prefix. "texfot" writes all accepted lines
35 to its stdout.
36 The messages shown are intended to be those which likely need action by
38 the author: error messages, overfull and underfull boxes, undefined
39 citations, missing characters from fonts, etc.
40
42 Here is the order in which lines of output are checked:
43 1. If the ``next line'' needs to be printed (see below), print it.
45 2. Otherwise, if the line matches the built-in list of regexps to
47 ignore, or any user-supplied list of regexps to ignore (given with
48 "--ignore", see below), in that order, ignore it.
49 3. Otherwise, if the line matches the list of regexps for which the
51 next line (two lines in all) should be shown, show this line and
52 set the ``next line'' flag for the next time around the loop.
53 Examples are the common "!" and "filename:lineno:" error messages,
54 which are generally followed by a line with specific detail about
55 the error.
56 4. Otherwise, if the line matches the list of regexps to show, show
58 it.
59 5. Otherwise, the default: if the line came from stdout, ignore it; if
61 the line came from stderr, print it (to stdout). (This distinction
62 is made because TeX engines write relatively few messages to
63 stderr, and it's not unlikely that any such should be considered.
64 It would be easy to add more options to allow for user additions to
66 the various regex lists, if that ever seems useful. Or email me
67 (see end).
68 Once a particular check matches, the program moves on to process the
70 next line.
71 Don't hesitate to peruse the source to the script, which is essentially
73 a straightforward loop matching against the different lists as above.
74 You can see the exact regexps being matched in the different categories
75 in the source.
76 Incidentally, although nothing in this basic operation is specific to
78 TeX engines, all the regular expressions included in the program are
79 specific to TeX. So in practice the program isn't useful except with
80 TeX engines, although it would be easy enough to adapt it (if there was
81 anything else as verbose as TeX to make that useful).
82
84 The following are the options to "texfot" itself (not the TeX engine
85 being invoked; consult the TeX documentation or the engine's "--help"
86 output for that).
87 The first non-option terminates "texfot"'s option parsing, and the
89 remainder of the command line is invoked as the TeX command, without
90 further parsing. For example, "texfot --debug tex --debug" will output
91 debugging information from both "texfot" and "tex".
92 Options may start with either - or --, and may be unambiguously
94 abbreviated. It is best to use the full option name in scripts,
95 though, to avoid possible collisions with new options in the future.
96 "--debug"
98 "--no-debug"
99 Output (or not) what is being done on standard error. Off by
100 default.
101 "--ignore" regexp
103 Ignore lines in the TeX output matching (Perl) regexp. Can be
104 repeated. Adds to the default set of ignore regexps rather than
105 replacing. These regexps are not automatically anchored (or
106 otherwise altered), simply used as-is.
107 "--interactive"
109 "--no-interactive"
110 By default, standard input to the TeX process is closed so that
111 TeX's interactive mode (waiting for input upon error, the "*"
112 prompt, etc.) is never entered. Giving "--interactive" allows
113 interaction to happen.
114 "--quiet"
116 "--no-quiet"
117 By default, the TeX command being invoked is reported on standard
118 output. "--quiet" omits that reporting.
119 "--stderr"
121 "--no-stderr"
122 The default is for "texfot" to report everything written to stderr
123 by the TeX command (on stdout). "--no-stderr" omits that
124 reporting. (Some programs, "dvisvgm" is one, can be rather verbose
125 on stderr.)
126 "--tee" file
128 By default, the output being filtered is "tee"-ed, before
129 filtering, to "$TMPDIR/fot" ("/tmp/fot" if "TMPDIR" is not set), to
130 make it easy to check the full output when the filtering seems
131 suspect. This option allows specifying a different file. Use
132 "--tee /dev/null" if you don't want the original output at all.
133 "--version"
135 Output version information and exit successfully.
136 "--help"
138 Display this help and exit successfully.
139
141 I wrote this because, in my work as a TUGboat editor
142 (<http://tug.org/TUGboat>, journal submissions always welcome!), I end
143 up running and rerunning many papers, many times each. It was too easy
144 to lose warnings I needed to see in the mass of unvarying and
145 uninteresting output from TeX, such as style files being read and fonts
146 being used. I wanted to see all and only those messages which needed
147 some action by me.
148 I found some other programs of a similar nature, the LaTeX package
150 "silence", and plenty of other (La)TeX wrappers, but it seemed none of
151 them did what I wanted. Either they read the log file (I wanted the
152 online output only), or they output more or less than I wanted, or they
153 required invoking TeX differently (I wanted to keep my build process
154 exactly the same, most critically the TeX invocation, which can get
155 complicated). Hence I wrote this.
156 Here are some keywords if you want to explore other options:
158 texloganalyser, pydflatex, logfilter, latexmk, rubber, arara, and
159 searching for "log" at <http://ctan.org/search>.
160 "texfot" is written in Perl, and runs on Unix, and does not work on
162 Windows. (If by some chance anyone wants to use this program on
163 Windows, please make your own fork; I'm not interested in supporting
164 that os.)
165 The name comes from the "trip.fot" and "trap.fot" files that are part
167 of Knuth's trip and trap torture tests, which record the online output
168 from the programs. I am not sure what "fot" stands for in trip and
169 trap, but I can pretend that it stands for "filter online transcript"
170 in the present case :).
171
173 This script and its documentation were written by Karl Berry and both
174 are released to the public domain. Email "karl@freefriends.org" with
175 bug reports. It has no home page beyond the package on CTAN:
176 <http://www.ctan.org/pkg/texfot>.
177texfot 2017-07-25 TEXFOT(1)