colour lib needs reviewers

[Manu via Digitalmars-d]

On 15 September 2016 at 07:31, Andrei Alexandrescu via Digitalmars-d
<digitalmars-d at puremagic.com> wrote:
> 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.

I haven't had enough experience for meaningful input. I have
experienced the comma and parens things myself, and I generally just
hate that everything is a macro, like you said yourself above.
It didn't occur to me to attempt the sort of workarounds you
illustrated here, I rather just factored the commas and parens out of
my docs and moved on ;)

Like, I really just don't care enough to try and understand ddoc
sufficiently to have a bag of tricks like those you demonstrated above
to workaround these issues. It's not a skill I *want* to possess,
rather, in this case, it's a skill I'm being forced into.
You're welcome to call me lazy, I'd suggest I'm being realistic.
Perhaps a phobos contributor will be required to work it out (as seems
to be a requirement for me right now), but normal programmers
wouldn't. In 7 years, I've never been motivated to find workarounds to
ddoc shortcomings before now, and now, it's only because people are
hassling me. There's no intrinsic motivation here... one reason I use
D is because I hate the C preprocessor ;)

If I had to suggest, I'd introduce doxygen style \tags alongside the
macros, then when people try and type docs in the way they've been
doing for decades, it'll just work, and they can get on with their
code. Nobody likes writing documentation, it needs to have the minimum
possible friction or people just won't.

Added bonus; when you cut&paste C code to adapt bindings, the existing
docs on the C code would remain valid documentation without additional
amendment.
I bind C code regularly, and my goto 'solution' is to just remove the
doxygen doco comments from the translated code and point them to the
C/C++ docs instead.
Again, call me what you like, I think my behaviour is probably typical
though. I'm just being honest.