TEXLOGSIEVE(1) User Commands TEXLOGSIEVE(1)
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 wrap-
ping. 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 fin-
ished (shipout). The advantage is that the page number is in-
cluded 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 en-
abled, except with level DEBUG as that would be redundant and
confusing).
--repetitions, --no-repetitions
Allow/prevent repeated messages (default disabled, i.e., re-
peated 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 en-
abled).
--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 un-
wrap long, wrapped lines. The output should be very similar (but
not equal) to the input file, but with wrapped lines recon-
structed. This activates -l debug, --no-summary, --no-page-de-
lay, --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 gener-
ated 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 mes-
sages 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 pat-
tern 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 ex-
pected. If you are only using packages you already know, silenc-
ing “*.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 chap-
ter1.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 be-
low 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 liter-
ally 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 pro-
vided string to the given level. Check the explanation for --si-
lence-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
the default config files (see the CONFIGURATION FILE section).
-v, --verbose
Print the list of configuration files read and a short summary
of the most important active configuration options.
-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 $TEXINPUTS (i.e., it searches using
Kpathsea). In the default configuration, the current directory is in
$TEXINPUTS, so adding a config file with that name to the project di-
rectory is enough to make it work. Options in the config file are ex-
actly 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
If you'd like to also have a generic configuration file for all your
projects (a good idea), put it at $HOME/.texlogsieverc in unix-like
systems; in Windows, put it either at %LOCALAPPDATA%\texlogsieverc
(C:\Users\<username>\AppData\Local) or %APPDATA%\texlogsieverc (C:\Doc-
uments and Settings\<username>\Application Data or C:\Users\<user-
name>\AppData\Roaming).
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 TIPS
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 really
run LaTeX in nonstopmode when texlogsieve is reading from a pipe.
Since it needs to know what messages to expect, texlogsieve is cur-
rently geared towards LaTeX; I have no idea how it would work with Con-
TeXt or plain TeX. Still, adding support to them should not be too dif-
ficult.
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.
texlogsieve 1.3.1 September 2022 TEXLOGSIEVE(1)
Generated by dwww version 1.15 on Sat Jun 29 02:28:51 CEST 2024.