(X)HTML/XML in DDoc

[Borden]

I don't want to turn this thread into a DDoc-bashing rag, but 
another observation I've made is that, ironicaly, DDoc macros are 
not self documenting. If one types $(SOME_MACRO this, that, the 
other) it's not immediately obvious to what 'this,' 'that,' 'the 
other' refer without interpreting the macro definitions. Perhaps 
this was a design feature in order to transfer the formatting 
burden onto the .ddoc file, but I'm finding the exact opposite as 
I look through the DLangSpec.

In contrast, <some-tag attr1="this" attr2="that">the 
other</some-tag> is far more obvious in terms of what 
relationship the variables have to one another. Again, I'm not 
suggesting for a second that XML is the documenter's cure-all, 
but illustrating some of the things which make DDoc macros 
awkward to use.

What are the general opinions on La(Tex) in terms of code 
documentation? I only have a superficial understanding of it but 
it seems to follow many of the principles that DDoc incorporates. 
It also has the advantage that it's not quite as obtrusive as XML 
when writing from scratch. Then again, I read on Wikipedia that 
Knuth's next incarnation of Tex is going to be XML-based. XML 
seems to be the unavoidable trend in file design.