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. What I'm saying is
that those two tables should be automatically generated, at least the
first one.
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
No. There are two tables there. One is a categorization of algorithms,
which is human-made. There are several solutions to materializing that
table but they all would require the intervention of a human being. I
figured std.algorithm adds new algorithms rarely enough to allow myself
a solution that requires manual intervention.
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 second table is a "cheat sheet" with human-produced short
descriptions for each function. Those short descriptions wouldn't fit
well with the longer descriptions.
That can also be generated automatically. Ddoc can just insert the
summary [1] for each symbol.
[1] The Ddoc documentation says:
"The first section is the Summary, and does not have a section name. It
is first paragraph, up to a blank line or a section name. While the
summary can be any length, try to keep it to one line."
http://dlang.org/ddoc.html
Again no. You are misinformed. The PDF manual is generated via LaTeX
from the same ddoc sources as the HTML pages.
Ok, fair enough.
--
/Jacob Carlborg
