On 1/5/2013 7:14 AM, Philippe Sigaud wrote:
Since I just remade a 180-pages tutorial on D templates in markdown without much trouble, I guess documentation and tutorial are different beasts. I felt no need for macros, really, but I can see how they are useful for Ddoc pages.
Having macros in Ddoc have been a godsend for improving productivity. For example, some bits need to be added or removed for generating an ebook - macros handle that in an ideal fashion. They're great for adding boilerplate, when urls need to be mass changed, etc. It just goes on.
Note that markdown was crafted to be readable by itself, even though its final goal is to be rendered in HTML. Ddoc has no such compulsion (some macros are a bit obscure for me when I read documentation in raw form) You know, I always felt Ddoc was a strange sublanguage bolted onto D. An elegant solution would be to have macros be D code, but I have nothing to propose here.
It is a strange sublanguage. It has its problems, but compared to what D documentation was like before Ddoc, it is a HUGE and incalculable leap forward. The Phobos documentation, for example, before Ddoc was complete and utter garbage that rarely had any correspondence to what the code actually was and did.
And, btw, I have published on Amazon a couple of non-tech ebooks. I used Ddoc for them, and there is no html feel to the result. They look like any other ebook.
