Inline code in the docs - the correct way

[H. S. Teoh]

On Wed, Jan 31, 2018 at 10:55:38PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
> 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.

Then I guess we differ on this point.  While I think the ddoc macro
system, *as a macro system*, is pretty elegant in and of itself, I
personally can't stand mixing it in with ddoc comments, which I've grown
accustomed to be plain ole text, like other code comments.  Interpreted
differently by the compiler, sure.  But having a different syntax? I
find it too jarring and distracting.


[...]
> $(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!)))))

Urgh, as if $(I this syntax) isn't already jarring enough, inserting
what is basically a poor man's transliteration of HTML into ddoc syntax
into source code is just ... it makes me wanna reach for the
'mark-block-delete' key combo in Vim.

In general, almost all text macro / formatting systems, from LaTeX to
HTML to ddoc, are universally ugly and verbose when it comes to tables,
and makes my eyes bleed. The only exception I've found so far is
markdown, where you can actually write this:

	|Blah|Blah|
	|----|----|
	|abc |def |
	|ghi |jkl |

It's not perfect, but it's worlds better than the line noise syntax of
the alternatives.


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

Yeah, I'm not really a fan of *...* or _..._ in markdown syntax. It's
just too easy to mix them up / misidentify them for identifiers in code
or expressions, esp. if C-like pointer dereference syntax is used.
Though I suppose that's what `...` is for.

But then again, I rarely find the need to have emphasis in technical
docs, so it's not a biggie.  And I do still prefer *...* over $(B ...).
I just don't like alphabetical macro names interspersed with text; it
makes it hard to parse the text with the eye.


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

This is why I prefer markdown-style syntax.


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

Actually, for me it's not so much a matter of "it's faster to type";
it's more of an issue of "when I'm reading (and presumably thinking
(hard) about) source code, do I really want to expend the mental
resources to parse the syntax of yet another embedded DSL inside a
*comment*?".  If I had my way, I would just write a normal comment as
opposed to a doc comment.  What makes the doc proposition attractive is
that, in an ideal world, a "normal" comment can be automatically
translated into nice docs without needing to pepper-spray it with
foreign syntax particles, so that I can read the comment while working
on the code, in addition to having nice docs to show to others in a
format they prefer, like HTML or whatever.

That's why I would actually welcome markdown-like syntax in ddoc. Yeah,
it has limitations and sux in many ways, but IMNSHO you shouldn't be
reimplementing complex HTML syntax inside a doc comment anyway -- leave
that to an external templating engine or whatever you wish to use, and
just let the doc comment be as readable as possible *as source code*.


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

I wouldn't expect `...` to produce a link; it should just be formatted
differently (typically in monospace font) to indicate that it's a code
snippet. Using [...] syntax for links makes more sense to me, even
though personally, I really prefer to just write plain ole text and
paste the URL in its own indented block:

	http://example.nowhere.edu/blah/blah/blah

Let the templating engine or whatever identify the link for me and
produce whatever HTML spew is necessary to make it work in a browser,
just leave my source code alone already!


T

-- 
Shin: (n.) A device for finding furniture in the dark.