On Wed, Jun 29, 2011 at 12:25 PM, Walter Bright <[email protected]>wrote:
> Ddoc is: > > 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. > > 2. It automatically tracks the D language, so D code examples are always > properly highlighted. > > 3. It is always available and installed for anyone who installs D. > > 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. > > 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. > > 6. And lastly, it works, it delivers, and has for many years. It's proven > its worth. > 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 -- lex.dd<https://github.com/D-Programming-Language/d-programming-language.org/blob/master/lex.dd>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.
