colour lib needs reviewers

[Andrei Alexandrescu via Digitalmars-d]

On 9/14/16 9:28 PM, Manu via Digitalmars-d wrote:
> 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 ;)

I don't see those workarounds to ddoc shortcomings. m4 and all macro 
systems I know of have similar idioms. It's the nature of macro 
processing. Are you simply saying you're familiar with other 
documentation tools and are not motivated to get into another one? 
That's entirely fair.

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

I have difficulty understanding this. I haven't looked at Doxygen in a 
long time and never really used it, but from what I see at 
https://www.stack.nl/~dimitri/doxygen/manual/commands.html it seems the 
\tags you refer to are just a form of macros. The syntax is different, 
i.e. you'd write \a hello whereas in html you'd write <i>hello</i>, in 
latex \textit{hello}, in ddoc $(I hello). It's a matter of syntax and 
though I agree syntax matters (and it would be nice to make ddoc's more 
configurable), is it right to assume you simply want a syntax you're 
more familiar with?

How do you mean people "type docs in the way they've been doing for 
decades"? Are you implying doxygen not only has been around for decades, 
but it's been some sort of ubiquitous standard? Honest question, I'm 
definitely not getting that.

Does this boil down to - if we replace the macro syntax with one closer 
to doxygen things will just click? (That may as well be the case.)


Andrei