dlangspec.pdf?

[Walter Bright]

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.