colour lib needs reviewers

[Andrei Alexandrescu via Digitalmars-d]

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