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.


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

Reply via email to