Here’s a question for folks. Currently Tectonic has three gradations of user communictions:
Note
Warning
Error
I’d say that these are pretty standard. But I’ve been a bit tempted to add a fourth one, making it:
Note
Warning
Severe (?)
Error
The “severe” category would be for problems that are very worrisome, but we can keep on processing. Errors would be for showstoppers.
This actually maps more closely to the gradations used by the underlying TeX engine — except what I would tentatively call “severe”, TeX calls “errors”, and what I call “errors” TeX calls “fatals”.
Does this seem like overkill? Any thoughts about the terminology? I’m a little dissatisfied because “severe” is an adjective not a noun, but I think in practice the user experience would be pretty fine.
I believe that in an ideal world, we would really not need the severe warning category: either the TeX engine fails because of an error in the input, or it produces a document, possibly with clearly specified issues (warnings), like missing references, overflows, etc.
If I understand your proposal, “severe” would be reserved for internal engine bugs. Or do you have in mind an example in the “severe” category, which would not be an internal engine bug? Hopefully, these would get ironed out with time and the “severe” would become less necessary.
a “warning” is what you get when something unusual happened, but your output document is probably going to be fine.
a “severe” is what you get when something worrisome happened and your output document is probably going to be messed up, but the engine thinks it can continue running and produce some kind of output file.
an “error” is when something so bad has happened that the engine can’t continue.
My understanding of TeX is that these map pretty directly onto its “warning”, “error”, and “fatal” categories.
I see. Though at the moment, tectonic runs the engine with the halt_on_error flag, so tex errors stop the processing.
I believe that this is the right approach. Tex “recovers” from the errors by inserting stuff or assuming defaults, which is almost never what you want. It usually just hides a serious problem that will bite you later. Does anyone these days require a tex engine to compile documents with errors? Or use the interactive mode?
I think that the motivation to recover from errors was appropriate at the time when tex was created: computers were much slower so I assume that a compilation might have taken minutes, maybe hours? In such a case it would be very frustrating to stop on a missing $ or }, and the interactive mode might have been very useful. But nowadays one just fixes the error and recompiles in seconds…
For me, error handling is one of the weakest points of tex, and I believe that tectonic could improve on this in the future: at least give more accurate error messages that are easier to parse for editors (if this is even possible).
So in my opinion, “error” and “warning” levels are enough: if the document is malformed, tectonic should not produce any output and indicate an error. Just like a regular compiler.
If you choose to follow the tex approach, 3 levels are fine. But then I guess we could just stick to the tex naming convention: “warning”, “error” and “fatal”. “severe” sounds to me very much like an “error”.
Also, not to forget, tectonic currently does not report LaTeX and Package warnings, for instance. These include missing references and such.
I’ve been thinking about this a bit, and since we have a full access to the engine internals, we should be able to track which macro expansion in a user’s code caused these warnings, hopefully even locating it in the source. LaTeX ecosystem seems to consistently use \GenericError and \GenericWarning latex commands to generate them.
Yes. I think the most sensible path forward for LaTeX-level warnings is to patch commands like \GenericWarning inside the bundle, inserting Tectonic-specific commands to present the messages in a more user-friendly way. This was the approach I took with my first foray into messing with a TeX engine, Webtex, and it was effective.
I think that it might be a little bit more straightforward to just patch the engine to detect the expansion of \GenericError and \GenericWarning and read the expanded arguments (or just parse whatever is printed to stdout, that might be easier). For instance id_lookup seems like a good starting point, when it is called in get_next.
Hmmm. At first blush I would like to avoid putting LaTeX-specific detection logic into the engine like that. Especially since the core files will be delivered through the main resource bundle, over which we have complete control. If we can edit the definitions of \GenericWarning and friends directly, I think there would be only a couple of precise interventions that would need to be made. But once someone gets to implementing this, maybe other tradeoffs will become more clear.
I’ve also thought about trying to parse the messages that get printed to stdout … it seems like a pretty painful undertaking since different packages seem to print out messages with very different formats, and don’t always do so on one line. But this might be the sort of thing where you can get 90% of the functionality for a fairly reasonable amount of effort.