Inline code in the docs - the correct way

[Adam D. Ruppe]

On Wednesday, 31 January 2018 at 21:34:47 UTC, H. S. Teoh wrote:
> Coming from you, I'm a little surprised.  Weren't you one of 
> the people complaining that ddoc macro syntax is ugly?

$(H1 Rebuttal)

It depends how you use it. For large blocks or for small, special 
bits, it doesn't bother me.

So if I wanted to $(I point out) something in the middle, it 
doesn't bug me.

$(QUOTE
Similarly, if I want to call out a whole block of text,
ddoc has some nice bits, like how easily it nests and can
be added around existing text without thinking about it.
)

$(H1 But...)

$(P Where it starts to bug me is when you are using it $(I all 
over the place), especially with $(B random nesting).)

$(P It is obnoxious to write on every paragraph, for example.)

$(TABLE $(TR $(TD $(P or trying to make a table out of it) $(P 
especially if it is
randomly formatted in the source. $(BR) $(B yikes!)))))



Phobos does a lot of that latter filth, and almost never even 
tries to format it, making it even worse.

My adrdox tries to eliminate most of the latter stuff Phobos 
uses, but it retains the ddoc syntax for the stuff I don't mind. 
In fact, I kinda $(B prefer) it to the *markdown way* in some 
places, since at least the ddoc is deliberate. Only thing that 
bugs me is when I try to write :) or 1) or similar in there but I 
plan to fix that.


Now though, inline code like $(D) and $(REF) are ambiguous. They 
are short enough that they'd normally fall into my "ok with it" 
zone like $(B)... but they are also so common and I want to 
encourage their use. And having three shifted characters that 
must appear in order is kinda painful to type - it just breaks up 
the thought process, and can get somewhat weird to look at.

So like I probably wouldn't write "The $(REF SimpleWindow) class 
is used along with the $(REF EventLoop) to create a window." 
without actually thinking about it, but "The [SimpleWindow] class 
is used with [EventLoop]" is almost thoughtless to type.


The latter may be slightly easier to read.... but I think the 
bigger difference is just the friction in typing it the first 
time in this case. Emphasis ought to be rare anyway, but 
interlinking ought to be very common. I'm very very skeptical of 
claims of "it is faster to type" being significant... but easier 
to type I do think makes it more likely to be used. Most macros I 
think ought not be used frequently but this is different.

BTW adrdox does [reference] instead of `reference` linking 
because of what I said before: `code` is too generic. It isn't 
necessarily a link. Moreover, my [reference|also allows 
alternative text to display], which wouldn't work well in ``.