On 1/1/14 4:56 AM, Jacob Carlborg wrote:
On 2013-12-31 18:08, Andrei Alexandrescu wrote:
That's an exaggeration. The top of std.algorithm produces complex output
(two tables). The rest of the documentation is nice and legible.
std.algorithm contains 335 lines of ddoc comments. I would consider that
"hundreds", or does "hundreds" mean something else.
I replied to "Hundreds of lines of Ddoc madness" with "that's an
exaggeration". Do you really think I was refuting the factual 335 lines?
What I'm saying is
that those two tables should be automatically generated, at least the
first one.
Yah, that would be nice.
As one who's written both, I can testify this isn't true. Ddoc macros
need to be mentioned once and then the closing paren completes them.
Additionally, they can expand to arbitrarily complex output. In
contrast, tags need to be mentioned twice (an often-mentioned issue with
writing HTML by hand), are syntactically heavier, and therefore litter
the text a lot more.
I'm considering it to be a sort of tag, just with a different syntax.
Who said tags need to have an end tag. A less verbose a minimal reliance
on tags would be Markdown or similar. Creating a list in Markdown is
simple as:
* this
* is
* a
* list
* in Markdown
I prefer ddoc to markdown for its flexibility. Ddoc is an almost pure
macro expansion system with minimal syntax. Markdown defines a bunch of
syntax but has (last time I looked) is weak on macro capability.
Case in point: markdown lists will be styled one way. With DDoc macros
one can define any style of lists needed. (We've defined BOOKTABLE in
addition to a couple of other TABLEs, which works beautifully in HTML
and LaTeX; not sure how can be done in Markdown.
If there's a specific macro that would indicate a category then it would
be easy to generate a table like that.
/// $(CATEGORY searching)
void foo ()
The issue is with writing text out of order, something DDoc is not very
apt at. Would be nice to improve on that (we do some of it with javascript).
Andrei
