summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/support/texlogsieve/README.md
blob: acc3204d907259cda4fa5309d37df4f44329d479 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
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/>.