Why I'm hesitating to switch to D

[KennyTM~]

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.