Provided by: texlive-extra-utils_2022.20220722-2_all 
NAME
texlogsieve - filter and summarize LaTeX log files
SYNOPSIS
texlogsieve [OPTION]... [INPUT FILE]
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 must 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 \input etc.). Also, since it cannot detect if LaTeX stops for user input,
you should really run LaTeX in nonstopmode when texlogsieve is reading from a pipe.
The program goes to great lengths to correctly handle TeX line wrapping. It understands
the max_print_line TeX configuration variable and reads its value from the same places as
TeX. Setting max_print_line to a value larger than 9999 makes texlogsieve ignore line
wrapping.
The defaults are reasonable; hopefully, you can just do
[pdf|lua|xe]latex -interaction nonstopmode myfile.tex | texlogsieve
or
texlogsieve myfile.log
and be satisfied with the result.
OPTIONS
--page-delay, --no-page-delay
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).
--summary, --no-summary
Enable/disable final summary (default enabled).
--only-summary
No messages, show only the final summary (default disabled).
--shipouts, --no-shipouts
Enable/disable reporting shipouts (default disabled with page-delay, enabled with
no-page-delay).
--file-banner, --no-file-banner
Show/don't show the “From file...” banner messages (default enabled, except with
level DEBUG as that would be redundant and confusing).
--repetitions, --no-repetitions
Allow/prevent repeated messages (default disabled, i.e., repeated messages are
supressed).
--be-redundant, --no-be-redundant
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.
--box-detail, --no-box-detail
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).
--ref-detail, --no-ref-detail
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).
--cite-detail, --no-cite-detail
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).
--summary-detail, --no-summary-detail
Toggle --box-detail, --ref-detail, and --cite-detail at once.
--heartbeat, --no-heartbeat
Enable/disable progress gauge in page-delay mode (default enabled).
--color, --no-color
Enable/disable colored output. On Windows, this will only work with an up-to-date
Windows 10 or later (default disabled).
-l LEVEL, --minlevel=LEVEL
Filter out messages with severity level lower than LEVEL. Valid levels are DEBUG
(no filtering), INFO, WARNING, CRITICAL, and UNKNOWN (default WARNING).
-u, --unwrap-only
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 “open/close file” and “shipout” 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).
--silence-package=PKGNAME
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.
--silence-string=EXCERPT OF UNWANTED MESSAGE
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 “////”, in which
case you can use lua-style pattern matching (⟨https://www.lua.org/pil/20.2.html⟩).
Note that the string is used verbatim: you may need to enclose it in quotes or
escape special characters such as “\” for the benefit of the shell, but such
quoting and escaping is unnecessary (and harmful) in the configuration file.
--silence-file=FILENAME OR FILE GLOB
Filter out messages that have been generated while the given file was being
processed. Do not use absolute or relative paths, only filenames. Simple file
globs, such as “*.cls”, work as expected. If you are only using packages you
already know, silencing “*.sty” 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.
--semisilence-file=FILENAME OR FILE GLOB
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
“chapters.tex” includes (with \input) the files “chapter1.tex” and “chapter2.tex”,
using “--silence-file=chapters.tex” will prevent messages generated by any of the
three files from being displayed. If, however, you use
“--semisilence-file=chapters.tex”, messages generated by chapters.tex will be
suppressed, but messages generated by chapter1.tex or chapter2.tex will not.
--add-[debug|info|warning|critical]-message=MESSAGE
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 \n explicitly to indicate line breaks (this is literally a backslash
character followed by the letter “n”, not a linefeed character). You may precede
the string with “////” to use lua-style pattern matching, but embedding \n to
indicate line breaks is unavoidable. Use these options multiple times to add many
different messages.
--set-to-level-[debug|info|warning|critical]=EXCERPT OF MESSAGE
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.
-c CFGFILE, --config-file=CFGFILE
Read options from the given configuration file in addition to texlogsieverc.
-h, --help
Show concise options description.
--version
Print program version.
UNRECOGNIZED MESSAGES
texlogsieve automatically handles messages such as “Package blah Info:...” or “LaTeX
Warning:...”. However, many messages do not follow this pattern. To do its thing,
texlogsieve should know about these other messages beforehand.
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 “-l unknown”). 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.
CONFIGURATION FILE
texlogsieve always searches automatically for the (optional) texlogsieverc configuration
file in the TeX path (i.e., it searches using Kpathsea). In the default configuration, the
current directory is in the search path, 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 “--”
characters. Lines starting with a “#” sign are comments. An example configuration file:
no-page-delay
# no-page-delay enables shipouts, but we do not want that
no-shipouts
silence-string = Hyperreferences in rotated content will be misplaced
# no need to escape the "\" (or any other) character
silence-string = Using \overbracket and \underbracket from `mathtools'
# silence a string using lua pattern matching
silence-string = ////luaotfload | aux : font no %d+ %(.-%)
silence-files = *.sty
LIMITATIONS
texlogsieve does not try to do anything smart about error messages (but it shows a warning
in the summary if one is detected); 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 really run LaTeX in nonstopmode 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.
SEE ALSO
The pdf documentation (in TeXLive, try texdoc texlogsieve) is a little more verbose than
this manpage and includes a TIPS 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.
BUGS AND DEVELOPMENT
⟨https://gitlab.com/lago/texlogsieve⟩
COPYRIGHT
Copyright © 2021, 2022 Nelson Lago <lago@ime.usp.br>
License GPLv3+: GNU GPL version 3 or later ⟨https://gnu.org/licenses/gpl.html⟩.
This is free software: you are free to change and redistribute it. There is NO WARRANTY,
to the extent permitted by law.