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