Donald Knuth – The Patron Saint of Yak Shaves

Plus that you might have to run it multiple times in the hopes that it'll eventually converge.

Sometimes you don't even get an error, only warnings, and still the thing won't compile … Also, overfull hbox. Still don't have an idea how this happens so often, even less why I should bother

This sentiment is basically the default from my experience and one I know all too well myself. It's a lot like makefiles and shell scripts in this way.

I can't really comment on what Knuth did right or wrong, but for me reading The TeXBook pretty much made Tex fun where it had previously felt arcane and frustrating. I'm convinced that overall the few hours invested there ended up saving me more hours of frustration on my masters thesis.

It seems that there's room to say that we should learn our tools before cursing them. Typography is surprisingly subtle and fraught with challenges, and I'm not yet convinced that it's a problem that can be made to Just Work in all cases.

To the contrary, TeX (not LaTeX) has one of the best error-handling and error-recovery interfaces of any commandline program — if you use TeX as Knuth intended, that is, if you use plain TeX at the commandline and if you have read the entertaining chapters in The TeXbook on dealing with errors. Just try using plain TeX (not LaTeX) for a few months and you'll find that the behaviour when errors happen is one of its delights, the opposite experience from when you use LaTeX. (Of course, you may miss many conveniences from LaTeX, but the error experience is itself almost worth the change.)

Knuth has done a great job that should be the model for all other software writers: every error is described in two ways, one somewhat formal and one somewhat informal, and every error is shown with enough context (and this is configurable too) for you to quickly see what the issue is, and you can even fix errors without having to abort the compilation. He has a great talk where he describes how the English language is optimized for dialogue (things like "I" and "you") and TeX messages are designed in that way.

Unfortunately, LaTeX consists of several layers of complicated macros (all in the name of making things convenient for, and hiding things from, the user) and as they (correctly) decide that all these layers won't make sense to the user, they actually turn off all the context that goes with the error, leading to error messages that are incomprehensible even to experts. But I don't think it's right to blame the fact that LaTeX didn't bother to implement good error-recovery on TeX.

Knuth does not think TeX is feature-complete: he said “it is axiomatic that any complex system can be improved”; the current state is just where he decided to stop and make his “responsible exit” (his term from a recent talk!) after about a decade of working on TeX and METAFONT. See his 1990 article/letter The Future of TeX and METAFONT (https://www.tug.org/TUGboat/tb11-4/tb30knut.pdf) where he writes:

> My work on developing TeX, METAFONT, and Computer Modern has come to an end. I will make no further changes except to correct extremely serious bugs. […] I strongly believe that an unchanging system has great value, even though it is axiomatic that any complex system can be improved. Therefore I believe that it is unwise to make further "improvements" to the systems called TeX and METAFONT. Let us regard these systems as fixed points, which should give the same results 100 years from now that they produce today. […] anybody can make use of my programs in whatever way they wish, as long as they do not use the names […] In particular, any person or group who wants to produce a program superior to mine is free to do so. […] Of course I do not claim to have found the best solution to every problem. I simply claim that it is a great advantage to have a fixed point as a building block. […] I welcome continued research that will lead to alternative systems that can typeset documents better than TeX is able to do.

Care to share?

That sounds remarkably like Pandoc. Have you tried it?

Sphinx can do that, using reStructuredText as its input language. In lieu of a button, run this:

  make latexpdf epub text html

Each publishing house and newspaper has a home-grown pipeline to do something close to this.

With work, you can get something that does most of what you want with a few stacks. You can cobble it together for markdown. Alternatively, there are strong plugins to emacs org mode that can go to TeX, then postscript, then PDF. There is probably a stack centred around docbook as well.

My experience has been that if you care about details, you will need to write parts yourself, as you have done. Emacs org mode is a good starting point. You can create your foundation data structures in org-mode trees, and then transform out to the main render pipelines (TeX, etc).

Why? It's correct. You run a tool to convert the Web source to Pascal. If you want to compile TeX on modern computers, you run another conversion step to convert the Pascal to C, but Knuth used a real Pascal compiler when he made TeX.