On Jun 30, 11 11:57, Walter Bright wrote:
On 6/29/2011 3:56 PM, KennyTM~ wrote:
The easier, nicer, and more productive part:
- Native support of sectioning and anchors instead of sprinkling with
<h3> and
<a name>'s.
In Ddoc, you can define your own macros to do that, for example:
H3=<h3>$0</h3>
and then:
$(H3 This is a Header 3)
There is no reason whatsoever you are stuck with the defaults.
Right, it's possible, but it is ugly. Isn't the point to show the syntax
"easier, nicer, and more productive"?
Linking is also more natural.
What if the link points to another file? And what if sometimes you want
it intrafile, and another time interfile, without changing the source text?
Yes it is supported by Sphinx with the :ref:`target` syntax.
http://sphinx.pocoo.org/markup/inline.html#ref-role
In DDoc you have to write $(LINK2 foo.html#bar, bar). I don't see that
as a solution. For example, if you move MixinDeclaration to
declaration.dd, then existing link to MixinDeclaration will break
because you have to write $(LINK2 module.html#MixinDeclaration) or
define a macro in macro.ddoc, because DDoc can't automatically track the
targets. This won't happen in reST/Sphinx.
All existing approach listed in
http://d-programming-language.org/ddoc.html support inter- and
intra-file cross-referencing
And what if, for the unordered list, you wish to add a "class=foo"
attribute for one of them, and "class=bar" for another?
Why would you need to do that? Anyway, this is also supported by
docutils natively with the '.. class::' directive ('.. rst-class::' in
Sphinx):
.. rst-class:: foo
* 1
* 2
* 3
.. rst-class:: bar
* 4
* 5
* 6
http://sphinx.pocoo.org/rest.html#id2
http://docutils.sourceforge.net/docs/ref/rst/directives.html#class
- 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.).
Let's say I have some C++ code, C code, and ASM code, and want them to
use different css classes. In Ddoc, I'd do:
$(CCODE
... C code ...
)
$(CPPCODE
... C++ code ...
)
$(ASMCODE
... asm code ...
)
and by defining the macros, I can set them to use div's, pre's, whatever
attributes I want, and do this as many times as I need to for ALL of the
constructs.
That's not an advantage of DDoc. As I've shown above you could use the
'.. class::' directive to assign classes, and it's also possible to
write your own directive or inline marker, more than DDoc's simple macro
system can do (e.g. it can create Phobos's links on the top without
relying on Javascript), and you could even use the '.. raw::' directive
to drop down to HTML.
But whether the document writer want to expose to these capabilities
frequently? I'd say no, they'd rather have functions to format the
document nicely by default.
Furthermore, Sphinx has the '.. code-block::' directive to even syntax
highlight those C and C++ code for you.
.. code-block:: c
int main() { return 0; }
.. code-block:: c++
template <typename T>
T min(const T& a, const T& b) { return a < b ? a : b; }
.. code-block:: gas
pushl %ebp
movl %esp,%ebp
pushl %edi
pushl %esi
pushl %ebx
subl $0x000001ec,%esp
calll 0x000c5361
popl %ebx
http://sphinx.pocoo.org/markup/code.html
Generally, how good or how bad your Ddoc source looks like depends on
how you've defined the macros.
This could be applied to everything, like C++ vs D ;). I'd rather the
source look good out of the box than having to define dozens of macros
to make it look good.
