TEXLOGSIEVE(1)

📦
version 77351 · 6 versions
, in fedora 44

💖 TEXLOGSIEVE(1) — User Commands 💖

okay bestie, welcome to the texlogsieve manual, she's an icon, she's a legend, and she is about to make your LaTeX logs not be a nightmare anymore 🎀

✨ NAME ✨

texlogsieve — filter and summarize LaTeX log files 💅

🌸 SYNOPSIS 🌸

texlogsieve [OPTION]... [INPUT FILE]

🦋 DESCRIPTION 🦋

So here's the vibe: texlogsieve reads a LaTeX log file (or, if you don't give it a file, it just reads from standard input), filters out the less relevant messages, and then shows you a summary report. It's giving personal assistant energy, honestly. 🫶

okay important thing: texlogsieve has to be run from the same directory as [pdf|lua|xe]latex, no cap. Why? Because it searches for the files used during compilation — think packages loaded from the current directory, files included with \input, all of that. Also — and this is the part where you have to trust me — since it cannot detect if LaTeX stops for user input, you should really run LaTeX in nonstopmode when texlogsieve is reading from a pipe. Like, for real. 😭

Now, the program goes to great lengths to correctly handle TeX line wrapping, and honestly? slay. It understands the max_print_line TeX configuration variable and reads its value from the same places as TeX does. Fun fact: if you set max_print_line to a value larger than 9999, texlogsieve just ignores line wrapping entirely. periodt.

The defaults are reasonable, bestie. Hopefully you can literally just do:

[pdf|lua|xe]latex -interaction nonstopmode myfile.tex | texlogsieve

or

texlogsieve myfile.log

and be satisfied with the result. ✨ iconic behavior ✨

💅 OPTIONS 💅

  • --page-delay, --no-page-delay — Enable/disable grouping messages by page before display. When it's enabled, messages are only output after the current page is finished (shipout). The glow-up here is that the page number gets included in the message (default enabled).
  • --summary, --no-summary — Enable/disable the final summary (default enabled).
  • --only-summary — No messages at all, just the final summary. That's it, that's the whole girl (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, because that would be redundant and confusing, and we don't do redundant and confusing here 🙈).
  • --repetitions, --no-repetitions — Allow/prevent repeated messages (default disabled, meaning repeated messages are suppressed, which is lowkey a blessing).
  • --be-redundant, --no-be-redundant — Present/suppress ordinary messages that will also appear in the summary. This affects messages that have special summaries (like under/overfull boxes or undefined citations, iykyk). With --no-be-redundant (the default), those messages get filtered out and only show up 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 — Toggles --box-detail, --ref-detail, and --cite-detail all at once. one switch, three toggles, main character energy 👑
  • --heartbeat, --no-heartbeat — Enable/disable the progress gauge in page-delay mode (default enabled). she's alive, she's breathing, she's processing 🌈
  • --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 suppresses 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. the way that she distinguishes, honestly? obsessed 🧚
  • --add-[debug|info|warning|critical]-message=MESSAGE — Add MESSAGE to the list of messages known to the program with the given severity level; see the UNRECOGNIZED MESSAGES section 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, because 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 — and this is the plot twist — many messages do not follow this pattern. And for her to do her thing, texlogsieve should know about these other messages beforehand. forewarned is forearmed, bestie 🎀

While texlogsieve recognizes quite a few messages out of the box, you may run into a message generated by some package that she does not know about (you can check for this using -l unknown). If that's 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. slay, now she knows ✨

🎀 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. Here's an example configuration file, she's giving template:

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 (which is a good idea, ngl), 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). 🌸

bestie we are NOT done yet, part 2 is coming and she has even more to say 💖 don't go anywhere 🦋

💀 LIMITATIONS 💀

okay so bestie, real talk: texlogsieve is not out here trying to be smart about error messages. like, it does not attempt any clever error-message analysis at all 🙈. it will pop a warning into the summary if it detects one (and there's a whole TIPS section in the pdf documentation about that, so go check it), but honestly if there's an error you probably wanna go stare at the log file directly anyway. no cap.

it also cannot tell if LaTeX stops and waits for user input 😭. so if texlogsieve is reading from a pipe, you really should run LaTeX in nonstopmode. seriously. otherwise you're just gonna sit there watching nothing happen and wondering why the vibe is off.

and because it needs to know what messages to expect, texlogsieve is currently geared towards LaTeX. how it would behave with ConTeXt or plain TeX? genuinely no idea, the author doesn't either 💀. but — adding support for them should not be too difficult, so that's lowkey hopeful.

🌈 SEE ALSO 🌈

the pdf documentation is a lil more verbose than this manpage and has a TIPS section you may find useful ✨. in TeXLive, just try:

texdoc texlogsieve

and if you wanna know more about the TeX log file itself and how the program actually works under the hood, go read the initial comments in the code. the lore is in there, iykyk 🫶

🦋 BUGS AND DEVELOPMENT 🦋

https://gitlab.com/lago/texlogsieve

that's the spot. come hang out, report stuff, it's giving community 💜

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

and that's the whole page bestie!! 🎀✨ this was texlogsieve version 1.6.0, dated March 2025, page TEXLOGSIE(1) — go forth and make your logs pretty, you absolute icon 👑💖
📦 where this page comes from