summaryrefslogtreecommitdiff
path: root/support/texlogsieve/README.md
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2021-12-17 03:01:00 +0000
committerNorbert Preining <norbert@preining.info>2021-12-17 03:01:00 +0000
commit6827f87d3315fc677ae89a9260d455a312a90864 (patch)
tree88318243546c8d29294c2d21d5d7998ccd9d57a4 /support/texlogsieve/README.md
parent16b22a983bc0f05cbbb201a6e0f5cbbfc3c8fffb (diff)
CTAN sync 202112170300
Diffstat (limited to 'support/texlogsieve/README.md')
-rw-r--r--support/texlogsieve/README.md143
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/>.