Chris Molozian wrote:
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?
Look at how many of those tools support D.
> Again wouldn't that mean less custom tools to maintain.
I doubt it. The source for DDoc is only 2000 lines of code (and it's
simple code). D has enough unique features that you need to fight with
your document generation system, if it doesn't natively support D.
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 <[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?).
