summaryrefslogtreecommitdiff
path: root/support/texlogsieve/texlogsieve.1
blob: 8aff5ee630e4185f0e82cffe2558542c932dd87c (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
.TH TEXLOGSIEVE "1" "September 2022" "texlogsieve 1.3.1" "User Commands"

.SH NAME

texlogsieve \- filter and summarize LaTeX log files

.SH SYNOPSIS

\fBtexlogsieve\fR [\fI\,OPTION\/\fR]... [\fI\,INPUT FILE\/\fR]

.SH DESCRIPTION

texlogsieve reads a LaTeX log file (or the standard input if no file is
specified), filters out less relevant messages, and displays a summary
report.

texlogsieve \fBmust\fR be run from the same directory as [pdf|lua|xe]latex,
because it searches for the files used during compilation (packages loaded
from the current directory, files included with \einput etc.). Also, since
it cannot detect if LaTeX stops for user input, you should \fBreally\fR run
LaTeX in \fI\,nonstopmode\/\fR when texlogsieve is reading from a pipe.

The program goes to great lengths to correctly handle TeX line wrapping. It
understands the \fI\,max_print_line\/\fR TeX configuration variable and reads
its value from the same places as TeX. Setting \fI\,max_print_line\/\fR to a
value larger than 9999 makes texlogsieve ignore line wrapping.

The defaults are reasonable; hopefully, you can just do

.RS 3
.EX
[pdf|lua|xe]latex \-interaction nonstopmode myfile.tex | texlogsieve
.EE
.RE

or

.RS 3
.EX
texlogsieve myfile.log
.EE
.RE

and be satisfied with the result.

.SH OPTIONS

.TP
\fB\-\-page\-delay\fR, \fB\-\-no\-page\-delay\fR
Enable/disable grouping messages by page before display. When enabled,
messages are only output after the current page is finished (shipout). \
The advantage is that the page number is included in the message (default
enabled).

.TP
\fB\-\-summary\fR, \fB\-\-no\-summary\fR
Enable/disable final summary (default enabled).

.TP
\fB\-\-only\-summary\fR
No messages, show only the final summary (default disabled).

.TP
\fB\-\-shipouts\fR, \fB\-\-no\-shipouts\fR
Enable/disable reporting shipouts (default disabled with page-delay,
enabled with no-page-delay).

.TP
\fB\-\-file\-banner\fR, \fB\-\-no\-file\-banner\fR
Show/don't show the \[lq]From file...\[rq] banner messages (default
enabled, except with level DEBUG as that would be redundant and confusing).

.TP
\fB\-\-repetitions\fR, \fB\-\-no\-repetitions\fR
Allow/prevent repeated messages (default disabled, i.e., repeated messages
are supressed).

.TP
\fB\-\-be\-redundant\fR, \fB\-\-no\-be\-redundant\fR
Present/suppress ordinary messages that will also appear in the summary.
This affects messages that have special summaries (such as under/overfull
boxes or undefined citations). With \-\-no\-be\-redundant (the default),
these messages are filtered out and only appear in the final summary.

.TP
\fB\-\-box\-detail\fR, \fB\-\-no\-box\-detail\fR
Include/exclude detailed information on under/overfull boxes in the final
summary. With \-\-no\-box\-detail, the summary presents only a list of
pages and files that had under/overfull boxes (default enabled).

.TP
\fB\-\-ref\-detail\fR, \fB\-\-no\-ref\-detail\fR
Include/exclude detailed information on undefined references in the final
summary. With \-\-no\-ref\-detail, the summary presents only a list of
undefined references, without page numbers and filenames (default enabled).

.TP
\fB\-\-cite\-detail\fR, \fB\-\-no\-cite\-detail\fR
Include/exclude detailed information on undefined citations in the final
summary. With \-\-no\-cite\-detail, the summary presents only a list of
undefined citations, without page numbers and filenames (default enabled).

.TP
\fB\-\-summary\-detail\fR, \fB\-\-no\-summary\-detail\fR
Toggle \-\-box\-detail, \-\-ref\-detail, and \-\-cite\-detail at once.

.TP
\fB\-\-heartbeat\fR, \fB\-\-no\-heartbeat\fR
Enable/disable progress gauge in page-delay mode (default enabled).

.TP
\fB\-\-color\fR, \fB\-\-no\-color\fR
Enable/disable colored output. On Windows, this will only work with
an up-to-date Windows 10 or later (default disabled).

.TP
\fB\-l\fR \fI\,LEVEL\/\fR, \fB\-\-minlevel\fR=\fI\,LEVEL\/\fR
Filter out messages with severity level lower than LEVEL. Valid levels
are DEBUG (no filtering), INFO, WARNING, CRITICAL, and UNKNOWN (default
WARNING).

.TP
\fB\-u\fR, \fB\-\-unwrap\-only\fR
Do not filter messages and do not output the summary, only unwrap long,
wrapped lines. The output should be very similar (but not equal) to the
input file, but with wrapped lines reconstructed. This activates \-l debug,
\-\-no\-summary, \-\-no\-page\-delay, \-\-repetitions, \-\-be\-redundant,
\-\-shipouts, and \-\-no\-file\-banner, and also supresses the verbose
\[lq]open/close file\[rq] and \[lq]shipout\[rq] messages, simulating
instead the TeX format, with parens and square brackets. This is useful if
you prefer the reports generated by some other tool but want to benefit
from texlogsieve's line unwrapping algorithm; the output generated by this
option should be parseable by other tools (but you probably need to coerce
the other tool not to try to unwrap lines).

.TP
\fB\-\-silence\-package\fR=\fI\,PKGNAME\/\fR
Filter out messages that can be identified as coming from the given package. \
Use this option multiple times to suppress messages from several different
packages.

.TP
\fB\-\-silence\-string\fR=\fI\,EXCERPT OF UNWANTED MESSAGE\/\fR
Filter out messages that contain the given string (you only need to provide
part of the message text for the whole message to be suppressed). Use this
option multiple times to suppress several different messages. The string
should be a single line, but that is not a problem for multiline log messages:
space characters in the provided string match any sequence of whitespace
characters in the message, including newlines. If needed, you may precede the
string with \[lq]////\[rq], in which case you can use lua-style pattern matching
(\c
.UR https://www.lua.org/pil/20.2.html
.UE ). Note that the string is used verbatim: you may need to enclose it in
quotes or escape special characters such as \[lq]\e\[rq] for the benefit of
the shell, but such quoting and escaping is unnecessary (and harmful) in the
configuration file.

.TP
\fB\-\-silence\-file\fR=\fI\,FILENAME OR FILE GLOB\/\fR
Filter out messages that have been generated while the given file was being
processed. Do \fBnot\fR use absolute or relative paths, only filenames. Simple
file globs, such as \[lq]*.cls\[rq], work as expected. If you are only using
packages you already know, silencing \[lq]*.sty\[rq] may be a good idea (note
that this does not suppress all messages from all packages, only the messages
generated while the packages are being loaded). Use this option multiple times
to suppress messages from several different files.

.TP
\fB\-\-semisilence\-file\fR=\fI\,FILENAME OR FILE GLOB\/\fR
Just like the previous option, but non-recursive. This means that messages
generated while the given file was being processed are excluded, but messages
generated by some other file that was opened by it are not. For example, if
\[lq]chapters.tex\[rq] includes (with \einput) the files \[lq]chapter1.tex\[rq]
and \[lq]chapter2.tex\[rq], using \[lq]\-\-silence\-file=chapters.tex\[rq]
will prevent messages generated by any of the three files from being
displayed. If, however, you use \[lq]\-\-semisilence\-file=chapters.tex\[rq],
messages generated by chapters.tex will be suppressed, but messages generated
by chapter1.tex or chapter2.tex will not.

.TP
\fB\-\-add\-[debug|info|warning|critical]\-message\fR=\fI\,MESSAGE\/\fR
Add MESSAGE to the list of messages known to the program with the given
severity level; see Section UNRECOGNIZED MESSAGES below for more information
about this. Like \-\-silence\-string, these should be a single line; unlike
\-\-silence\-string, you need to embed \en explicitly to indicate line
breaks (this is literally a backslash character followed by the letter
\[lq]n\[rq], \fBnot\fR a linefeed character). You may precede the string
with \[lq]////\[rq] to use lua-style pattern matching, but embedding \en
to indicate line breaks is unavoidable. Use these options multiple times
to add many different messages.

.TP
\fB\-\-set\-to\-level\-[debug|info|warning|critical]\fR=\fI\,EXCERPT OF MESSAGE\/\fR
Redefine the severity level of messages that contain the provided string
to the given level. Check the explanation for \-\-silence\-string, as this
works in a similar way. Use these options multiple times to change the
severity level of many different messages.

.TP
\fB\-c\fR \fI\,CFGFILE\/\fR, \fB\-\-config\-file\fR=\fI\,CFGFILE\/\fR
Read options from the given configuration file in addition to the
default config files (see the \fBCONFIGURATION FILE\fR section).

.TP
\fB\-v\fR, \fB\-\-verbose\fR
Print the list of configuration files read and a short summary of the
most important active configuration options.

.TP
\fB\-h\fR, \fB\-\-help\fR
Show concise options description.

.TP
\fB\-\-version\fR
Print program version.

.SH UNRECOGNIZED MESSAGES

texlogsieve automatically handles messages such as \[lq]Package blah
Info:...\[rq] or \[lq]LaTeX Warning:...\[rq]. However, many messages do not
follow this pattern. To do its thing, texlogsieve should know about these
other messages beforehand.

.PP
While texlogsieve recognizes quite a few messages out of the box, you may run
into a message generated by some package that it does not know about (you can
check for this using \[lq]\-l unknown\[rq]). If that is the case, you can use
the \-\-add\-[debug|info|warning|critical]\-message options to add it to the
list of messages known to the program.

.SH CONFIGURATION FILE

texlogsieve always searches automatically for the (optional)
\fI\,texlogsieverc\/\fR configuration file in \fI\,$TEXINPUTS\/\fR (i.e.,
it searches using Kpathsea). In the default configuration, the current
directory is in \fI\,$TEXINPUTS\/\fR, so adding a config file with that
name to the project directory is enough to make it work. Options in
the config file are exactly the same as the long command-line options
described above, but without the preceding \[lq]\-\-\[rq] characters.
Lines starting with a \[lq]#\[rq] sign are comments. An example
configuration file:

.RS
.EX
no\-page\-delay
.br
# no\-page\-delay enables shipouts, but we do not want that
.br
no\-shipouts
.br
silence\-string = Hyperreferences in rotated content will be misplaced
.br
# no need to escape the \[dq]\e\[dq] (or any other) character
.br
silence\-string = Using \eoverbracket and \eunderbracket from \[ga]mathtools\[aq]
.br
# silence a string using lua pattern matching
.br
silence\-string = ////luaotfload | aux : font no %d+ %(.\-%)
.br
silence\-files = *.sty
.EE
.RE

If you'd like to also have a generic configuration file for all your projects
(a good idea), put it at \fI\,$HOME/.texlogsieverc\/\fR in unix-like systems;
in Windows, put it either at \fI\,%LOCALAPPDATA%\etexlogsieverc\/\fR
(\fI\,C:\eUsers\e<username>\eAppData\eLocal\/\fR)
or \fI\,%APPDATA%\etexlogsieverc\/\fR (\fI\,C:\eDocuments and
Settings\e<username>\eApplication Data\/\fR or
\fI\,C:\eUsers\e<username>\eAppData\eRoaming).

.SH LIMITATIONS

texlogsieve does not try to do anything smart about error messages (but it
shows a warning in the summary if one is detected; check the \fBTIPS\fR
section of the pdf documentation regarding this); if there is an error, you
probably want to take a look directly at the log file anyway. It also cannot
detect if LaTeX stops for user input, so you should \fBreally\fR run LaTeX
in \fI\,nonstopmode\/\fR when texlogsieve is reading from a pipe.

Since it needs to know what messages to expect, texlogsieve is currently
geared towards LaTeX; I have no idea how it would work with ConTeXt or plain
TeX. Still, adding support to them should not be too difficult.

.SH SEE ALSO

The pdf documentation (in TeXLive, try \fI\,texdoc texlogsieve\/\fR)
is a little more verbose than this manpage and includes a \fBTIPS\fR
section you may find useful.

If you want to know more about the TeX log file and the workings of the
program, check the initial comments in the code.

.SH BUGS AND DEVELOPMENT

.UR https://gitlab.com/lago/texlogsieve
.UE

.SH COPYRIGHT

Copyright \[co] 2021, 2022 Nelson Lago <lago@ime.usp.br>
.br
License GPLv3+: GNU GPL version 3 or later
.UR https://gnu.org/licenses/gpl.html
.UE .

This is free software: you are free to change and redistribute it. \
There is NO WARRANTY, to the extent permitted by law.