new documentation format for std.algorithm

[Adam Ruppe]

Andrei Alexandrescu wrote:
> For now it's manual; I had to write the actual text which was the bulk
> anyway. Long term we'll need to look at generating the table by adding
> category tags to each function/class etc.

Right. I now think the best way to do it is something like this:


Macros:
WIKI = Phobos/StdAlgorithm
TAG = <a href="#$1" class="tag">$1</a>


/**
map!"2 * a"([1, 2, 3]) lazily returns a range with the numbers 2, 4, 6.

Implements the homonym function (also known as $(D transform)) present

[... snip all unmodified existing content ...]
See_also:
        $(TAG Iteration)

 */


Then, the function tags are grouped in a pretty logical place,
and have enough decoration in the HTML that we can easily parse
them out before or after.

The helper program would search all links with the tag class and
figure out what function they belong to. With that, it generates
the categorization tables.

Alternatively, it could use a "Tags:" instead of "See_also:".


I also moved the brief description from the table to the first
line of the ddoc. The ddoc spec already describes the first paragraph
as being a summary, with the following paragraphs as a separate
description <http://digitalmars.com/d/2.0/ddoc.html>, so we're
just leveraging that existing definition.

Now, when the table is generated, it can go through and pull
the first paragraph out of each ddoc section and put it in the
summary table.

Alternatively, we add a new section, say, "Briefly":


/**
Implements the homonym function (also known as $(D transform)) present
[... snip all unmodified existing content ...]

Briefly:
map!"2 * a"([1, 2, 3]) lazily returns a range with the numbers 2, 4, 6.

See_also:
        $(TAG Iteration)

 */


And the helper program pulls that out for the table. The
result might look something like this:

http://arsdnet.net/d-web-site/algorithm.html

(I only played with map() there and dmd -D'd it, so nothing fancy).


> Not getting this.

What I mean there is the above "Briefly:" section.


> That would really hurt e.g. set operations.

Yeah. Oh well.