| 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. |