Why I'm hesitating to switch to D

Walter Bright newshound2 at digitalmars.com
Thu Jun 30 03:25:15 PDT 2011


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.


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

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

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

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.

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

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!)

(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?

> 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? :-)


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

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.


More information about the Digitalmars-d mailing list