Why I'm hesitating to switch to D

[KennyTM~]

On Jul 1, 11 03:10, Walter Bright wrote:
> 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().
>

Right. Perhaps d-p-l.org should replace those $(LINK2 x#y, z) by 
$(CHAPTER x, y, z) also. (or $(SECTION x, y, z) depending on what y is).

>
>>> 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.
>

OK.

I agree DDoc make a very easy to define and change a macro, but this 
isn't a unique capability of DDoc. (Also you write your own '.. 
cppcode::', as I've said before. It's just not as straight-forward as 
DDoc :) )

>
>>> 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.
>

If D can get a new keyword we won't see 'inout(T)' and 'auto ref' and 
'final switch' and all overloads of 'static' ;-) And missing a few 
keywords (say, __gshared) isn't fatal.

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

(actually I wanted to write "not that it's _a disadvantage_ in this 
context". My mind lost in the double negativeness :) )