Why I'm hesitating to switch to D

[KennyTM~]

On Jun 30, 11 18:25, Walter Bright wrote:
> On 6/30/2011 1:26 AM, KennyTM~ wrote:
>> Right, it's possible, but it is ugly. Isn't the point to show the syntax
>> "easier, nicer, and more productive"?
>
> Ddoc has pretty much only one syntax. Sphinx seems to have a lot of them.
>
>

OK, if that's a concern.

>>> 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
>
> What's natural about that?
>
>> In DDoc you have to write $(LINK2 foo.html#bar, bar).
>
> 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'. Also, in 
d-programming-language.org $(LINK2 x.html#y, y) is used, but $(CHAPTER 
x, y) does not exist.

>
>> 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.
>
> Yes, the idea that a link may be somewhere in a collection files, is
> probably better.
>
>>> 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?
>
> Style sheets. For example, sometimes you want a list to go out
> horizontally rather than vertically; this is controlled by the style
> sheet. You specify a class for the list, and then the layout for that
> class.
>

OK.

>> 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
>
> This I don't particularly like. I've got to learn a new syntax for it,
> I've got to read and learn a manual on what 'class' means for Sphinx and
> do some spelunking to figure out if it is the same thing as an html
> class or something different. The syntax arguably isn't better, either.
> It's just different. Even worse, if I want to change the classes, I've
> got to do a global search/replace. With Ddoc, I change one macro.
>

You don't have to use '.. class::'! Directives can be manually-defined 
also. I'm just illustrating this is possible with the requirement 'you 
wish to add a "class=foo" attribute for one of them, and "class=bar" for 
another?'

(Also I didn't say _you_ have to learn reST. For instance, the site 
could be maintained by some other people in Digital Mars or the D 
"committee".)

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

> HTML has lots of these attributes. Are they *all* in Sphinx? What if a
> new one is added to HTML? What if I want to use :: in my text? One
> problem with a lot of text markup is you've got to provide escapes for
> all that - which is why Ddoc pretty much sticks to $.
>

If you need all of these attributes, why not use raw HTML (yes there is 
'.. raw::')? Besides, the output may not be HTML. Sphinx supports LaTeX, 
ePub, man page, texinfo, etc. That should also be the same for Ddoc.

You can '::' escape it as ':\:', and '::' is special only at the end of 
a line. In Ddoc there is $(LPAREN) and $(RPAREN) and & also.

> In Ddoc, for another example, I did the documentation for the Digital
> Mars C++ runtime library. For web pages, I formatted things using
> definition lists. Unfortunately, those came out badly in the Kindle, but
> using h4 instead worked much better. Since I had written the docs in
> terms of a higher level Ddoc macro, I simply changed its definition to
> use h4 instead of dl, and voila! thousands of library functions got
> fixed without incredibly tediously recoding each one.
>
> For me, a viable doc system needs to have some sort of symbolic
> redefinition capability. Textual macro processors have existed for a
> long time, and they work well for that, which is why Ddoc went that
> direction. (You might notice that Ddoc macros are a lot like makefile
> macros!)
>

OK.

> (I did consider using the C macro preprocessor, but it is too
> specialized for C.)
>
>
>>> 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,
>
> Do I gotta do that every time I write a CPPCODE section?
>

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

>> and it's also possible to write your own
>> directive or inline marker,
>
> That would be better.
>
>> 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.
>
> The default works well 95% of the time. The rest of the time it doesn't,
> and if you have to leave the documentation system, it really sucks.
>
>
>> Furthermore, Sphinx has the '.. code-block::' directive to even syntax
>> highlight
>> those C and C++ code for you.
>
> 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. OTOH, DDoc doesn't highlight anything besides D (not that it's 
an advantage in this context).

>> I'd rather the source
>> look good out of the box than having to define dozens of macros to
>> make it look
>> good.
>
> The point is, you can customize the macros to match the semantic content
> of your documentation. It is not necessarily a low level thing. For
> example, I might want to document a library function like this:
>
> $(RTLENTRY name,
> $(HEADER name.h)
> $(PROTOTYPE
> void name();
> )
> $(DESCRIPTION
> name() is the greatest function evar!
> )
> $(EXAMPLE
> name(); // great things happen
> )
> )
>
> Or some such. Then, by manipulating the definitions of those macros, I
> can generate all kinds of different markup. I could set it up as h4's,
> h3's, tables, definition lists, etc. I could use a code font for HEADER,
> and regular font for DESCRIPTION.
>

Yes. But as I've argued before, you can't highlight code in $(EXAMPLE a) 
without relying on Javascript or other run-time solution.

> If I used a markup language with no symbolic ability, I would have to
> re-edit everything to change the layout of the output.
>
> This isn't just pie in the sky. I really do write Ddoc stuff like this,
> and really do change the layouts searching for something that is more
> pleasing.

Yes.