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
