This small Ruby gem eases many pains around digesting logs from (La)TeX engines. Used as a command-line program or library, it converts (La)TeX logs into human- or machine-readable forms.
Disclaimer: Due to the nature of (La)TeX logs, parsing is inherently heuristic.
On any system with working Ruby (≥ 2.3), installation is as simple as this:
[sudo] gem install tex_log_parser
The usual options and, later, update mechanisms of Rubygems apply; please refer to their documentation for details.
There are two ways to parse logs: with the command-line program and via the underlying Ruby API.
texlogparser reads from stdin and writes to stdout. That is, you can use it like so:
pdflatex -interaction=nonstopmode example.tex | texlogparser
This adds so little runtime overhead that there are few reasons not to use it.
Note that the original log file will still be written to
so no information is lost.
pdflatex et al. stop on errors to interact
with the user;
texlogparser is not prepared to play the middle man for that and
You can also read from and/or write to files:
texlogparser -i example.log # From file, to stdout texlogparser -i example.log -o example.simple.log # From and to file cat example.log | texlogparser -o example.simple.log # From stdin, to file
If you want to use the output programmatically, you may want to add option
It does just what it sounds like.
Here is a minimal yet complete example:
require 'tex_log_parser' log = File.readlines('example.log') parser = TexLogParser.new(log) puts parser.parse
Here are some tips on how to generate logs that do not trip up parsing unnecessarily:
-file-line-errorto get higher accuracy regarding source files and lines.
- Increase the maximum line length as much as possible to improve overall efficacy. Bad linebreaks are bad.
- Avoid parentheses and whitespace in file paths.
- The shell output of the initial run of
pdflatexet al. on a new file can contain output of subprograms, and be complicated in other ways as well. It is therefore more robust to use the log file as written to disk, and/or the output resp. log file produced by a subsequent run. (Don't worry, real errors will stick around!)
That aside, there are two groups of experts whose help would be much appreciated: (La)TeX gourmets and Ruby developers.
Please report any logs that get parsed wrong, be it because whole messages are not found, or because not all details are correctly extracted.
Reports that provide the following information will be the most useful:
- Full failing log of a minimal example (ideally with source document).
- The engine(s) you use, e.g.
- Expected number of error, warning, and info messages (the latter optional).
- Expected message with
- log line numbers (where the message starts and ends),
- level of the message (error, warning, or info), and
- which source file (and lines) it references.
- Advanced: In case of wrong source files, run
texlogparser -don the log and note on which lines it changes file scopes in wrong ways.
If you also know a little Ruby, please consider translating those data into a (failing) test and open a pull request.
Some preemptive notes:
- Issues around messages below warning level have low priority.
- Problems caused by inopportune linebreaks are probably out of scope.
Bonus: Convince as many package maintainers to use the same standardized, robust way of writing to the log.
Any feedback about the code quality and usefulness of the documentation would be very appreciated. Particular areas of interest include:
- Is the API designed in useful ways?
- Does the documentation cover all your questions?
- Is the Gem structured properly?
- What can be improved to encourage code contributions?
- Does the CLI script have problems on any platform?