<div class="gmail_quote">On Wed, Jun 29, 2011 at 12:25 PM, Walter Bright <span dir="ltr"><<a href="mailto:newshound2@digitalmars.com">newshound2@digitalmars.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex;">
<div class="im">Ddoc is:</div>
<br>
1. Rather trivial to learn & use. A website/book/community devoted to how to use it is completely unnecessary. It's fairly obvious how to use it (for someone with a basic familiarity with HTML) by simply looking at a couple examples.<br>

<br>
2. It automatically tracks the D language, so D code examples are always properly highlighted.<br>
<br>
3. It is always available and installed for anyone who installs D.<br>
<br>
4. The D compiler and Ddoc are always in sync. No begging for updates from 3rd parties, no lags even if they get right on incorporating necessary updates.<br>
<br>
5. It is not necessary to direct anyone to install some third party system that may not even exist on all the platforms D does. In general, we try to minimize dependency on things that are not default installed across operating systems.<br>

<br>
6. And lastly, it works, it delivers, and has for many years. It's proven its worth.<br></blockquote><div><br></div><div>OK.  These are all good reasons to maintain code documentation in Ddoc -- i.e., the Phobos documentation.  Let's drop the argument over replacing the documentation format.  What I'm not convinced of is that Ddoc is has any advantage over a generic markup format when it comes to the homepage, associated pages (FAQ, acknowledgements, etc.), howtos, or even the language reference.  When I look over any of those documents -- <a href="https://github.com/D-Programming-Language/d-programming-language.org/blob/master/lex.dd">lex.dd</a> to take a random example -- I don't see any semantics that can't be expressed even in something as simple as Markdown.  Forcing people to write their howtos in Ddoc is asking too much for no good reason.</div>
</div>