Inline code in the docs - the correct way

[Adam D. Ruppe]

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.