new documentation format for std.algorithm

[Nick Sabalausky]

"Andrei Alexandrescu" <SeeWebsiteForEmail at erdani.org> wrote in message 
news:iibuu1$123i$1 at digitalmars.com...
> On 2/2/11 6:06 AM, Nick Sabalausky wrote:
>> "Denis Koroskin"<2korden at gmail.com>  wrote in message
>> news:op.vp9wmrreo7cclz at korden-pc...
>>> On Wed, 02 Feb 2011 14:06:11 +0300, Magnus Lie Hetland
>>> <magnus at hetland.org>  wrote:
>>>
>>>> I think perhaps some adjustments could be made to the layout, to make 
>>>> it
>>>> more suitable to narrow(ish) browser windows (c.f., the discussio about
>>>> 80 columns -- without starting a huge thread like that again ;)
>>>>
>>>> For one thing, in narrow(ish) columns, ragged-right might be 
>>>> preferable.
>>>> Then again, it may be that the way it looks on my end isn't what's
>>>> intended:
>>>>
>>>>    http://www.idi.ntnu.no/~mlh/images/std-alg-docs.png
>>>>
>>>
>>> Left menu, Category and Function Name tables do take up about 800 pixels
>>> in width, leaving very little space for Description on small resolution
>>> displays, mostly because of the large font size used and identifiers as
>>> long as "largestPartialIntersectionWeighted".
>>>
>>> While there is little we can do with identifier names, I believe font 
>>> size
>>> could be reduced by about 30% without sacrificing readability. At least 
>>> in
>>> Opera the page looks well even at 70% scale.
>>
>> Actually, I think a smaller font improves the readability on that page. 
>> Left
>> as it is, I would always hit "decrease font" two or three times in my
>> browser before reading. (And that's even not counting the layout problems
>> the current font size causes.)
>
> OK, for now I removed everything fixing the font size from the css. Take a 
> look.
>

Not quite ideal IMHO, but definitely a *lot* better. I'd be happy with it.


>> I also agree with what others said about needing a better visual boundary
>> between the different descriptions.
>
> I'll look into this. I saw arguments against alternating colors. Also, 
> horizontal lines throughout would be ugly. More ideas would be welcome.
>

I think it would work ok if each description were at least 3 lines on 
average, but yea, with them mostly being one or two lines (esp. one line) it 
does get noisy.

I'd try adding extra spacing before and after the line, and *if* the line 
still looks noisy I'd try ripping out the line and just go with the extra 
spacing.

It's not actually all that bad as it is, though. I could certainly live with 
it and get used to it. Big improvement over just not having the line like 
before.


>> Only other thing I could bring up is that I'm really not as much a fan of
>> justified text as Andrei. But I can live with it fine, of course, just as
>> I've been doing (and I don't want to start a "left-aligned" vs 
>> "justified"
>> bikeshed war).
>
> Yah, it sometimes does look a bit forced. I'd need to add hyphenation to 
> make justified text look good.
>

I'm not sure how much that would work in this case, since each "paragraph" 
is fairly short and there doesn't seem to be much that would be 
hyphenatable.

As it is, I'm getting a lot of rather huge space characters:
http://www.semitwist.com/download/phobosAlgoScreenshot.png

FWIW, doing one "decrease font" click in FF2 (I have no idea how much that 
decreases it by) fixes the ultra-large spaces, and puts the font size at 
what I would consider ideal (although there's probably a number of people 
who would find that too small.)