On 09/14/2016 09:28 AM, Manu via Digitalmars-d wrote:
... I'm just gonna go on the record and say that I am really, really
not enjoying ddoc ;)

I was using ddoc today for the Greeks in DIP1000 and was musing about what makes it annoying. I think a major part is the macro invocation syntax: $(MACRO a1, a2, a3). After writing it for a few dozen times today, I figured it's objectively awkward to type (at least on the US keyboard): the dollar sign followed by the left paren is just unpleasant for mechanical reasons.

The resulting look is alien too, as opposed to the more familiar $MACRO(a1, a2, a3) or the CPP-style MACRO(a1, a2, a3).

There are a couple of un(der)documented tricks without which life is very difficult. For example, people commonly believe that in order to embed a literal comma they need to go like this:

COMMA = ,

and then $(MACRO Hello$(COMMA) world, a2). That scales poorly with the size of the argument. In fact, there's a much better solution:

ARGS = $0

and then $(MACRO $(ARGS Hello, world), a2) allows any amount of text with commas. Sadly no similar solution for unpaired parens.

Also, the fact that the doc opens with the text and then has an obscure "Macros:" line at a point is unpleasant. The macro definitions should come first, followed by a separator and then the content. That would make for a much nicer flow.

There are a few other macros I never leave home without:

ARGS = $0
COMMA = ,
DOLLAR = $
LPAREN = (
RPAREN = )
TAIL = $+
COLON = :
LF = $(LF)
$(LF)
COMMENT =
SP = $(COMMENT space coming) $(COMMENT that was a space)

TAIL sadly doesn't work properly.

Overall: I'm trying to build a list of ddoc grievances that can be fixed. It's the de jure and de facto standard for D documentation (with the ddoc processor or ddox), so we'd do good to improve it.

Please add your own ideas.


Andrei

Reply via email to