Ubuntu Manpage: texlogsieve - filter and summarize LaTeX log files

Provided by: texlive-extra-utils_2024.20250309-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).

--tips, --no-tips
Enable/disable suggesting fixes for some known warnings (default enabled).

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

       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:\Documents        and
       Settings\<username>\Application Data or C:\Users\<username>\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 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.

BUGS AND DEVELOPMENT

       https://gitlab.com/lago/texlogsieve

COPYRIGHT

       Copyright © 2021-2025 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.5.0                                  March 2025                                     TEXLOGSIEVE(1)