On Jun 30, 11 02:20, Walter Bright wrote:
On 6/29/2011 6:12 AM, James Fisher wrote:
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.
Ok, so take lex.dd (or another page, pick any) and show how it is so
much easier, nicer, and more productive to express it using some other
markup format.
Ddoc:
https://raw.github.com/D-Programming-Language/d-programming-language.org/master/module.dd
Output: http://d-programming-language.org/module.html
reStructuredText (+ Sphinx):
https://raw.github.com/kennytm/dmd/gh-pages/module.rst
Output (using Sphinx's default stylesheet): http://kennytm.github.com/dmd/
The easier, nicer, and more productive part:
- Native support of sectioning and anchors instead of sprinkling with
<h3> and <a name>'s. Linking is also more natural.
- One could use an external Turing-complete parser (in Python, though)
for some special block of documentation, e.g. the grammar list, instead
of having to hack the macro system for the result. The latter is like
having to highlight the D code using $(RED x) $(GREEN x) $(BLUE x) manually.
- Writing reST is really like writing document. Writing DDoc is like
writing Lisp.
- reST has better support than DDoc is many aspects (output format,
stylesheets, plugins, documentations, etc.).
