new documentation format for std.algorithm

[Andrei Alexandrescu]

On 2/2/11 7:24 PM, Jonathan M Davis wrote:
> 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

Wow, Konqueror has a pretty bad layout engine wrt soft hyphenation. 
Hyphenating has a high penalty and should only occur when otherwise 
things would be really ugly.

I'll setup the table such that the first column is not hyphenated.

Andrei