colour lib needs reviewers

Patrick Schluter via Digitalmars-d digitalmars-d at puremagic.com
Thu Sep 15 02:46:07 PDT 2016


On Thursday, 15 September 2016 at 03:49:55 UTC, Andrei 
Alexandrescu wrote:
> 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.

doxygen is mostly javadoc compatible and that one is the standard.
(in fact the \ can be replaced by @ every where) and it allows 
direct html tags. The good thing about doxygen is that it 
supports also markdown.
There are also some niceties like auto brief and autoreferencing 
(when a symbol is written in a text will be clickable if its body 
was reachable during generation of the doc).

>
> 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.)
>
Probably. But be reminded of your remark in the SDLang vs. JSON 
thread from last year:
"...this is a strategic error. Please throw s/SDL/DDOC/ away and 
use a standardized file format. -- Andrei



More information about the Digitalmars-d mailing list