Why I'm hesitating to switch to D

[Walter Bright]

On 6/30/2011 6:28 AM, KennyTM~ wrote:
>> No, you don't have to. I'll often write it as:
>>
>> $(CHAPTER foo, bar)
>
> The 'foo' is still here. By natural I mean once you have a 'bar', you often
> don't need to care about the 'foo'.

Right, I agreed that Sphinx does better with that detail.

> Also, in d-programming-language.org $(LINK2
> x.html#y, y) is used, but $(CHAPTER x, y) does not exist.

Right, but defining your own macros is completely trivial, and when using Ddoc 
for more than a few lines, I'd expect one to define helpful macros specific to 
what you're writing.

If you're going to avoid writing such macros, then writing Ddoc source is 
probably going to be clumsy. It's just not meant to be used that way - like 
trying to write C code without writing any functions other than main().


>> With Ddoc, you can read the HTML manual and apply it directly to Ddoc.
>> Ddoc doesn't even know what HTML is, so it has no need to replicate its
>> functionality in a same-only-different manner.
>>
>
> Neither does Sphinx. '.. class::' is not tied to HTML either.

I think you misunderstood me. I meant I don't have to learn a separate-but-equal 
markup language. If I know html, then using Ddoc is a no-brainer to use. If you 
need more than a few minutes to get the hang of it, something is wrong. Maybe if 
you're unfamiliar with text macros, but I can't see a person competent to write 
programming manuals not knowing them.

Expecting someone who's expertise is flower arranging to learn/use Ddoc is 
likely a hopeless task.


> If you need all of these attributes, why not use raw HTML (yes there is '..
> raw::')?

Because writing HTML more than once is a giant annoying pain. With Ddoc, I hide 
those naughty bits in a macro, then use the macro.


> How is '.. class:: cppcode' different from '$(CPPCODE x)' in terms of redundancy?

Since CPPCODE is a macro, it can expand to anything. I can use it to set the 
html tag, font, color, size, class, whatever. And, I can *change* it globally by 
changing the macro, not by editing each instance.

It's the same rationale for why we have user-defined aliases, classes, and 
functions in programming languages.

I think I've completely failed to make that point.


>> What if you have something it doesn't highlight for you? Like D? :-)
> You contribute to Pygment! :)

:-(

> BTW it *does* highlight D. See http://pygments.org/languages/ for the support.

And when D gets a new keyword? Everyone has to wait for the next upgrade cycle 
of Sphinx. With Ddoc, it's automatic.


> OTOH, DDoc doesn't highlight anything besides D (not that it's an advantage in
> this context).

That's right.