new documentation format for std.algorithm

[Andrei Alexandrescu]

On 2/2/11 9:08 AM, Adam Ruppe wrote:
> Andrei Alexandrescu Wrote:
>> There are two tables, one with just the names and the other with
>> names and a brief description. Let me know of any feedback.
>> Thanks!
>
> Did you decide on a manually maintained table or is it auto
> generated?  I do really think adding a Tags: section, or perhaps just
> putting groups under the See_Also: section is a good way to do the
> grouping.

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.

> The mini examples might be good as a new section too, one that can be
> hidden in the big docs, but available to the jump table.

Not getting this.

> Also a few notes:
>
> a) I really like a fixed width for the links, so it forms a neat
> grid. My eyes just see a blob of links when it's a list...

That would really hurt e.g. set operations.

> b) The<a name="">  anchors in the page are repeated in a lot of
> cases, meaning the links may go to the wrong place. I suggest
> tweaking ddoc to make them fully qualified (at least inside the
> module, for example, "#OpenRight.yes" instead of "#yes").

Yah, how did you pull that trick in your generated jump table?

> c) I think I agree with the others that the Category header eats a
> bit too much horizontal space, but it isn't a big deal to me.

I'll probably change that.

> I'm working on my own little tweaks to the system concurrently. I
> like your version a lot more than mine right now, but still think we
> can do a little better... if I have time today in between my other
> work, I'll see about adding my ideas here to my version so you can
> see them in practice.

Awesome!


Andrei