new documentation format for std.algorithm

[Jonathan M Davis]

On Wednesday, February 02, 2011 17:37:27 Andrei Alexandrescu wrote:
> 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.htm
> >>> l
> >>> 
> >>> 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.

Chrome looks pretty much the same (though for some reason it shows almost none 
of the hyphens). Of course, they are cousins, since Konqueror uses KHTML and 
Chrome uses Webkit, which was forked from KHTML. Regardless, even if Konqueror 
were considered unimportant (which, fortunately, was not your reaction), the 
fact that Chrome has the problem would make it so that it was still something 
that needed to be addressed (since Chrome certainly doesn't have a small user 
base).

- Jonathan M Davis