Debian Codegraph @

texmf-dist/doc/man/man1/texlogsieve.1

raw
1 .TH TEXLOGSIEVE "1" "January 2026" "texlogsieve 1.6.1" "User Commands"
2
3 .SH NAME
4
5 texlogsieve \- filter and summarize LaTeX log files
6
7 .SH SYNOPSIS
8
9 \fBtexlogsieve\fR [\fI\,OPTION\/\fR]... [\fI\,INPUT FILE\/\fR]
10
11 .SH DESCRIPTION
12
13 texlogsieve reads a LaTeX log file (or the standard input if no file is
14 specified), filters out less relevant messages, and displays a summary
15 report.
16
17 texlogsieve \fBmust\fR be run from the same directory as [pdf|lua|xe]latex,
18 because it searches for the files used during compilation (packages loaded
19 from the current directory, files included with \einput etc.). Also, since
20 it cannot detect if LaTeX stops for user input, you should \fBreally\fR run
21 LaTeX in \fI\,nonstopmode\/\fR when texlogsieve is reading from a pipe.
22
23 The program goes to great lengths to correctly handle TeX line wrapping. It
24 understands the \fI\,max_print_line\/\fR TeX configuration variable and reads
25 its value from the same places as TeX. Setting \fI\,max_print_line\/\fR to a
26 value larger than 9999 makes texlogsieve ignore line wrapping.
27
28 The defaults are reasonable; hopefully, you can just do
29
30 .RS 3
31 .EX
32 [pdf|lua|xe]latex \-interaction nonstopmode myfile.tex | texlogsieve
33 .EE
34 .RE
35
36 or
37
38 .RS 3
39 .EX
40 texlogsieve myfile.log
41 .EE
42 .RE
43
44 and be satisfied with the result.
45
46 .SH OPTIONS
47
48 .TP
49 \fB\-\-page\-delay\fR, \fB\-\-no\-page\-delay\fR
50 Enable/disable grouping messages by page before display. When enabled,
51 messages are only output after the current page is finished (shipout). \
52 The advantage is that the page number is included in the message (default
53 enabled).
54
55 .TP
56 \fB\-\-summary\fR, \fB\-\-no\-summary\fR
57 Enable/disable final summary (default enabled).
58
59 .TP
60 \fB\-\-only\-summary\fR
61 No messages, show only the final summary (default disabled).
62
63 .TP
64 \fB\-\-shipouts\fR, \fB\-\-no\-shipouts\fR
65 Enable/disable reporting shipouts (default disabled with page-delay,
66 enabled with no-page-delay).
67
68 .TP
69 \fB\-\-file\-banner\fR, \fB\-\-no\-file\-banner\fR
70 Show/don't show the \[lq]From file...\[rq] banner messages (default
71 enabled, except with level DEBUG as that would be redundant and confusing).
72
73 .TP
74 \fB\-\-repetitions\fR, \fB\-\-no\-repetitions\fR
75 Allow/prevent repeated messages (default disabled, i.e., repeated messages
76 are supressed).
77
78 .TP
79 \fB\-\-be\-redundant\fR, \fB\-\-no\-be\-redundant\fR
80 Present/suppress ordinary messages that will also appear in the summary.
81 This affects messages that have special summaries (such as under/overfull
82 boxes or undefined citations). With \-\-no\-be\-redundant (the default),
83 these messages are filtered out and only appear in the final summary.
84
85 .TP
86 \fB\-\-box\-detail\fR, \fB\-\-no\-box\-detail\fR
87 Include/exclude detailed information on under/overfull boxes in the final
88 summary. With \-\-no\-box\-detail, the summary presents only a list of
89 pages and files that had under/overfull boxes (default enabled).
90
91 .TP
92 \fB\-\-ref\-detail\fR, \fB\-\-no\-ref\-detail\fR
93 Include/exclude detailed information on undefined references in the final
94 summary. With \-\-no\-ref\-detail, the summary presents only a list of
95 undefined references, without page numbers and filenames (default enabled).
96
97 .TP
98 \fB\-\-cite\-detail\fR, \fB\-\-no\-cite\-detail\fR
99 Include/exclude detailed information on undefined citations in the final
100 summary. With \-\-no\-cite\-detail, the summary presents only a list of
101 undefined citations, without page numbers and filenames (default enabled).
102
103 .TP
104 \fB\-\-summary\-detail\fR, \fB\-\-no\-summary\-detail\fR
105 Toggle \-\-box\-detail, \-\-ref\-detail, and \-\-cite\-detail at once.
106
107 .TP
108 \fB\-\-heartbeat\fR, \fB\-\-no\-heartbeat\fR
109 Enable/disable progress gauge in page-delay mode (default enabled).
110
111 .TP
112 \fB\-\-color\fR, \fB\-\-no\-color\fR
113 Enable/disable colored output. On Windows, this will only work with
114 an up-to-date Windows 10 or later (default disabled).
115
116 .TP
117 \fB\-\-tips\fR, \fB\-\-no\-tips\fR
118 Enable/disable suggesting fixes for some known warnings (default enabled).
119
120 .TP
121 \fB\-l\fR \fI\,LEVEL\/\fR, \fB\-\-minlevel\fR=\fI\,LEVEL\/\fR
122 Filter out messages with severity level lower than LEVEL. Valid levels
123 are DEBUG (no filtering), INFO, WARNING, CRITICAL, and UNKNOWN (default
124 WARNING).
125
126 .TP
127 \fB\-u\fR, \fB\-\-unwrap\-only\fR
128 Do not filter messages and do not output the summary, only unwrap long,
129 wrapped lines. The output should be very similar (but not equal) to the
130 input file, but with wrapped lines reconstructed. This activates \-l debug,
131 \-\-no\-summary, \-\-no\-page\-delay, \-\-repetitions, \-\-be\-redundant,
132 \-\-shipouts, and \-\-no\-file\-banner, and also supresses the verbose
133 \[lq]open/close file\[rq] and \[lq]shipout\[rq] messages, simulating
134 instead the TeX format, with parens and square brackets. This is useful if
135 you prefer the reports generated by some other tool but want to benefit
136 from texlogsieve's line unwrapping algorithm; the output generated by this
137 option should be parseable by other tools (but you probably need to coerce
138 the other tool not to try to unwrap lines).
139
140 .TP
141 \fB\-\-silence\-package\fR=\fI\,PKGNAME\/\fR
142 Filter out messages that can be identified as coming from the given package. \
143 Use this option multiple times to suppress messages from several different
144 packages.
145
146 .TP
147 \fB\-\-silence\-string\fR=\fI\,EXCERPT OF UNWANTED MESSAGE\/\fR
148 Filter out messages that contain the given string (you only need to provide
149 part of the message text for the whole message to be suppressed). Use this
150 option multiple times to suppress several different messages. The string
151 should be a single line, but that is not a problem for multiline log messages:
152 space characters in the provided string match any sequence of whitespace
153 characters in the message, including newlines. If needed, you may precede the
154 string with \[lq]////\[rq], in which case you can use lua-style pattern matching
155 (\c
156 .UR https://www.lua.org/pil/20.2.html
157 .UE ). Note that the string is used verbatim: you may need to enclose it in
158 quotes or escape special characters such as \[lq]\e\[rq] for the benefit of
159 the shell, but such quoting and escaping is unnecessary (and harmful) in the
160 configuration file.
161
162 .TP
163 \fB\-\-silence\-file\fR=\fI\,FILENAME OR FILE GLOB\/\fR
164 Filter out messages that have been generated while the given file was being
165 processed. Do \fBnot\fR use absolute or relative paths, only filenames. Simple
166 file globs, such as \[lq]*.cls\[rq], work as expected. If you are only using
167 packages you already know, silencing \[lq]*.sty\[rq] may be a good idea (note
168 that this does not suppress all messages from all packages, only the messages
169 generated while the packages are being loaded). Use this option multiple times
170 to suppress messages from several different files.
171
172 .TP
173 \fB\-\-semisilence\-file\fR=\fI\,FILENAME OR FILE GLOB\/\fR
174 Just like the previous option, but non-recursive. This means that messages
175 generated while the given file was being processed are excluded, but messages
176 generated by some other file that was opened by it are not. For example, if
177 \[lq]chapters.tex\[rq] includes (with \einput) the files \[lq]chapter1.tex\[rq]
178 and \[lq]chapter2.tex\[rq], using \[lq]\-\-silence\-file=chapters.tex\[rq]
179 will prevent messages generated by any of the three files from being
180 displayed. If, however, you use \[lq]\-\-semisilence\-file=chapters.tex\[rq],
181 messages generated by chapters.tex will be suppressed, but messages generated
182 by chapter1.tex or chapter2.tex will not.
183
184 .TP
185 \fB\-\-add\-[debug|info|warning|critical]\-message\fR=\fI\,MESSAGE\/\fR
186 Add MESSAGE to the list of messages known to the program with the given
187 severity level; see Section UNRECOGNIZED MESSAGES below for more information
188 about this. Like \-\-silence\-string, these should be a single line; unlike
189 \-\-silence\-string, you need to embed \en explicitly to indicate line
190 breaks (this is literally a backslash character followed by the letter
191 \[lq]n\[rq], \fBnot\fR a linefeed character). You may precede the string
192 with \[lq]////\[rq] to use lua-style pattern matching, but embedding \en
193 to indicate line breaks is unavoidable. Use these options multiple times
194 to add many different messages.
195
196 .TP
197 \fB\-\-set\-to\-level\-[debug|info|warning|critical]\fR=\fI\,EXCERPT OF MESSAGE\/\fR
198 Redefine the severity level of messages that contain the provided string
199 to the given level. Check the explanation for \-\-silence\-string, as this
200 works in a similar way. Use these options multiple times to change the
201 severity level of many different messages.
202
203 .TP
204 \fB\-c\fR \fI\,CFGFILE\/\fR, \fB\-\-config\-file\fR=\fI\,CFGFILE\/\fR
205 Read options from the given configuration file in addition to the
206 default config files (see the \fBCONFIGURATION FILE\fR section).
207
208 .TP
209 \fB\-v\fR, \fB\-\-verbose\fR
210 Print the list of configuration files read and a short summary of the
211 most important active configuration options.
212
213 .TP
214 \fB\-h\fR, \fB\-\-help\fR
215 Show concise options description.
216
217 .TP
218 \fB\-\-version\fR
219 Print program version.
220
221 .SH UNRECOGNIZED MESSAGES
222
223 texlogsieve automatically handles messages such as \[lq]Package blah
224 Info:...\[rq] or \[lq]LaTeX Warning:...\[rq]. However, many messages do not
225 follow this pattern. To do its thing, texlogsieve should know about these
226 other messages beforehand.
227
228 .PP
229 While texlogsieve recognizes quite a few messages out of the box, you may run
230 into a message generated by some package that it does not know about (you can
231 check for this using \[lq]\-l unknown\[rq]). If that is the case, you can use
232 the \-\-add\-[debug|info|warning|critical]\-message options to add it to the
233 list of messages known to the program.
234
235 .SH CONFIGURATION FILE
236
237 texlogsieve always searches automatically for the (optional)
238 \fI\,texlogsieverc\/\fR configuration file in \fI\,$TEXINPUTS\/\fR (i.e.,
239 it searches using Kpathsea). In the default configuration, the current
240 directory is in \fI\,$TEXINPUTS\/\fR, so adding a config file with that
241 name to the project directory is enough to make it work. Options in
242 the config file are exactly the same as the long command-line options
243 described above, but without the preceding \[lq]\-\-\[rq] characters.
244 Lines starting with a \[lq]#\[rq] sign are comments. An example
245 configuration file:
246
247 .RS
248 .EX
249 no\-page\-delay
250 .br
251 # no\-page\-delay enables shipouts, but we do not want that
252 .br
253 no\-shipouts
254 .br
255 silence\-string = Hyperreferences in rotated content will be misplaced
256 .br
257 # no need to escape the \[dq]\e\[dq] (or any other) character
258 .br
259 silence\-string = Using \eoverbracket and \eunderbracket from \[ga]mathtools\[aq]
260 .br
261 # silence a string using lua pattern matching
262 .br
263 silence\-string = ////luaotfload | aux : font no %d+ %(.\-%)
264 .br
265 silence\-files = *.sty
266 .EE
267 .RE
268
269 If you'd like to also have a generic configuration file for all your projects
270 (a good idea), put it at \fI\,$HOME/.texlogsieverc\/\fR in unix-like systems;
271 in Windows, put it either at \fI\,%LOCALAPPDATA%\etexlogsieverc\/\fR
272 (\fI\,C:\eUsers\e<username>\eAppData\eLocal\/\fR)
273 or \fI\,%APPDATA%\etexlogsieverc\/\fR (\fI\,C:\eDocuments and
274 Settings\e<username>\eApplication Data\/\fR or
275 \fI\,C:\eUsers\e<username>\eAppData\eRoaming).
276
277 .SH LIMITATIONS
278
279 texlogsieve does not try to do anything smart about error messages (but it
280 shows a warning in the summary if one is detected; check the \fBTIPS\fR
281 section of the pdf documentation regarding this); if there is an error, you
282 probably want to take a look directly at the log file anyway. It also cannot
283 detect if LaTeX stops for user input, so you should \fBreally\fR run LaTeX
284 in \fI\,nonstopmode\/\fR when texlogsieve is reading from a pipe.
285
286 Since it needs to know what messages to expect, texlogsieve is currently
287 geared towards LaTeX; I have no idea how it would work with ConTeXt or plain
288 TeX. Still, adding support to them should not be too difficult.
289
290 .SH SEE ALSO
291
292 The pdf documentation (in TeXLive, try \fI\,texdoc texlogsieve\/\fR)
293 is a little more verbose than this manpage and includes a \fBTIPS\fR
294 section you may find useful.
295
296 If you want to know more about the TeX log file and the workings of the
297 program, check the initial comments in the code.
298
299 .SH BUGS AND DEVELOPMENT
300
301 .UR https://gitlab.com/lago/texlogsieve
302 .UE
303
304 .SH COPYRIGHT
305
306 Copyright \[co] 2021-2026 Nelson Lago <[email protected]>
307 .br
308 License GPLv3+: GNU GPL version 3 or later
309 .UR https://gnu.org/licenses/gpl.html
310 .UE .
311
312 This is free software: you are free to change and redistribute it. \
313 There is NO WARRANTY, to the extent permitted by law.