adrdox vs markdown vs ddoc

[Adam D. Ruppe]

FYI I am changing the subject line with this post since it is 
branching off the original question of simple best practices of 
code in ddoc.


On Thursday, 1 February 2018 at 00:19:53 UTC, H. S. Teoh wrote:
> 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.


So adrdox actually supports that (though you must label it), but 
I actually kinda hate it because it is enormously difficult to 
edit.

Earlier today, in a work call, the non-programmers on the team 
asked me to define "beautiful code". I have two main criteria:

1) does it work?

2) is it easy to edit while keeping it working?


When people say "code is read far more than it is written", I 
usually disagree: the main reason I read code is when I have to 
edit it! If it is working fine, it disappears into the 
background. But when there's a bug, I read it... as a means to 
the end of fixing the bug, which means editing it.

So, technically, sure I'll agree it is read more than it is 
written, but code is rarely actually written just once. It needs 
to get edited for bug fixes, new features, and changing external 
requirements.


How does that relate here? Take your ASCII table above and fix a 
misspelled word in the upper left cell. If you wrote "mispelled" 
instead of "misspelled", you just need to add the missing 's'.... 
and then go back and add spaces and/or dashes on each and every 
row to line the '|' column back up.

In CS terms, it turned a constant-time edit into a O(n) 
operation, scaling linearly with the number of rows. But it isn't 
even the number of rows in the table, it is the number of rows in 
the source text, which can really explode when you need to 
elaborate in the table somehow:

+-----------------------+
| This header  | This   |
| needed three | does   |
| rows to fit. | not.   |
+==============+========+
| Here's some  | More!  |
| text.        |        |
+--------------+--------+

Let's add another word.

+-----------------------+
| This header  | This   |
| needed three | does   |
| more rows to | not.   |
| fit.         |        |
+==============+========+
| Here's some  | More!  |
| text.        |        |
+--------------+--------+


Adding a 5-character word there took me *29* edit operations, not 
counting navigation of the caret. Now, maybe you use some editor 
macros to clean it up instead of doing it manually, but I don't 
have those... and if you need a fancy editor macro to just add a 
word to a comment, I think the comment syntax has failed.

And how do you add a code sample inside the table? Oh I don't 
even want to try that.


And let me emphasize this: this is comment in source code. If you 
want to read it as an end user, you can render it to HTML or 
whatever. In the source code, if you are reading it there... 
again, it is probably because you are editing it!


Now, if a 5-character insertion requires 29 edit operations, what 
do you think the programmer is going to do? Keep up with it, or 
let the documentation stay slightly suboptimal and out-of-date 
because it is a hassle?



So, that syntax is nice for little tables that get trivial edits, 
but for larger info tables, I prefer writing it out as paragraphs 
some how. That's why adrdox also supports "table_rows" and 
"table_columns", which I borrowed from Python's restructured text.

It is basically a vertical list - similar to Markdown's nested 
list syntaxes - of rows and columns, or columns and rows.


See more of my stuff here:
http://dpldocs.info/experimental-docs/adrdox.syntax.html#tables

I don't love it all, but for the most part, I implement it 
because it is useful to me and I at least don't hate it (or 
because I was forced to for Phobos compatibility lol).

So my above thing becomes:

* + This header needed three more rows to fit.
   + This does not

* - Here's some text.
   - More!


So each * introduces a new row (or column, these must be 
bracketed to tell which style it is), then + introduces a table 
header, and - introduces a table cell.

Alignment is trivial now, since it is just leading indentation 
(and that's optional, but to be fair, actually aligning the pipes 
is optional in Markdown's tables too, but if you don't it gets 
ugly anyway in both cases).

Adding a new word there? Constant time operation again. Adding a 
code sample is simple too, you can write it vertically like any 
other.

And it isn't quite as beautiful as the ASCII table for some 
cases... but it is still very legible in plain text source view, 
while being infinitely easier to edit.


BTW this is my big justification for bracketed syntax: putting 
$(SMALL_TABLE) or $(TABLE_ROWS) or $(LIST) around those bullets 
tells the parser not only that you are intentionally opting into 
special syntax, but also tells it exactly how to interpret it. So 
we can reuse these simple bullet-point lists in the source for a 
couple different render modes.

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

Yes, the `...` stuff handles that, but is also just bugs me 
because when I write something like *foo* I actually DO intend 
for it to be rendered as *foo*, not as bold foo.

For example, I like to text my friends "*hugs*". It kills me when 
that gets bolded. (yes, i know i can write \*hugs\* but barf.)

Granted, I'm not frequently writing *hugs* in technical 
documentation, but the principle bugs me. Every time something 
like Facebook bolds my hugs it makes me hate markdown a little 
bit more.


>  If I had my way, I would just write a normal comment as 
> opposed to a doc comment.

Ironically, ddoc was supposed to be that. 
https://dlang.org/spec/ddoc.html

[quote]
D's goals for embedded documentation are:

     It looks good as embedded documentation, not just after it is 
extracted and processed.
     It's easy and natural to write, i.e. minimal reliance on 
<tags> and other clumsy forms one would never see in a finished 
document.
[/quote]


BTW, I also hate any syntax that requires editing every line. 
Again, it goes back to that linear vs constant time edit. I just 
copy/pasted that from the website. Using bbcode or html or ddoc 
or adrdox, you just surround it with some tag like I did there. 
Even indenting it is not really necessary to make it legible and 
functional (though like every editor makes that simple anyway).

I prefer markdown's ``` blocks to the leading for spaces 
primarily for this reason, though adding language tags is a 
secondary benefit to that.

This is also why I friggen hate comments with leading stars:

/*
  * why write all
  * this leading crap?
  */

/*
     This is so much better
*/


Edit those without using editor macros. Barf. And if you are 
willing to use editor macros, the other justification for it - 
making the comment look different than code - disappears since if 
your editor is fancy enough to understand that leading * crap and 
automatically reformat it, it could just as well syntax highlight 
it in some way (including displaying leading stars without saving 
them to the file!)

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

yeah me too. Though ddox for a while syntax highlighted them too. 
And adrdox did too for a while, with $(D) though not `` since D 
is explicitly D language (though phobos authors frequently used 
it for non-D...) though I changed my mind on it after using it - 
it just distracted from the text instead of adding to it.

> 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

adrdox recognizes urls and I like writing them like that when I 
actually write a url.... but the benefit of [reference] is that 
it doesn't require an actual url. It is just a symbol, in scope 
even.

/**
    See also: [otherFunction]
*/
void foo() {}

/**
    See also: [foo]
*/
void otherFunction() {}


It knows those are local symbols so it looks them up in scope. 
adrdox understands D's import rules and even handles nested 
names. Having to get a URL there is a big hassle... what if a 
library gets a new fork/maintainer and the doc url changes? What 
if you want to render it offline? What a pain!