On Monday, 29 December 2014 at 19:47:50 UTC, Walter Bright wrote:
On 12/29/2014 3:19 AM, Jacob Carlborg wrote:
On 2014-12-29 06:39, Walter Bright wrote:
Having used both Ddoc and Markdown, I seriously disagree with
this. Take
a look at the markdown source for DIP69. It's horrific.
Do you mean on the wiki? The wiki doesn't use Markdown. At
least not anyone I've
seen.
It uses something pretty similar. They all kinda mush together
in my mind :-(
It's NOT SIMILAR at all. It's a completely different language.
Also as mentioned above, DDoc macros are extremely ugly and hard
to read (and to make sense of, with their lisp-ness).
Not to mention, *almost everyone* coding today knows Markdown and
can immediately begin contributing to the docs, without looking
up DDoc documentation or a *freaking macro file in one of D's
repositories*. Only a subset of D devs know DDoc macros, and a
very small minority of those know DDoc macros used by Phobos.
This is ugly, it is the *very definition* of ugly. (how the heck
am I even supposed to read that?):
DDoc:
$(OL $(LI If $(D line) has type $(D string), $(D
wstring), or $(D dstring), a new string of the respective type
is allocated every read.) $(LI If $(D line) has type $(D
char[]), $(D wchar[]), $(D dchar[]), the line's content
will be reused (overwritten) across reads.) $(LI If $(D line)
has type $(D immutable(ubyte)[]), the behavior is similar to
case (1), except that no UTF checking is attempted upon input.)
$(LI
If $(D line) has type $(D ubyte[]), the behavior is
similar to case (2), except that no UTF checking is attempted upon
input.))
This is *much less ugly*:
Markdown:
1. If `line` has type `string`, `wstring`, or `dstring`, a new
string of the respective type is allocated every read.
2. If `line` has type `char[]`, `wchar[]`, `dchar[]`, the line's
content will be reused (overwritten) across reads.
3. If `line` has type `immutable(ubyte)[]`, the behavior is
similar to case (1), except that no UTF checking is attempted
upon input.
4. If `line` has type `ubyte[]`, the behavior is similar to
case (2), except that no UTF checking is attempted upon input.
And my favorite, tables in DDoc. First 3 lines for brevity:
DDoc:
$(BOOKTABLE Cheat Sheet,
$(TR $(TH Function Name) $(TH Description)
)
$(LEADINGROW Searching
)
$(TR $(TDNW $(LREF all)) $(TD $(D all!"a > 0"([1, 2, 3, 4]))
returns $(D true) because all elements are positive)
)
$(TR $(TDNW $(LREF any)) $(TD $(D any!"a > 0"([1, 2, -3, -4]))
returns $(D true) because at least one element is positive)
)
...
Markdown (assuming some kind of automatic crossreferencing, which
*needs* to
be in any decent documentation generator, and DDox, which renders
your
"preview new" documentation, already does it)
| Function Name | Description
|
| -------------
|------------------------------------------------- |
| #all | `all!"a > 0"([1, 2, 3, 4])` returns `true` ...
|
| #any | `any!"a > 0"([1, 2, -3, -4])` returns `true`
... |
(shortened to fit mail, but you should be able to get the point)
If you don't want so many pipes / aligning work, this works too:
Function Name | Description
- | -
#all | `all!"a > 0"([1, 2, 3, 4])` returns `true` ...
#any | `any!"a > 0"([1, 2, -3, -4])` returns `true` ...
And yes, the above is limited, it can't do everything DDoc can
do. Macros are
useful when you need something way out of the ordinary. But using
them for
things like tables or lists or 5 different macros for links
because you don't
think cross-referencing is important is insane.
I'd be happy if I could use *something that's not DDoc macros*
99% of the time.
But if I want my docs to be anything better than bare text with
Params:,
Returns: and Examples:, I have to write that kind of gibberish
(actually, not
anymore, as I said I'm working on DDoc + markdown).
