On Thursday, 1 February 2018 at 02:10:22 UTC, Jonathan M Davis
wrote:
Personally, I hate markdown, because it makes certain syntax
magical - e.g. it's not uncommon that a commit message ends up
looking bad when github uses it as the message for a PR,
because some piece of code contained * or some other piece of
syntax that markdown decides to do something magical with.
Yeah.
I _much_ prefer the explicit syntax used by ddoc, so I can't
say that I'm at all happy at the idea of markdown syntax being
added to ddoc.
I agree, which is why adrdox only has a few magic syntaxes at top
level and they are in places where I think it is more important
to be extremely convenient (like cross-linking*).
But, at the same time, some special syntax can be REALLY nice. So
I went with the hybrid approach: certain ddoc macro blocks
actually run magic syntax:
$(LIST
* List item here
* another list item
* third list item
)
The bracket clearly indicates that you want to opt-in to the
special syntax, then you get to use that syntax for a while for
the convenience. Another benefit is you can add other tweaks like
class names for the HTML inside the bracket since there is a spot
for that.
But anyway, the bracket also lets me use different syntaxes or
reuse the same in a few places and generate different things. And
BTW it is worth noting that ddoc ALREADY has a little bit of
this: see the "Params:" section!
* BTW I almost wanted that syntax to be a bit uglier so you can
embed it in code samples too unambiguously but that made me use
it less instead of more...
IMHO, the main problem with ddoc for documentation is that it
doesn't automatically handle stuff like cross-links, and it
fundamentally can't, because to do that properly, you have to
generate all of the docs at once with a standard layout for
where everything goes so that the links can link to stuff.
Well, maybe, it could do something like adrdox's symbol lookup
but instead of generating a link directly, it could replace it
with $(REF) and let the macro definitions handle it.
Wouldn't be perfect tho, that macro is clunky to use and define
because it doesn't know all the details, but it would be a move
up from what we have, and may even work inside code examples.
