diff options
author | Norbert Preining <norbert@preining.info> | 2021-12-17 03:01:00 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2021-12-17 03:01:00 +0000 |
commit | 6827f87d3315fc677ae89a9260d455a312a90864 (patch) | |
tree | 88318243546c8d29294c2d21d5d7998ccd9d57a4 /support/texlogsieve/README.md | |
parent | 16b22a983bc0f05cbbb201a6e0f5cbbfc3c8fffb (diff) |
CTAN sync 202112170300
Diffstat (limited to 'support/texlogsieve/README.md')
-rw-r--r-- | support/texlogsieve/README.md | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/support/texlogsieve/README.md b/support/texlogsieve/README.md new file mode 100644 index 0000000000..acc3204d90 --- /dev/null +++ b/support/texlogsieve/README.md @@ -0,0 +1,143 @@ +# texlogsieve - (yet another program to) filter and summarize LaTeX log files + +`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. It is a `texlua` script, similar in spirit to tools such as +`texfot`, `texloganalyser`, `rubber-info`, `textlog_extract`, +`texlogparser`, and others. Highlights: + +* Two reports: the most important messages from the log file followed by + a summary of repeated messages, undefined references etc.; + +* The program goes to great lengths to correctly handle TeX line wrapping + and does a much better job at that than existing tools; + +* Multiline messages are treated as a single entity; + +* Several options to control which messages should be filtered out; + +* No messages are accidentally removed; + +* The summary report is currently simple, but useful. + +`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.). + +The defaults are reasonable; hopefully, you can just do + +``` +[pdf|lua|xe]latex myfile.tex | texlogsieve +``` + +and be satisfied with the result. + +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. + +If you want to know more about the TeX log file and the workings of +the program, check the initial comments in the code. + +## Short-term improvements + + * Create tests + + - Synthetic unit tests: these should systematically test the code and the + features it implements with small "fake" log files + + - Real-world files (for example, the docs for some packages or some papers + from arXiv): these should help us detect important log messages and + changes in messages whenever new versions of LaTeX and its packages are + released + + * Include the line number in the summary for messages that have it + + * Consider messages that only differ by "on line XXX" to be repetitions + + * Implement option `--collapse-lines` (show multiline messages as a single + line) + + * Implement option `--no-redundant` (makes messages that are going to be + summarized, such as `undefined reference blah`, not appear in the filtered + report, only in the summary) + +## Other improvements + + * Improve the final summary format - we should look at other tools for + inspiration + + * Filter the summary report too; look at `texloganalyser` for inspiration + + * Consider indicating filenames more prominently in the filtered report; + something like + + Messages for file ./somefile.tex: + LaTeX Warning: File `blah.txt' already exists on the system. + Messages for file ./someotherfile.tex: + Warning: Missing character: There is no " (U+0022) in font... + but only when there is actually something to report for the given file + + * Do something smart about LaTeX errors (maybe just detecting them and saying + "there was an error here" is enough) - maybe get some inspiration from + <https://github.com/overleaf/latex-log-parser> (the parser from overleaf). + This can get complicated if we account for the possibility that the user + interactively solved whatever was the problem, but do we really want to or + need to handle that? + + * Add colors (see `texlog_extract`) + + * Improve error handling if/where possible + + * Better aggregation in the summary: + + - `under/overfull boxes: p.5 (chap1.tex, L27); p.7 (chap2.tex, L37); p.19 + (chap2.tex, L176)` + + - `missing characters X, Y, Z in font blah` + + * Try to figure out a way to automatically extract possible messages from + LaTeX packages + + * Stuff like + `LaTeX Warning: Label(s) may have changed. Rerun to get cross-references right` + should trigger a specific "please rerun" message in the summary + + * Maybe grep the .fls file first before trying to do `kpse.find_file()`; this + is probably more reliable and works even if the environment has changed, + but can we be sure it works correctly when reading the logfile from a pipe? + +## Refactorings to consider: + + * Modify `heartbeat` to use `os.difftime()` + + * Improve Lines: + + - Eliminate `Lines.current` and instead always use `Lines.get(0)`, + `Lines.get(1)` etc. We might store stuff in indexes 1, 2, 3 etc. and + make something like `Lines:get(val) => return Lines[val +1]` (this is + better than actually using index 0 because the lua standard library + counts from one, so adhering to this convention makes using it easier) + + - Reimplement the logic using <https://www.lua.org/pil/11.4.html> for a + small performance increase + +--- + +Code etc: <https://gitlab.com/lago/texlogsieve> + +Copyright 2021 Nelson Lago <lago@ime.usp.br> + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see <https://www.gnu.org/licenses/>. |