Latex. The document object model is stupid. The Latex language's syntax and semantics are weird and idiosyncratic. Every Latex package uses its own weird conventions. It's slow. But there are thousands of packages out there for almost any conceivable problem you might have. And that makes Latex very very useful. But it is not well-designed software.
I have used LaTeX “forever”, basically since it was first created. As so many longtime LaTeX users, I have a love-hate relationship to it: I love it for what it allows me to do. Nothing else comes close. And yet, the number of hours wasted swearing at it while debugging something or other is beyond count.
There is an interesting ongoing project to replace it, though: Namely, finl (“finl is not LaTeX”) by Don Hosek, himself a longtime TeX/LaTeX user and developer.
That is a very ambitious project though, and not one finished in an afternoon. Se we will be stuck with LaTeX for years to come.
There's not DOM outright: each command is just a macro that is designed to expand to "the right thing". More or less.
More in general, I tend to hate all macro languages, like LaTeX, M4 and the C/C++ preprocessor (fortunately in the latter case the impact is usually more limited, because the C/C++ preprocessor layer is thinner than, e.g., a LaTeX document). They tend to require a lot of shenanigans even to make easy things, so the source quickly become a tangled unmaintainable mess, when each time you touch something, you make seemingly unrelated errors appear.
For a trivial example, consider in C:
#define IDENTITY(x) x
In any reasonable language you would expect that if you see `IDENTITY(y)` you could replace it with `y`. Of course not with macro languages.
Yes, I spent several months lovingly creating an open source LaTeX tool in the last few years. And yet... yes, you're right of course. I hate those stupid PDF "manuals" that each package has -- they have to be one of the least successful media for teaching anyone how to use anything!
I guess it is a case of eat your own dog food. But LaTeX and PDF have existed for longer than any more flexible format suited for the task. And last but not least, if the documentation is to actually show you the typeset result using the package, it is hard to get around the PDF format. (Though you can always embed images of typeset excerpts in documents of a different format.)
I think my problem is that they never seem to contain an introduction to how to use the package; they seem to be a mixture of API reference and jumping-immediately-into-obscure-details.
