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

Reply via email to