1TEXLOGSIEVE(1) User Commands TEXLOGSIEVE(1)
2
6 texlogsieve - filter and summarize LaTeX log files
7
10 texlogsieve [OPTION]... [INPUT FILE]
11
14 texlogsieve reads a LaTeX log file (or the standard input if no file is
15 specified), filters out less relevant messages, and displays a summary
16 report.
17 texlogsieve must be run from the same directory as [pdf|lua|xe]latex,
19 because it searches for the files used during compilation (packages
20 loaded from the current directory, files included with \input etc.).
21 Also, since it cannot detect if LaTeX stops for user input, you should
22 really run LaTeX in nonstopmode when texlogsieve is reading from a
23 pipe.
24 The program goes to great lengths to correctly handle TeX line wrap‐
26 ping. It understands the max_print_line TeX configuration variable and
27 reads its value from the same places as TeX. Setting max_print_line to
28 a value larger than 9999 makes texlogsieve ignore line wrapping.
29 The defaults are reasonable; hopefully, you can just do
31 [pdf|lua|xe]latex -interaction nonstopmode myfile.tex | texlogsieve
33 or
35 texlogsieve myfile.log
37 and be satisfied with the result.
39
42 --page-delay, --no-page-delay
43 Enable/disable grouping messages by page before display. When
44 enabled, messages are only output after the current page is fin‐
45 ished (shipout). The advantage is that the page number is in‐
46 cluded in the message (default enabled).
47 --summary, --no-summary
50 Enable/disable final summary (default enabled).
51 --only-summary
54 No messages, show only the final summary (default disabled).
55 --shipouts, --no-shipouts
58 Enable/disable reporting shipouts (default disabled with page-
59 delay, enabled with no-page-delay).
60 --file-banner, --no-file-banner
63 Show/don't show the “From file...” banner messages (default en‐
64 abled, except with level DEBUG as that would be redundant and
65 confusing).
66 --repetitions, --no-repetitions
69 Allow/prevent repeated messages (default disabled, i.e., re‐
70 peated messages are supressed).
71 --be-redundant, --no-be-redundant
74 Present/suppress ordinary messages that will also appear in the
75 summary. This affects messages that have special summaries
76 (such as under/overfull boxes or undefined citations). With
77 --no-be-redundant (the default), these messages are filtered out
78 and only appear in the final summary.
79 --box-detail, --no-box-detail
82 Include/exclude detailed information on under/overfull boxes in
83 the final summary. With --no-box-detail, the summary presents
84 only a list of pages and files that had under/overfull boxes
85 (default enabled).
86 --ref-detail, --no-ref-detail
89 Include/exclude detailed information on undefined references in
90 the final summary. With --no-ref-detail, the summary presents
91 only a list of undefined references, without page numbers and
92 filenames (default enabled).
93 --cite-detail, --no-cite-detail
96 Include/exclude detailed information on undefined citations in
97 the final summary. With --no-cite-detail, the summary presents
98 only a list of undefined citations, without page numbers and
99 filenames (default enabled).
100 --summary-detail, --no-summary-detail
103 Toggle --box-detail, --ref-detail, and --cite-detail at once.
104 --heartbeat, --no-heartbeat
107 Enable/disable progress gauge in page-delay mode (default en‐
108 abled).
109 --color, --no-color
112 Enable/disable colored output. On Windows, this will only work
113 with an up-to-date Windows 10 or later (default disabled).
114 -l LEVEL, --minlevel=LEVEL
117 Filter out messages with severity level lower than LEVEL. Valid
118 levels are DEBUG (no filtering), INFO, WARNING, CRITICAL, and
119 UNKNOWN (default WARNING).
120 -u, --unwrap-only
123 Do not filter messages and do not output the summary, only un‐
124 wrap long, wrapped lines. The output should be very similar (but
125 not equal) to the input file, but with wrapped lines recon‐
126 structed. This activates -l debug, --no-summary, --no-page-de‐
127 lay, --repetitions, --be-redundant, --shipouts, and
128 --no-file-banner, and also supresses the verbose “open/close
129 file” and “shipout” messages, simulating instead the TeX format,
130 with parens and square brackets. This is useful if you prefer
131 the reports generated by some other tool but want to benefit
132 from texlogsieve's line unwrapping algorithm; the output gener‐
133 ated by this option should be parseable by other tools (but you
134 probably need to coerce the other tool not to try to unwrap
135 lines).
136 --silence-package=PKGNAME
139 Filter out messages that can be identified as coming from the
140 given package. Use this option multiple times to suppress mes‐
141 sages from several different packages.
142 --silence-string=EXCERPT OF UNWANTED MESSAGE
145 Filter out messages that contain the given string (you only need
146 to provide part of the message text for the whole message to be
147 suppressed). Use this option multiple times to suppress several
148 different messages. The string should be a single line, but that
149 is not a problem for multiline log messages: space characters in
150 the provided string match any sequence of whitespace characters
151 in the message, including newlines. If needed, you may precede
152 the string with “////”, in which case you can use lua-style pat‐
153 tern matching (⟨https://www.lua.org/pil/20.2.html⟩). Note that
154 the string is used verbatim: you may need to enclose it in
155 quotes or escape special characters such as “\” for the benefit
156 of the shell, but such quoting and escaping is unnecessary (and
157 harmful) in the configuration file.
158 --silence-file=FILENAME OR FILE GLOB
161 Filter out messages that have been generated while the given
162 file was being processed. Do not use absolute or relative paths,
163 only filenames. Simple file globs, such as “*.cls”, work as ex‐
164 pected. If you are only using packages you already know, silenc‐
165 ing “*.sty” may be a good idea (note that this does not suppress
166 all messages from all packages, only the messages generated
167 while the packages are being loaded). Use this option multiple
168 times to suppress messages from several different files.
169 --semisilence-file=FILENAME OR FILE GLOB
172 Just like the previous option, but non-recursive. This means
173 that messages generated while the given file was being processed
174 are excluded, but messages generated by some other file that was
175 opened by it are not. For example, if “chapters.tex” includes
176 (with \input) the files “chapter1.tex” and “chapter2.tex”, using
177 “--silence-file=chapters.tex” will prevent messages generated by
178 any of the three files from being displayed. If, however, you
179 use “--semisilence-file=chapters.tex”, messages generated by
180 chapters.tex will be suppressed, but messages generated by chap‐
181 ter1.tex or chapter2.tex will not.
182 --add-[debug|info|warning|critical]-message=MESSAGE
185 Add MESSAGE to the list of messages known to the program with
186 the given severity level; see Section UNRECOGNIZED MESSAGES be‐
187 low for more information about this. Like --silence-string,
188 these should be a single line; unlike --silence-string, you need
189 to embed \n explicitly to indicate line breaks (this is liter‐
190 ally a backslash character followed by the letter “n”, not a
191 linefeed character). You may precede the string with “////” to
192 use lua-style pattern matching, but embedding \n to indicate
193 line breaks is unavoidable. Use these options multiple times to
194 add many different messages.
195 --set-to-level-[debug|info|warning|critical]=EXCERPT OF MESSAGE
198 Redefine the severity level of messages that contain the pro‐
199 vided string to the given level. Check the explanation for --si‐
200 lence-string, as this works in a similar way. Use these options
201 multiple times to change the severity level of many different
202 messages.
203 -c CFGFILE, --config-file=CFGFILE
206 Read options from the given configuration file in addition to
207 the default config files (see the CONFIGURATION FILE section).
208 -v, --verbose
211 Print the list of configuration files read and a short summary
212 of the most important active configuration options.
213 -h, --help
216 Show concise options description.
217 --version
220 Print program version.
221
224 texlogsieve automatically handles messages such as “Package blah
225 Info:...” or “LaTeX Warning:...”. However, many messages do not follow
226 this pattern. To do its thing, texlogsieve should know about these
227 other messages beforehand.
228 While texlogsieve recognizes quite a few messages out of the box, you
231 may run into a message generated by some package that it does not know
232 about (you can check for this using “-l unknown”). If that is the case,
233 you can use the --add-[debug|info|warning|critical]-message options to
234 add it to the list of messages known to the program.
235
238 texlogsieve always searches automatically for the (optional)
239 texlogsieverc configuration file in $TEXINPUTS (i.e., it searches using
240 Kpathsea). In the default configuration, the current directory is in
241 $TEXINPUTS, so adding a config file with that name to the project di‐
242 rectory is enough to make it work. Options in the config file are ex‐
243 actly the same as the long command-line options described above, but
244 without the preceding “--” characters. Lines starting with a “#” sign
245 are comments. An example configuration file:
246 no-page-delay
248 # no-page-delay enables shipouts, but we do not want that
249 no-shipouts
250 silence-string = Hyperreferences in rotated content will be misplaced
251 # no need to escape the "\" (or any other) character
252 silence-string = Using \overbracket and \underbracket from `mathtools'
253 # silence a string using lua pattern matching
254 silence-string = ////luaotfload | aux : font no %d+ %(.-%)
255 silence-files = *.sty
256 If you'd like to also have a generic configuration file for all your
258 projects (a good idea), put it at $HOME/.texlogsieverc in unix-like
259 systems; in Windows, put it either at %LOCALAPPDATA%\texlogsieverc
260 (C:\Users\<username>\AppData\Local) or %APPDATA%\texlogsieverc (C:\Doc‐
261 uments and Settings\<username>\Application Data or C:\Users\<user‐
262 name>\AppData\Roaming).
263
266 texlogsieve does not try to do anything smart about error messages (but
267 it shows a warning in the summary if one is detected; check the TIPS
268 section of the pdf documentation regarding this); if there is an error,
269 you probably want to take a look directly at the log file anyway. It
270 also cannot detect if LaTeX stops for user input, so you should really
271 run LaTeX in nonstopmode when texlogsieve is reading from a pipe.
272 Since it needs to know what messages to expect, texlogsieve is cur‐
274 rently geared towards LaTeX; I have no idea how it would work with Con‐
275 TeXt or plain TeX. Still, adding support to them should not be too dif‐
276 ficult.
277
280 The pdf documentation (in TeXLive, try texdoc texlogsieve) is a little
281 more verbose than this manpage and includes a TIPS section you may find
282 useful.
283 If you want to know more about the TeX log file and the workings of the
285 program, check the initial comments in the code.
286
289 ⟨https://gitlab.com/lago/texlogsieve⟩
290
293 Copyright © 2021, 2022 Nelson Lago <lago@ime.usp.br>
294 License GPLv3+: GNU GPL version 3 or later
295 ⟨https://gnu.org/licenses/gpl.html⟩.
296 This is free software: you are free to change and redistribute it.
298 There is NO WARRANTY, to the extent permitted by law.
299texlogsieve 1.3.1 September 2022 TEXLOGSIEVE(1)