On 2011-06-29 10:38, James Fisher wrote:
On Wed, Jun 29, 2011 at 7:46 AM, Jacob Carlborg <[email protected] <mailto:[email protected]>> wrote:On 2011-06-28 23:09, Walter Bright wrote: 5. I know I suck at web site design, which is why David Gileadi helped us out by designing the d-programming-language.org <http://d-programming-language.org> look & feel. I think it makes it hard when most of the pages are written in DDOC. It doesn't help to attract web designers. I'd definitely agree with that. I have no experience with DDOC, but TBH I don't intend to ever have any. As a general criticism of DDOC, it seems like another reinvented wheel. Semi-plaintext formats surround us like the plague, and for every use case for documentation, there's a better option. If you want * simplicity, use Markdown <http://daringfireball.net/projects/markdown/>. Supported everywhere, like GH. * bulky extensible semantic documentation, use DocBook <http://www.docbook.org/>. Used by O'Reilly, I'm told. Presumably that's how Real World Haskell <http://book.realworldhaskell.org/> is maintained as a slick website and an O'Reilly book. * readability, but power and extensibility if required, use docutils <http://docutils.sourceforge.net/>/Sphinx <http://sphinx.pocoo.org/>. Used for the Python standard library documentation <http://docs.python.org/py3k/>, which, as anyone who has used it knows, is The Best Documentation In The World. That said, I suspect DDOC is now entrenched at least in the stdlib documentation, so maybe we'll have to live with it. However, the case for using it for the website <https://github.com/D-Programming-Language/d-programming-language.org/blob/master/index.dd> is nonexistent (anyone disagree?).
HTML or some kind of other language can be used for the web site and DDoc for the actual documentation.
-- /Jacob Carlborg
