1TEXFOT(1)                         Karl Berry                         TEXFOT(1)
2
3
4

NAME

6       texfot - run TeX, filtering online transcript for interesting messages
7

SYNOPSIS

9       texfot [option]... texcmd [texarg...]
10

DESCRIPTION

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
16         # Sample basic invocation:
17         texfot pdflatex file.tex
18
19         # Ordinarily all output is copied to /tmp/fot before filtering,
20         # but that can be omitted:
21         texfot --tee=/dev/null lualatex file.tex
22
23         # Example of more complex engine invocation:
24         texfot xelatex --recorder '\nonstopmode\input file'
25
26       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
31       "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
37       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

FLOW OF OPERATION

42       Here is the order in which lines of output are checked:
43
44       1.  If the ``next line'' needs to be printed (see below), print it.
45
46       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
50       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
57       4.  Otherwise, if the line matches the list of regexps to show, show
58           it.
59
60       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 likely that any such should be considered.
64
65           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
69       Once a particular check matches, the program moves on to process the
70       next line.
71
72       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
77       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

OPTIONS

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
88       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
93       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
97       "--debug"
98       "--no-debug"
99           Output (or not) what is being done on standard error.  Off by
100           default.
101
102       "--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
108       "--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
115       "--quiet"
116       "--no-quiet"
117           By default, the TeX command being invoked is reported on standard
118           output.  "--quiet" omits that reporting. To get a completely silent
119           run, redirect standard output: "texfot ... >/dev/null". (The only
120           messages to standard error should be errors from "texfot" itself,
121           so it shouldn't be necessary to redirect that, but of course that
122           can be done as well.)
123
124       "--stderr"
125       "--no-stderr"
126           The default is for "texfot" to report everything written to stderr
127           by the TeX command (on stdout).  "--no-stderr" omits that
128           reporting.  (Some programs, "dvisvgm" is one, can be rather verbose
129           on stderr.)
130
131       "--tee" file
132           By default, the output being filtered is "tee"-ed, before
133           filtering, to "$TMPDIR/fot" (or "$TMP/fot" if "TMP" is set, or
134           "/tmp/fot" if neither environment variable is set), to make it easy
135           to check the full output when the filtering seems suspect. This
136           option allows specifying a different file. Use "--tee /dev/null" if
137           you don't want the original output at all.
138
139       "--version"
140           Output version information and exit successfully.
141
142       "--help"
143           Display this help and exit successfully.
144

RATIONALE

146       I wrote this because, in my work as a TUGboat editor
147       (<https://tug.org/TUGboat>, journal submissions always welcome!), I run
148       and rerun many documents, many times each. It was too easy to lose
149       warnings I needed to see in the mass of unvarying and uninteresting
150       output from TeX, such as style files being read and fonts being used. I
151       wanted to see all and only those messages which needed some action by
152       me.
153
154       I found some other programs of a similar nature, the LaTeX package
155       "silence", and plenty of other (La)TeX wrappers, but it seemed none of
156       them did what I wanted.  Either they read the log file (I wanted the
157       online output only), or they output more or less than I wanted, or they
158       required invoking TeX differently (I wanted to keep my build process
159       exactly the same, most critically the TeX invocation, which can get
160       complicated).  Hence I wrote this.
161
162       Here are some keywords if you want to explore other options:
163       texloganalyser, pydflatex, logfilter, latexmk, rubber, arara, and
164       searching for "log" at <https://ctan.org/search>.
165
166       "texfot" is written in Perl, and runs on Unix. It may work on Windows
167       if Perl and other software is installed, but I don't use Windows and
168       don't support C,texfot> there.
169
170       The name comes from the "trip.fot" and "trap.fot" files that are part
171       of Knuth's trip and trap torture tests, which record the online output
172       from the programs.  I am not sure what "fot" stands for in trip and
173       trap, but I can pretend that it stands for "filter online transcript"
174       in the present case :).
175
177       This script and its documentation were written by Karl Berry and both
178       are released to the public domain.  Email "karl@freefriends.org" with
179       bug reports.  It has no home page beyond the package on CTAN:
180       <https://ctan.org/pkg/texfot>.
181
182
183
184texfot                            2021-05-01                         TEXFOT(1)
Impressum