new documentation format for std.algorithm

[Jonathan M Davis]

On Wednesday, February 02, 2011 11:12:07 Andrei Alexandrescu wrote:
> On 2/2/11 2:45 AM, Andrei Alexandrescu wrote:
> > Following ideas and advice from this newsgroup, I have a draft at
> > 
> > http://d-programming-language.org/cutting-edge/phobos/std_algorithm.html
> > 
> > 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!
> > 
> > 
> > Andrei
> 
> I made one more pass and made the following changes:
> 
> * Added thin horizontal rules (you might have seen this already)
> 
> * Added "Comparison" category
> 
> * Reduced columns to two in the cheat sheet table and used leading rows
> for distinguishing categories
> 
> * Added hyphenation, which should make justice to the justified style
> (watch it at work in a narrow window!)
> 
> Let me know how it looks!

Aside from the category column, it looks great. However, the hyphenated category 
column looks horrible. The only one that manages to put its whole name on one 
line is Sorting. All of the others get split up onto 2 or 3 lines and become 
almost illegible. There's _tons_ of room for the Functions column in comparison. 
Unless you really think that there are going to be screens that are so small 
that they can't even fit all of the function names in there by listing them in a 
single line vertically (i.e. so small that there isn't enough space to 
horizontally place the longest function name), I would strongly suggest having 
the category column take up one line for each name rather than trying to 
hyphenate it. At most, split up Set Operations onto two lines, with Set on one 
line and Operations on the second. The hyphenating looks horrible and is hard to 
read. I see no reason to make the category column worry about space so much. I 
would expect the functions column to be able to handle the width adjustment for 
various screen sizes.

Screenshot: http://is.gd/J51l9r

- Jonathan M Davis