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