I very much agree. When it comes to lightweight markup languages for use
in web (and more) templating there's: Markdown
<http://daringfireball.net/projects/markdown/>, Markdown Extra
<http://michelf.com/projects/php-markdown/extra/>, Haml
<http://haml-lang.com/>, Textile <http://textile.thresholdstate.com/>...
to name just a few. Is it worth maintaining another tool?
When it comes to documentation within source files couldn't D adopt one
of the many different
<http://en.wikipedia.org/wiki/Comparison_of_documentation_generators>documentation
generators? Again wouldn't that mean less custom tools to maintain.
Unless of course ddoc does something more than these other tools?
Cheers,
Chris
On 06/29/11 09:38, James Fisher wrote:
On Wed, Jun 29, 2011 at 7:46 AM, Jacob Carlborg <d...@me.com
<mailto:d...@me.com>> 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?).
