Re: Re: Scaladoc layout (was: Upcoming 2.9.0.RC1 (take 2))

Perhaps I should say something about *what* I changed. :-)

First, I used the Scaladoc files from the latest 2.10 nightly build as
the basis for my changes, with Bill's changes on top. Although I must
admit that I reverted some of his changes.

The biggest change is the layout of the member lists. No more gray
headers, everything is white now, with light gray separators in
between. Light gray is a much better choice than my previous black, I
think.

Then I changed the spacing in many places to be more even / regular
and to ensure that things line up properly. Also I added some spacing
to emphasize the separation of separate things. Does that sentence
make sense? :-)

Also, I changed the line height to the default which is something like
1.2. This makes everything much easier to read.

I changed the separators at the bottom of the expanded method / type
descriptions to be somewhat lighter and I also removed the separating
lines in between the parameter descriptions.

Last but not least, I changed the line breaking behavior when the
window is not wide enough to display a signature in a single line.
Just compare it with the original version, you will notice the
improvement.

There might be some other minor things, I forgot.

I wanted to add that I would like the colons for defining the types
not to have leading white space, just as Randall noted before. But I
cannot change that with the CSS, because the HTML files generated
contain white space (and even line breaks) before the colons.

Another thing I thought had been fixed already, but is not: if I click
"display packages only" in the left panel, the packages collapse as
expected, but the "hide" links next to the package names do not change
into "show" links. IMHO this is clearly a bug and should be fixed.

Should I create tickets for this? Although I think there already
exists one for the latter.

Regards,
Rüdiger

2011/3/20 Rüdiger Keller :
> Ok, I'm done with the first iteration. I just attached the new
> template.css and index.css. I hope that is not too inconvenient.
>
> If there is demand for it, I can put my modified version of the
> Scaladocs on my own web space, but I would prefer not to. I only have
> 20MB and the Scaladocs are 200MB in size. I hope Donna or Bill can set
> up comparison sites again.
>
> Also, I used Firefox and Firebug to create my changes, but a (very)
> quick check with IE8 and Chrome showed no problems.
>
> Ok, I'm waiting for feedback then.
>
> Regards,
> Rüdiger
>
>
> 2011/3/20 Ruediger Keller :
>> Ok. I'm working on it right now and it's coming along nicely, I think.
>>
>>
>> 2011/3/20 Donna Malayeri :
>>>> I think my suggestion can be improved further, but first I want to
>>>> know it it's worth the time. If everyone is in favor of the old style
>>>> with alternating grey and white, I will not pursue this approach.
>>>
>>> Personally, I like the new style (no alternating black and grey), but I might be in a minority here. If we come up with some concrete re-designs, I can make a poll so people can vote on their preferred design.
>>>
>>> Donna
>>
>

Ok, I did some additional changes, now also including the index.

Files are attached.

2011/3/20 Rüdiger Keller :
> Perhaps I should say something about *what* I changed. :-)
>
> First, I used the Scaladoc files from the latest 2.10 nightly build as
> the basis for my changes, with Bill's changes on top. Although I must
> admit that I reverted some of his changes.
>
> The biggest change is the layout of the member lists. No more gray
> headers, everything is white now, with light gray separators in
> between. Light gray is a much better choice than my previous black, I
> think.
>
> Then I changed the spacing in many places to be more even / regular
> and to ensure that things line up properly. Also I added some spacing
> to emphasize the separation of separate things. Does that sentence
> make sense? :-)
>
> Also, I changed the line height to the default which is something like
> 1.2. This makes everything much easier to read.
>
> I changed the separators at the bottom of the expanded method / type
> descriptions to be somewhat lighter and I also removed the separating
> lines in between the parameter descriptions.
>
> Last but not least, I changed the line breaking behavior when the
> window is not wide enough to display a signature in a single line.
> Just compare it with the original version, you will notice the
> improvement.
>
> There might be some other minor things, I forgot.
>
>
> I wanted to add that I would like the colons for defining the types
> not to have leading white space, just as Randall noted before. But I
> cannot change that with the CSS, because the HTML files generated
> contain white space (and even line breaks) before the colons.
>
> Another thing I thought had been fixed already, but is not: if I click
> "display packages only" in the left panel, the packages collapse as
> expected, but the "hide" links next to the package names do not change
> into "show" links. IMHO this is clearly a bug and should be fixed.
>
> Should I create tickets for this? Although I think there already
> exists one for the latter.
>
> Regards,
> Rüdiger
>
>
>
> 2011/3/20 Rüdiger Keller :
>> Ok, I'm done with the first iteration. I just attached the new
>> template.css and index.css. I hope that is not too inconvenient.
>>
>> If there is demand for it, I can put my modified version of the
>> Scaladocs on my own web space, but I would prefer not to. I only have
>> 20MB and the Scaladocs are 200MB in size. I hope Donna or Bill can set
>> up comparison sites again.
>>
>> Also, I used Firefox and Firebug to create my changes, but a (very)
>> quick check with IE8 and Chrome showed no problems.
>>
>> Ok, I'm waiting for feedback then.
>>
>> Regards,
>> Rüdiger
>>
>>
>> 2011/3/20 Ruediger Keller :
>>> Ok. I'm working on it right now and it's coming along nicely, I think.
>>>
>>>
>>> 2011/3/20 Donna Malayeri :
>>>>> I think my suggestion can be improved further, but first I want to
>>>>> know it it's worth the time. If everyone is in favor of the old style
>>>>> with alternating grey and white, I will not pursue this approach.
>>>>
>>>> Personally, I like the new style (no alternating black and grey), but I might be in a minority here. If we come up with some concrete re-designs, I can make a poll so people can vote on their preferred design.
>>>>
>>>> Donna
>>>
>>
>

Yes, please do create tickets (assuming non-duplicates). Thanks for your work and the explanations! I will set up a site with both versions for comparison, probably on Monday or Tuesday.

thanks,
Donna

On Mar 20, 2011, at 2:33 PM, Rüdiger Keller wrote:

> Perhaps I should say something about *what* I changed. :-)
>
> First, I used the Scaladoc files from the latest 2.10 nightly build as
> the basis for my changes, with Bill's changes on top. Although I must
> admit that I reverted some of his changes.
>
> The biggest change is the layout of the member lists. No more gray
> headers, everything is white now, with light gray separators in
> between. Light gray is a much better choice than my previous black, I
> think.
>
> Then I changed the spacing in many places to be more even / regular
> and to ensure that things line up properly. Also I added some spacing
> to emphasize the separation of separate things. Does that sentence
> make sense? :-)
>
> Also, I changed the line height to the default which is something like
> 1.2. This makes everything much easier to read.
>
> I changed the separators at the bottom of the expanded method / type
> descriptions to be somewhat lighter and I also removed the separating
> lines in between the parameter descriptions.
>
> Last but not least, I changed the line breaking behavior when the
> window is not wide enough to display a signature in a single line.
> Just compare it with the original version, you will notice the
> improvement.
>
> There might be some other minor things, I forgot.
>
>
> I wanted to add that I would like the colons for defining the types
> not to have leading white space, just as Randall noted before. But I
> cannot change that with the CSS, because the HTML files generated
> contain white space (and even line breaks) before the colons.
>
> Another thing I thought had been fixed already, but is not: if I click
> "display packages only" in the left panel, the packages collapse as
> expected, but the "hide" links next to the package names do not change
> into "show" links. IMHO this is clearly a bug and should be fixed.
>
> Should I create tickets for this? Although I think there already
> exists one for the latter.
>
> Regards,
> Rüdiger
>
>
>
> 2011/3/20 Rüdiger Keller :
>> Ok, I'm done with the first iteration. I just attached the new
>> template.css and index.css. I hope that is not too inconvenient.
>>
>> If there is demand for it, I can put my modified version of the
>> Scaladocs on my own web space, but I would prefer not to. I only have
>> 20MB and the Scaladocs are 200MB in size. I hope Donna or Bill can set
>> up comparison sites again.
>>
>> Also, I used Firefox and Firebug to create my changes, but a (very)
>> quick check with IE8 and Chrome showed no problems.
>>
>> Ok, I'm waiting for feedback then.
>>
>> Regards,
>> Rüdiger
>>
>>
>> 2011/3/20 Ruediger Keller :
>>> Ok. I'm working on it right now and it's coming along nicely, I think.
>>>
>>>
>>> 2011/3/20 Donna Malayeri :
>>>>> I think my suggestion can be improved further, but first I want to
>>>>> know it it's worth the time. If everyone is in favor of the old style
>>>>> with alternating grey and white, I will not pursue this approach.
>>>>
>>>> Personally, I like the new style (no alternating black and grey), but I might be in a minority here. If we come up with some concrete re-designs, I can make a poll so people can vote on their preferred design.
>>>>
>>>> Donna
>>>
>>

Ok, I will do so.

I have again made some changes. I think I'm quite happy with the
results now. Again, the files are attached.

Regards,
Rüdiger

2011/3/20 Donna Malayeri :
> Yes, please do create tickets (assuming non-duplicates). Thanks for your work and the explanations!  I will set up a site with both versions for comparison, probably on Monday or Tuesday.
>
> thanks,
> Donna
>
> On Mar 20, 2011, at 2:33 PM, Rüdiger Keller wrote:
>
>> Perhaps I should say something about *what* I changed. :-)
>>
>> First, I used the Scaladoc files from the latest 2.10 nightly build as
>> the basis for my changes, with Bill's changes on top. Although I must
>> admit that I reverted some of his changes.
>>
>> The biggest change is the layout of the member lists. No more gray
>> headers, everything is white now, with light gray separators in
>> between. Light gray is a much better choice than my previous black, I
>> think.
>>
>> Then I changed the spacing in many places to be more even / regular
>> and to ensure that things line up properly. Also I added some spacing
>> to emphasize the separation of separate things. Does that sentence
>> make sense? :-)
>>
>> Also, I changed the line height to the default which is something like
>> 1.2. This makes everything much easier to read.
>>
>> I changed the separators at the bottom of the expanded method / type
>> descriptions to be somewhat lighter and I also removed the separating
>> lines in between the parameter descriptions.
>>
>> Last but not least, I changed the line breaking behavior when the
>> window is not wide enough to display a signature in a single line.
>> Just compare it with the original version, you will notice the
>> improvement.
>>
>> There might be some other minor things, I forgot.
>>
>>
>> I wanted to add that I would like the colons for defining the types
>> not to have leading white space, just as Randall noted before. But I
>> cannot change that with the CSS, because the HTML files generated
>> contain white space (and even line breaks) before the colons.
>>
>> Another thing I thought had been fixed already, but is not: if I click
>> "display packages only" in the left panel, the packages collapse as
>> expected, but the "hide" links next to the package names do not change
>> into "show" links. IMHO this is clearly a bug and should be fixed.
>>
>> Should I create tickets for this? Although I think there already
>> exists one for the latter.
>>
>> Regards,
>> Rüdiger
>>
>>
>>
>> 2011/3/20 Rüdiger Keller :
>>> Ok, I'm done with the first iteration. I just attached the new
>>> template.css and index.css. I hope that is not too inconvenient.
>>>
>>> If there is demand for it, I can put my modified version of the
>>> Scaladocs on my own web space, but I would prefer not to. I only have
>>> 20MB and the Scaladocs are 200MB in size. I hope Donna or Bill can set
>>> up comparison sites again.
>>>
>>> Also, I used Firefox and Firebug to create my changes, but a (very)
>>> quick check with IE8 and Chrome showed no problems.
>>>
>>> Ok, I'm waiting for feedback then.
>>>
>>> Regards,
>>> Rüdiger
>>>
>>>
>>> 2011/3/20 Ruediger Keller :
>>>> Ok. I'm working on it right now and it's coming along nicely, I think.
>>>>
>>>>
>>>> 2011/3/20 Donna Malayeri :
>>>>>> I think my suggestion can be improved further, but first I want to
>>>>>> know it it's worth the time. If everyone is in favor of the old style
>>>>>> with alternating grey and white, I will not pursue this approach.
>>>>>
>>>>> Personally, I like the new style (no alternating black and grey), but I might be in a minority here. If we come up with some concrete re-designs, I can make a poll so people can vote on their preferred design.
>>>>>
>>>>> Donna
>>>>
>>>
>
>

Hi Ruediger,

I generated Scaladoc for the ScalaTest trunk with the latest
2.9.0-SNAPSHOT, then put your three .css files in there. I then
deployed it here:

http://www.artima.com/sdp/ruediger2/

Comparing this to my suggestion:

http://www.artima.com/sdp/suggestion/

I think your line height of 1.2 might be an improvement, but I could
live with either for 2.9.0. I think I actually prefer the alternating
gray/white background of current Scaladoc to the all-white with
separator lines you're suggesting.

There are some other issues I'm seeing in ruediger2. For example, on
trait Suite:

http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html

There's extra white space at the top before the first comment line
that begins, "A suite of tests. A Suite instance encapsulates..."

There's missing white space after lists. Look at the list in the
Extensability section down at the bottom for an example. After
"expectedTestCount - override this method to count this Suite's...",
there's no white space before the start of the next paragraph.

I think also the paragraphs are not quite far enough apart to visually
separate them.

One thing I think we should separate is what would go into 2.9.0 and
what would go later. This is very last minute for 2.9.0. I should have
gone through and done my second pass looking for remaining issues
earlier, but I was very busy. So at this point I think only critical
problems should be addressed, and for layout I think just adding a bit
of white space here and there is probably all we should try to do for
2.9.0. After that Donna can lead a more careful and thorough redesign
of the layout, if need be.

In my suggestion I was trying to be minimal so that the change would
be low risk and easy enough to go into 2.9.0. I'll make one more pass
today using your suggestions (line height of 1.2, and evening out
those descriptions, which you pointed out yesterday.) After that I'll
stop and I think that will be good enough for 2.9.0 as far as layout
goes. The kind of changes your suggesting are more appropriate to
consider for post-2.9.0 in my opinion.

I will follow up with another email clarifying what Scaladoc bugs I am
hoping to see closed for 2.9.0. Several we submitted yesterday are
minutia that could wait until later, but there are still a few that
result in documentation being dropped and inaccessible to the user,
which I think we should try and fix for 2.9.0.

Thanks.

Bill

On Sun, Mar 20, 2011 at 11:14 AM, Rüdiger Keller
wrote:
> Ok, I will do so.
>
> I have again made some changes. I think I'm quite happy with the
> results now. Again, the files are attached.
>
> Regards,
> Rüdiger
>
>
> 2011/3/20 Donna Malayeri :
>> Yes, please do create tickets (assuming non-duplicates). Thanks for your work and the explanations!  I will set up a site with both versions for comparison, probably on Monday or Tuesday.
>>
>> thanks,
>> Donna
>>
>> On Mar 20, 2011, at 2:33 PM, Rüdiger Keller wrote:
>>
>>> Perhaps I should say something about *what* I changed. :-)
>>>
>>> First, I used the Scaladoc files from the latest 2.10 nightly build as
>>> the basis for my changes, with Bill's changes on top. Although I must
>>> admit that I reverted some of his changes.
>>>
>>> The biggest change is the layout of the member lists. No more gray
>>> headers, everything is white now, with light gray separators in
>>> between. Light gray is a much better choice than my previous black, I
>>> think.
>>>
>>> Then I changed the spacing in many places to be more even / regular
>>> and to ensure that things line up properly. Also I added some spacing
>>> to emphasize the separation of separate things. Does that sentence
>>> make sense? :-)
>>>
>>> Also, I changed the line height to the default which is something like
>>> 1.2. This makes everything much easier to read.
>>>
>>> I changed the separators at the bottom of the expanded method / type
>>> descriptions to be somewhat lighter and I also removed the separating
>>> lines in between the parameter descriptions.
>>>
>>> Last but not least, I changed the line breaking behavior when the
>>> window is not wide enough to display a signature in a single line.
>>> Just compare it with the original version, you will notice the
>>> improvement.
>>>
>>> There might be some other minor things, I forgot.
>>>
>>>
>>> I wanted to add that I would like the colons for defining the types
>>> not to have leading white space, just as Randall noted before. But I
>>> cannot change that with the CSS, because the HTML files generated
>>> contain white space (and even line breaks) before the colons.
>>>
>>> Another thing I thought had been fixed already, but is not: if I click
>>> "display packages only" in the left panel, the packages collapse as
>>> expected, but the "hide" links next to the package names do not change
>>> into "show" links. IMHO this is clearly a bug and should be fixed.
>>>
>>> Should I create tickets for this? Although I think there already
>>> exists one for the latter.
>>>
>>> Regards,
>>> Rüdiger
>>>
>>>
>>>
>>> 2011/3/20 Rüdiger Keller :
>>>> Ok, I'm done with the first iteration. I just attached the new
>>>> template.css and index.css. I hope that is not too inconvenient.
>>>>
>>>> If there is demand for it, I can put my modified version of the
>>>> Scaladocs on my own web space, but I would prefer not to. I only have
>>>> 20MB and the Scaladocs are 200MB in size. I hope Donna or Bill can set
>>>> up comparison sites again.
>>>>
>>>> Also, I used Firefox and Firebug to create my changes, but a (very)
>>>> quick check with IE8 and Chrome showed no problems.
>>>>
>>>> Ok, I'm waiting for feedback then.
>>>>
>>>> Regards,
>>>> Rüdiger
>>>>
>>>>
>>>> 2011/3/20 Ruediger Keller :
>>>>> Ok. I'm working on it right now and it's coming along nicely, I think.
>>>>>
>>>>>
>>>>> 2011/3/20 Donna Malayeri :
>>>>>>> I think my suggestion can be improved further, but first I want to
>>>>>>> know it it's worth the time. If everyone is in favor of the old style
>>>>>>> with alternating grey and white, I will not pursue this approach.
>>>>>>
>>>>>> Personally, I like the new style (no alternating black and grey), but I might be in a minority here. If we come up with some concrete re-designs, I can make a poll so people can vote on their preferred design.
>>>>>>
>>>>>> Donna
>>>>>
>>>>
>>
>>
>

Looking at that example, my main concern is the behaviour of expanded/collapsed elements.
Expand a few methods, and it quickly becomes difficult to discern much structure...

On 20 March 2011 23:05, Bill Venners <bill@artima.com> wrote:

Hi Ruediger,

I generated Scaladoc for the ScalaTest trunk with the latest
2.9.0-SNAPSHOT, then put your three .css files in there. I then
deployed it here:

http://www.artima.com/sdp/ruediger2/

Comparing this to my suggestion:

http://www.artima.com/sdp/suggestion/

I think your line height of 1.2 might be an improvement, but I could
live with either for 2.9.0. I think I actually prefer the alternating
gray/white background of current Scaladoc to the all-white with
separator lines you're suggesting.

There are some other issues I'm seeing in ruediger2. For example, on
trait Suite:

http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html

There's extra white space at the top before the first comment line
that begins, "A suite of tests. A Suite instance encapsulates..."

There's missing white space after lists. Look at the list in the
Extensability section down at the bottom for an example. After
"expectedTestCount - override this method to count this Suite's...",
there's no white space before the start of the next paragraph.

I think also the paragraphs are not quite far enough apart to visually
separate them.

One thing I think we should separate is what would go into 2.9.0 and
what would go later. This is very last minute for 2.9.0. I should have
gone through and done my second pass looking for remaining issues
earlier, but I was very busy. So at this point I think only critical
problems should be addressed, and for layout I think just adding a bit
of white space here and there is probably all we should try to do for
2.9.0. After that Donna can lead a more careful and thorough redesign
of the layout, if need be.

In my suggestion I was trying to be minimal so that the change would
be low risk and easy enough to go into 2.9.0. I'll make one more pass
today using your suggestions (line height of 1.2, and evening out
those descriptions, which you pointed out yesterday.) After that I'll
stop and I think that will be good enough for 2.9.0 as far as layout
goes. The kind of changes your suggesting are more appropriate to
consider for post-2.9.0 in my opinion.

I will follow up with another email clarifying what Scaladoc bugs I am
hoping to see closed for 2.9.0. Several we submitted yesterday are
minutia that could wait until later, but there are still a few that
result in documentation being dropped and inaccessible to the user,
which I think we should try and fix for 2.9.0.

Thanks.

Bill


On Sun, Mar 20, 2011 at 11:14 AM, Rüdiger Keller
<ruediger.keller@googlemail.com> wrote:
> Ok, I will do so.
>
> I have again made some changes. I think I'm quite happy with the
> results now. Again, the files are attached.
>
> Regards,
> Rüdiger
>
>
> 2011/3/20 Donna Malayeri <lindydonna@gmail.com>:
>> Yes, please do create tickets (assuming non-duplicates). Thanks for your work and the explanations!  I will set up a site with both versions for comparison, probably on Monday or Tuesday.
>>
>> thanks,
>> Donna
>>
>> On Mar 20, 2011, at 2:33 PM, Rüdiger Keller wrote:
>>
>>> Perhaps I should say something about *what* I changed. :-)
>>>
>>> First, I used the Scaladoc files from the latest 2.10 nightly build as
>>> the basis for my changes, with Bill's changes on top. Although I must
>>> admit that I reverted some of his changes.
>>>
>>> The biggest change is the layout of the member lists. No more gray
>>> headers, everything is white now, with light gray separators in
>>> between. Light gray is a much better choice than my previous black, I
>>> think.
>>>
>>> Then I changed the spacing in many places to be more even / regular
>>> and to ensure that things line up properly. Also I added some spacing
>>> to emphasize the separation of separate things. Does that sentence
>>> make sense? :-)
>>>
>>> Also, I changed the line height to the default which is something like
>>> 1.2. This makes everything much easier to read.
>>>
>>> I changed the separators at the bottom of the expanded method / type
>>> descriptions to be somewhat lighter and I also removed the separating
>>> lines in between the parameter descriptions.
>>>
>>> Last but not least, I changed the line breaking behavior when the
>>> window is not wide enough to display a signature in a single line.
>>> Just compare it with the original version, you will notice the
>>> improvement.
>>>
>>> There might be some other minor things, I forgot.
>>>
>>>
>>> I wanted to add that I would like the colons for defining the types
>>> not to have leading white space, just as Randall noted before. But I
>>> cannot change that with the CSS, because the HTML files generated
>>> contain white space (and even line breaks) before the colons.
>>>
>>> Another thing I thought had been fixed already, but is not: if I click
>>> "display packages only" in the left panel, the packages collapse as
>>> expected, but the "hide" links next to the package names do not change
>>> into "show" links. IMHO this is clearly a bug and should be fixed.
>>>
>>> Should I create tickets for this? Although I think there already
>>> exists one for the latter.
>>>
>>> Regards,
>>> Rüdiger
>>>
>>>
>>>
>>> 2011/3/20 Rüdiger Keller <ruediger.keller@googlemail.com>:
>>>> Ok, I'm done with the first iteration. I just attached the new
>>>> template.css and index.css. I hope that is not too inconvenient.
>>>>
>>>> If there is demand for it, I can put my modified version of the
>>>> Scaladocs on my own web space, but I would prefer not to. I only have
>>>> 20MB and the Scaladocs are 200MB in size. I hope Donna or Bill can set
>>>> up comparison sites again.
>>>>
>>>> Also, I used Firefox and Firebug to create my changes, but a (very)
>>>> quick check with IE8 and Chrome showed no problems.
>>>>
>>>> Ok, I'm waiting for feedback then.
>>>>
>>>> Regards,
>>>> Rüdiger
>>>>
>>>>
>>>> 2011/3/20 Ruediger Keller <ruediger.keller@rk42.de>:
>>>>> Ok. I'm working on it right now and it's coming along nicely, I think.
>>>>>
>>>>>
>>>>> 2011/3/20 Donna Malayeri <lindydonna@gmail.com>:
>>>>>>> I think my suggestion can be improved further, but first I want to
>>>>>>> know it it's worth the time. If everyone is in favor of the old style
>>>>>>> with alternating grey and white, I will not pursue this approach.
>>>>>>
>>>>>> Personally, I like the new style (no alternating black and grey), but I might be in a minority here. If we come up with some concrete re-designs, I can make a poll so people can vote on their preferred design.
>>>>>>
>>>>>> Donna
>>>>>
>>>>
>>
>>
>



--
Bill Venners
Artima, Inc.
http://www.artima.com

--
Kevin Wright

gtalk / msn : kev.lee.wright@gmail.comkev.lee.wright@gmail.commail: kevin.wright@scalatechnology.com
vibe / skype: kev.lee.wrightquora: http://www.quora.com/Kevin-Wright
twitter: @thecoda

"My point today is that, if we wish to count lines of code, we should not regard them as "lines produced" but as "lines spent": the current conventional wisdom is so foolish as to book that count on the wrong side of the ledger" ~ Dijkstra

Hi All,

I wanted to clarify what Scaladoc bugs I'm hoping we can zap before
2.9.0. The only ones I think should be fixed are those that actually
drop documentation from the output. The rest could wait until later.
There's just two more tickets, which may be two manifestations of the
same bug:

https://lampsvn.epfl.ch/trac/scala/ticket/4358
https://lampsvn.epfl.ch/trac/scala/ticket/4366

These both cause the full comment of a method to not show up at all.
You do see the short comment, but when you click on it to see the
full, the short goes away never to return.

Three other tickets that I wanted to see fixed in 2.9.0 are already
closed, but I haven't verified them myself yet because they didn't yet
show up in 2.9.0-SNAPSHOT.

https://lampsvn.epfl.ch/trac/scala/ticket/4356
https://lampsvn.epfl.ch/trac/scala/ticket/4357
https://lampsvn.epfl.ch/trac/scala/ticket/4361

Thanks for taking care of those. I'll try another snapshot tomorrow to
verify. The other bugs we submitted could wait until a later release.
The one that I think is the most important is:

https://lampsvn.epfl.ch/trac/scala/ticket/4360

This one may take some thought to figure out when to show a fully
qualified name and when not to. What happens in the example shown in
the ticket is that the methods show they take a Matcher parameter,
which is really an org.hamcrest.Matcher. Well ScalaTest also has
something called Matcher, so it is non-obvious when you look at the
documentation which Matcher is being required. Actually it is
misleading, because it looks like a ScalaTest Matcher is being
required, which is wrong.

The others we submitted can wait. One was markup showing up in equals
and eq comment:
https://lampsvn.epfl.ch/trac/scala/ticket/4359

Another was getting rid of the dollar signs prepending is/asInstanceOf:
https://lampsvn.epfl.ch/trac/scala/ticket/4368

The other two I realized this morning are actually the same bug. I was
seeing blocks of gray because those methods did not have any comments.
We reported one bug complaining about blocks of gray and another
complaining about missing comments. You can close the one complaining
about blocks of gray saying it's a duplicate:

https://lampsvn.epfl.ch/trac/scala/ticket/4367
https://lampsvn.epfl.ch/trac/scala/ticket/4369

So in summary, other than 4358 and 4366, which drop documentation and
may be the same bug, the only other change I hope to see in 2.9.0 is
some minor tweaks to the template.css file. I'll submit one more
suggestion for that here shortly, and that'll be it for 2.9.0.

Thanks everyone for helping with this stuff last minute like this.
Sorry I was so grouchy after my second pass the other day. It was very
frustrating to work hard on ScalaTest documentation like that and have
it mangled and even deleted by the tool. One thing I think that hasn't
been said much on this thread is that Scaladoc does have a lot of nice
features that work well. I quite like being able to enter names in the
search box and quickly find what I want. That's a big improvement over
JavaDoc, which gives me long lists I must scroll through. Now that it
works I quite like the JavaScript way of popping open and hiding the
full comment. So while I'm focused on finding and reporting bugs
because it is so last minute for 2.9.0, I don't want to be all
complaints.

Bill
----
Bill Venners
Artima, Inc.
http://www.artima.com

Hi Bill,
Hi list,

I did not mean to force any changes into 2.9, I just hijacked the
"wrong" thread. Sorry for that.

I wanted to start a constructive discussion by offering something for
trying, that I personally like better than the current scaladocs. And
it seems I reached my goal even though most of my changes don't seem
to be well received.

Bill, I will address your individual concerns later tomorrow.

Now I need to sleep.

Regards,
Rüdiger

2011/3/21 Bill Venners :
> Hi Ruediger,
>
> I generated Scaladoc for the ScalaTest trunk with the latest
> 2.9.0-SNAPSHOT, then put your three .css files in there. I then
> deployed it here:
>
> http://www.artima.com/sdp/ruediger2/
>
> Comparing this to my suggestion:
>
> http://www.artima.com/sdp/suggestion/
>
> I think your line height of 1.2 might be an improvement, but I could
> live with either for 2.9.0. I think I actually prefer the alternating
> gray/white background of current Scaladoc to the all-white with
> separator lines you're suggesting.
>
> There are some other issues I'm seeing in ruediger2. For example, on
> trait Suite:
>
> http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html
>
> There's extra white space at the top before the first comment line
> that begins, "A suite of tests. A Suite instance encapsulates..."
>
> There's missing white space after lists. Look at the list in the
> Extensability section down at the bottom for an example. After
> "expectedTestCount - override this method to count this Suite's...",
> there's no white space before the start of the next paragraph.
>
> I think also the paragraphs are not quite far enough apart to visually
> separate them.
>
> One thing I think we should separate is what would go into 2.9.0 and
> what would go later. This is very last minute for 2.9.0. I should have
> gone through and done my second pass looking for remaining issues
> earlier, but I was very busy. So at this point I think only critical
> problems should be addressed, and for layout I think just adding a bit
> of white space here and there is probably all we should try to do for
> 2.9.0. After that Donna can lead a more careful and thorough redesign
> of the layout, if need be.
>
> In my suggestion I was trying to be minimal so that the change would
> be low risk and easy enough to go into 2.9.0. I'll make one more pass
> today using your suggestions (line height of 1.2, and evening out
> those descriptions, which you pointed out yesterday.) After that I'll
> stop and I think that will be good enough for 2.9.0 as far as layout
> goes. The kind of changes your suggesting are more appropriate to
> consider for post-2.9.0 in my opinion.
>
> I will follow up with another email clarifying what Scaladoc bugs I am
> hoping to see closed for 2.9.0. Several we submitted yesterday are
> minutia that could wait until later, but there are still a few that
> result in documentation being dropped and inaccessible to the user,
> which I think we should try and fix for 2.9.0.
>
> Thanks.
>
> Bill
>
>
> On Sun, Mar 20, 2011 at 11:14 AM, Rüdiger Keller
> wrote:
>> Ok, I will do so.
>>
>> I have again made some changes. I think I'm quite happy with the
>> results now. Again, the files are attached.
>>
>> Regards,
>> Rüdiger
>>
>>
>> 2011/3/20 Donna Malayeri :
>>> Yes, please do create tickets (assuming non-duplicates). Thanks for your work and the explanations!  I will set up a site with both versions for comparison, probably on Monday or Tuesday.
>>>
>>> thanks,
>>> Donna
>>>
>>> On Mar 20, 2011, at 2:33 PM, Rüdiger Keller wrote:
>>>
>>>> Perhaps I should say something about *what* I changed. :-)
>>>>
>>>> First, I used the Scaladoc files from the latest 2.10 nightly build as
>>>> the basis for my changes, with Bill's changes on top. Although I must
>>>> admit that I reverted some of his changes.
>>>>
>>>> The biggest change is the layout of the member lists. No more gray
>>>> headers, everything is white now, with light gray separators in
>>>> between. Light gray is a much better choice than my previous black, I
>>>> think.
>>>>
>>>> Then I changed the spacing in many places to be more even / regular
>>>> and to ensure that things line up properly. Also I added some spacing
>>>> to emphasize the separation of separate things. Does that sentence
>>>> make sense? :-)
>>>>
>>>> Also, I changed the line height to the default which is something like
>>>> 1.2. This makes everything much easier to read.
>>>>
>>>> I changed the separators at the bottom of the expanded method / type
>>>> descriptions to be somewhat lighter and I also removed the separating
>>>> lines in between the parameter descriptions.
>>>>
>>>> Last but not least, I changed the line breaking behavior when the
>>>> window is not wide enough to display a signature in a single line.
>>>> Just compare it with the original version, you will notice the
>>>> improvement.
>>>>
>>>> There might be some other minor things, I forgot.
>>>>
>>>>
>>>> I wanted to add that I would like the colons for defining the types
>>>> not to have leading white space, just as Randall noted before. But I
>>>> cannot change that with the CSS, because the HTML files generated
>>>> contain white space (and even line breaks) before the colons.
>>>>
>>>> Another thing I thought had been fixed already, but is not: if I click
>>>> "display packages only" in the left panel, the packages collapse as
>>>> expected, but the "hide" links next to the package names do not change
>>>> into "show" links. IMHO this is clearly a bug and should be fixed.
>>>>
>>>> Should I create tickets for this? Although I think there already
>>>> exists one for the latter.
>>>>
>>>> Regards,
>>>> Rüdiger
>>>>
>>>>
>>>>
>>>> 2011/3/20 Rüdiger Keller :
>>>>> Ok, I'm done with the first iteration. I just attached the new
>>>>> template.css and index.css. I hope that is not too inconvenient.
>>>>>
>>>>> If there is demand for it, I can put my modified version of the
>>>>> Scaladocs on my own web space, but I would prefer not to. I only have
>>>>> 20MB and the Scaladocs are 200MB in size. I hope Donna or Bill can set
>>>>> up comparison sites again.
>>>>>
>>>>> Also, I used Firefox and Firebug to create my changes, but a (very)
>>>>> quick check with IE8 and Chrome showed no problems.
>>>>>
>>>>> Ok, I'm waiting for feedback then.
>>>>>
>>>>> Regards,
>>>>> Rüdiger
>>>>>
>>>>>
>>>>> 2011/3/20 Ruediger Keller :
>>>>>> Ok. I'm working on it right now and it's coming along nicely, I think.
>>>>>>
>>>>>>
>>>>>> 2011/3/20 Donna Malayeri :
>>>>>>>> I think my suggestion can be improved further, but first I want to
>>>>>>>> know it it's worth the time. If everyone is in favor of the old style
>>>>>>>> with alternating grey and white, I will not pursue this approach.
>>>>>>>
>>>>>>> Personally, I like the new style (no alternating black and grey), but I might be in a minority here. If we come up with some concrete re-designs, I can make a poll so people can vote on their preferred design.
>>>>>>>
>>>>>>> Donna
>>>>>>
>>>>>
>>>
>>>
>>
>
>
>
> --
> Bill Venners
> Artima, Inc.
> http://www.artima.com
>

I like Ruediger's layout. I think the grey / white altrenations detract from what's most important: the member names, so that's why I like it to be all white with thin separation lines. Agreed though that there should be an element that identifies open vs short comments -- maybe the rihg/downwards pointing triangle of standard outline views?

Cheers

 -- Martin

On Mon, Mar 21, 2011 at 1:54 AM, Rüdiger Keller <ruediger.keller@googlemail.com> wrote:

Hi Bill,
Hi list,

I did not mean to force any changes into 2.9, I just hijacked the
"wrong" thread. Sorry for that.

I wanted to start a constructive discussion by offering something for
trying, that I personally like better than the current scaladocs. And
it seems I reached my goal even though most of my changes don't seem
to be well received.

Bill, I will address your individual concerns later tomorrow.

Now I need to sleep.

Regards,
Rüdiger


2011/3/21 Bill Venners <bill@artima.com>:
> Hi Ruediger,
>
> I generated Scaladoc for the ScalaTest trunk with the latest
> 2.9.0-SNAPSHOT, then put your three .css files in there. I then
> deployed it here:
>
> http://www.artima.com/sdp/ruediger2/
>
> Comparing this to my suggestion:
>
> http://www.artima.com/sdp/suggestion/
>
> I think your line height of 1.2 might be an improvement, but I could
> live with either for 2.9.0. I think I actually prefer the alternating
> gray/white background of current Scaladoc to the all-white with
> separator lines you're suggesting.
>
> There are some other issues I'm seeing in ruediger2. For example, on
> trait Suite:
>
> http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html
>
> There's extra white space at the top before the first comment line
> that begins, "A suite of tests. A Suite instance encapsulates..."
>
> There's missing white space after lists. Look at the list in the
> Extensability section down at the bottom for an example. After
> "expectedTestCount - override this method to count this Suite's...",
> there's no white space before the start of the next paragraph.
>
> I think also the paragraphs are not quite far enough apart to visually
> separate them.
>
> One thing I think we should separate is what would go into 2.9.0 and
> what would go later. This is very last minute for 2.9.0. I should have
> gone through and done my second pass looking for remaining issues
> earlier, but I was very busy. So at this point I think only critical
> problems should be addressed, and for layout I think just adding a bit
> of white space here and there is probably all we should try to do for
> 2.9.0. After that Donna can lead a more careful and thorough redesign
> of the layout, if need be.
>
> In my suggestion I was trying to be minimal so that the change would
> be low risk and easy enough to go into 2.9.0. I'll make one more pass
> today using your suggestions (line height of 1.2, and evening out
> those descriptions, which you pointed out yesterday.) After that I'll
> stop and I think that will be good enough for 2.9.0 as far as layout
> goes. The kind of changes your suggesting are more appropriate to
> consider for post-2.9.0 in my opinion.
>
> I will follow up with another email clarifying what Scaladoc bugs I am
> hoping to see closed for 2.9.0. Several we submitted yesterday are
> minutia that could wait until later, but there are still a few that
> result in documentation being dropped and inaccessible to the user,
> which I think we should try and fix for 2.9.0.
>
> Thanks.
>
> Bill
>
>
> On Sun, Mar 20, 2011 at 11:14 AM, Rüdiger Keller
> <ruediger.keller@googlemail.com> wrote:
>> Ok, I will do so.
>>
>> I have again made some changes. I think I'm quite happy with the
>> results now. Again, the files are attached.
>>
>> Regards,
>> Rüdiger
>>
>>
>> 2011/3/20 Donna Malayeri <lindydonna@gmail.com>:
>>> Yes, please do create tickets (assuming non-duplicates). Thanks for your work and the explanations!  I will set up a site with both versions for comparison, probably on Monday or Tuesday.
>>>
>>> thanks,
>>> Donna
>>>
>>> On Mar 20, 2011, at 2:33 PM, Rüdiger Keller wrote:
>>>
>>>> Perhaps I should say something about *what* I changed. :-)
>>>>
>>>> First, I used the Scaladoc files from the latest 2.10 nightly build as
>>>> the basis for my changes, with Bill's changes on top. Although I must
>>>> admit that I reverted some of his changes.
>>>>
>>>> The biggest change is the layout of the member lists. No more gray
>>>> headers, everything is white now, with light gray separators in
>>>> between. Light gray is a much better choice than my previous black, I
>>>> think.
>>>>
>>>> Then I changed the spacing in many places to be more even / regular
>>>> and to ensure that things line up properly. Also I added some spacing
>>>> to emphasize the separation of separate things. Does that sentence
>>>> make sense? :-)
>>>>
>>>> Also, I changed the line height to the default which is something like
>>>> 1.2. This makes everything much easier to read.
>>>>
>>>> I changed the separators at the bottom of the expanded method / type
>>>> descriptions to be somewhat lighter and I also removed the separating
>>>> lines in between the parameter descriptions.
>>>>
>>>> Last but not least, I changed the line breaking behavior when the
>>>> window is not wide enough to display a signature in a single line.
>>>> Just compare it with the original version, you will notice the
>>>> improvement.
>>>>
>>>> There might be some other minor things, I forgot.
>>>>
>>>>
>>>> I wanted to add that I would like the colons for defining the types
>>>> not to have leading white space, just as Randall noted before. But I
>>>> cannot change that with the CSS, because the HTML files generated
>>>> contain white space (and even line breaks) before the colons.
>>>>
>>>> Another thing I thought had been fixed already, but is not: if I click
>>>> "display packages only" in the left panel, the packages collapse as
>>>> expected, but the "hide" links next to the package names do not change
>>>> into "show" links. IMHO this is clearly a bug and should be fixed.
>>>>
>>>> Should I create tickets for this? Although I think there already
>>>> exists one for the latter.
>>>>
>>>> Regards,
>>>> Rüdiger
>>>>
>>>>
>>>>
>>>> 2011/3/20 Rüdiger Keller <ruediger.keller@googlemail.com>:
>>>>> Ok, I'm done with the first iteration. I just attached the new
>>>>> template.css and index.css. I hope that is not too inconvenient.
>>>>>
>>>>> If there is demand for it, I can put my modified version of the
>>>>> Scaladocs on my own web space, but I would prefer not to. I only have
>>>>> 20MB and the Scaladocs are 200MB in size. I hope Donna or Bill can set
>>>>> up comparison sites again.
>>>>>
>>>>> Also, I used Firefox and Firebug to create my changes, but a (very)
>>>>> quick check with IE8 and Chrome showed no problems.
>>>>>
>>>>> Ok, I'm waiting for feedback then.
>>>>>
>>>>> Regards,
>>>>> Rüdiger
>>>>>
>>>>>
>>>>> 2011/3/20 Ruediger Keller <ruediger.keller@rk42.de>:
>>>>>> Ok. I'm working on it right now and it's coming along nicely, I think.
>>>>>>
>>>>>>
>>>>>> 2011/3/20 Donna Malayeri <lindydonna@gmail.com>:
>>>>>>>> I think my suggestion can be improved further, but first I want to
>>>>>>>> know it it's worth the time. If everyone is in favor of the old style
>>>>>>>> with alternating grey and white, I will not pursue this approach.
>>>>>>>
>>>>>>> Personally, I like the new style (no alternating black and grey), but I might be in a minority here. If we come up with some concrete re-designs, I can make a poll so people can vote on their preferred design.
>>>>>>>
>>>>>>> Donna
>>>>>>
>>>>>
>>>
>>>
>>
>
>
>
> --
> Bill Venners
> Artima, Inc.
> http://www.artima.com
>

--
----------------------------------------------
Martin Odersky
Prof., EPFL and CEO, Scala Solutions
PSED, 1015 Lausanne, Switzerland

Hi Martin, Ruediger, Donna,

I just realized that this non-obvious place to click problem exists at
the top. I just figured out now that you can click on the name of a
trait/class/object to get more information about it. I didn't know I
could do that. The ones below in ruediger2 look click-on-able to me
because the member names are blue. But I'm not sure how obvious that
would be if I didn't already know that I could click there.

Anyway, if you're going to move away from the alternating gray
background for 2.9.0, I'd request that you fork suggestion2 and just
make that one change. I.e., start with this file:

http://www.artima.com/sdp/suggestion2/lib/template.css

A couple things got broken in ruediger2, which I mentioned on an
earlier previous email. To see my concern, look at the difference
between the last two sections here on ruediger2:

http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html#errorHandling

versus suggestion2:

http://www.artima.com/sdp/suggestion2/org/scalatest/Suite.html#errorHand...

My main hope for a css tweak for 2.9.0 is that we can add a bit more
space between paragraphs and lines. ScalaTest docs are hard to read
without that whitespace.

Perhaps, Ruediger, you could start with the above suggestion2 css file
and just add only whatever you did to replace the alternating gray and
white background with the thin gray separator lines?

One other suggestion I have now that I know I can click on the top
line is to make the name of the trait/class/object the same blue color
as the member names. Blue still tends to mean "I can click here" to
people. That way there's a consistent signal about clicking to get
more info.

I'd stop there as a base line. Then if you want to try a triangle go
for it, but things like that can send you down a rabbit hole. For
2.9.0 it seems prudent to just do some very minimalist improvements at
this late point, and then a more thorough, careful makeover can be
done for a future release.

Thanks for your attention to this.

Bill

2011/3/20 martin odersky :
> I like Ruediger's layout. I think the grey / white altrenations detract from
> what's most important: the member names, so that's why I like it to be all
> white with thin separation lines. Agreed though that there should be an
> element that identifies open vs short comments -- maybe the rihg/downwards
> pointing triangle of standard outline views?
>
> Cheers
>
>  -- Martin
>
> On Mon, Mar 21, 2011 at 1:54 AM, Rüdiger Keller
> wrote:
>>
>> Hi Bill,
>> Hi list,
>>
>> I did not mean to force any changes into 2.9, I just hijacked the
>> "wrong" thread. Sorry for that.
>>
>> I wanted to start a constructive discussion by offering something for
>> trying, that I personally like better than the current scaladocs. And
>> it seems I reached my goal even though most of my changes don't seem
>> to be well received.
>>
>> Bill, I will address your individual concerns later tomorrow.
>>
>> Now I need to sleep.
>>
>> Regards,
>> Rüdiger
>>
>>
>> 2011/3/21 Bill Venners :
>> > Hi Ruediger,
>> >
>> > I generated Scaladoc for the ScalaTest trunk with the latest
>> > 2.9.0-SNAPSHOT, then put your three .css files in there. I then
>> > deployed it here:
>> >
>> > http://www.artima.com/sdp/ruediger2/
>> >
>> > Comparing this to my suggestion:
>> >
>> > http://www.artima.com/sdp/suggestion/
>> >
>> > I think your line height of 1.2 might be an improvement, but I could
>> > live with either for 2.9.0. I think I actually prefer the alternating
>> > gray/white background of current Scaladoc to the all-white with
>> > separator lines you're suggesting.
>> >
>> > There are some other issues I'm seeing in ruediger2. For example, on
>> > trait Suite:
>> >
>> > http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html
>> >
>> > There's extra white space at the top before the first comment line
>> > that begins, "A suite of tests. A Suite instance encapsulates..."
>> >
>> > There's missing white space after lists. Look at the list in the
>> > Extensability section down at the bottom for an example. After
>> > "expectedTestCount - override this method to count this Suite's...",
>> > there's no white space before the start of the next paragraph.
>> >
>> > I think also the paragraphs are not quite far enough apart to visually
>> > separate them.
>> >
>> > One thing I think we should separate is what would go into 2.9.0 and
>> > what would go later. This is very last minute for 2.9.0. I should have
>> > gone through and done my second pass looking for remaining issues
>> > earlier, but I was very busy. So at this point I think only critical
>> > problems should be addressed, and for layout I think just adding a bit
>> > of white space here and there is probably all we should try to do for
>> > 2.9.0. After that Donna can lead a more careful and thorough redesign
>> > of the layout, if need be.
>> >
>> > In my suggestion I was trying to be minimal so that the change would
>> > be low risk and easy enough to go into 2.9.0. I'll make one more pass
>> > today using your suggestions (line height of 1.2, and evening out
>> > those descriptions, which you pointed out yesterday.) After that I'll
>> > stop and I think that will be good enough for 2.9.0 as far as layout
>> > goes. The kind of changes your suggesting are more appropriate to
>> > consider for post-2.9.0 in my opinion.
>> >
>> > I will follow up with another email clarifying what Scaladoc bugs I am
>> > hoping to see closed for 2.9.0. Several we submitted yesterday are
>> > minutia that could wait until later, but there are still a few that
>> > result in documentation being dropped and inaccessible to the user,
>> > which I think we should try and fix for 2.9.0.
>> >
>> > Thanks.
>> >
>> > Bill
>> >
>> >
>> > On Sun, Mar 20, 2011 at 11:14 AM, Rüdiger Keller
>> > wrote:
>> >> Ok, I will do so.
>> >>
>> >> I have again made some changes. I think I'm quite happy with the
>> >> results now. Again, the files are attached.
>> >>
>> >> Regards,
>> >> Rüdiger
>> >>
>> >>
>> >> 2011/3/20 Donna Malayeri :
>> >>> Yes, please do create tickets (assuming non-duplicates). Thanks for
>> >>> your work and the explanations!  I will set up a site with both versions for
>> >>> comparison, probably on Monday or Tuesday.
>> >>>
>> >>> thanks,
>> >>> Donna
>> >>>
>> >>> On Mar 20, 2011, at 2:33 PM, Rüdiger Keller wrote:
>> >>>
>> >>>> Perhaps I should say something about *what* I changed. :-)
>> >>>>
>> >>>> First, I used the Scaladoc files from the latest 2.10 nightly build
>> >>>> as
>> >>>> the basis for my changes, with Bill's changes on top. Although I must
>> >>>> admit that I reverted some of his changes.
>> >>>>
>> >>>> The biggest change is the layout of the member lists. No more gray
>> >>>> headers, everything is white now, with light gray separators in
>> >>>> between. Light gray is a much better choice than my previous black, I
>> >>>> think.
>> >>>>
>> >>>> Then I changed the spacing in many places to be more even / regular
>> >>>> and to ensure that things line up properly. Also I added some spacing
>> >>>> to emphasize the separation of separate things. Does that sentence
>> >>>> make sense? :-)
>> >>>>
>> >>>> Also, I changed the line height to the default which is something
>> >>>> like
>> >>>> 1.2. This makes everything much easier to read.
>> >>>>
>> >>>> I changed the separators at the bottom of the expanded method / type
>> >>>> descriptions to be somewhat lighter and I also removed the separating
>> >>>> lines in between the parameter descriptions.
>> >>>>
>> >>>> Last but not least, I changed the line breaking behavior when the
>> >>>> window is not wide enough to display a signature in a single line.
>> >>>> Just compare it with the original version, you will notice the
>> >>>> improvement.
>> >>>>
>> >>>> There might be some other minor things, I forgot.
>> >>>>
>> >>>>
>> >>>> I wanted to add that I would like the colons for defining the types
>> >>>> not to have leading white space, just as Randall noted before. But I
>> >>>> cannot change that with the CSS, because the HTML files generated
>> >>>> contain white space (and even line breaks) before the colons.
>> >>>>
>> >>>> Another thing I thought had been fixed already, but is not: if I
>> >>>> click
>> >>>> "display packages only" in the left panel, the packages collapse as
>> >>>> expected, but the "hide" links next to the package names do not
>> >>>> change
>> >>>> into "show" links. IMHO this is clearly a bug and should be fixed.
>> >>>>
>> >>>> Should I create tickets for this? Although I think there already
>> >>>> exists one for the latter.
>> >>>>
>> >>>> Regards,
>> >>>> Rüdiger
>> >>>>
>> >>>>
>> >>>>
>> >>>> 2011/3/20 Rüdiger Keller :
>> >>>>> Ok, I'm done with the first iteration. I just attached the new
>> >>>>> template.css and index.css. I hope that is not too inconvenient.
>> >>>>>
>> >>>>> If there is demand for it, I can put my modified version of the
>> >>>>> Scaladocs on my own web space, but I would prefer not to. I only
>> >>>>> have
>> >>>>> 20MB and the Scaladocs are 200MB in size. I hope Donna or Bill can
>> >>>>> set
>> >>>>> up comparison sites again.
>> >>>>>
>> >>>>> Also, I used Firefox and Firebug to create my changes, but a (very)
>> >>>>> quick check with IE8 and Chrome showed no problems.
>> >>>>>
>> >>>>> Ok, I'm waiting for feedback then.
>> >>>>>
>> >>>>> Regards,
>> >>>>> Rüdiger
>> >>>>>
>> >>>>>
>> >>>>> 2011/3/20 Ruediger Keller :
>> >>>>>> Ok. I'm working on it right now and it's coming along nicely, I
>> >>>>>> think.
>> >>>>>>
>> >>>>>>
>> >>>>>> 2011/3/20 Donna Malayeri :
>> >>>>>>>> I think my suggestion can be improved further, but first I want
>> >>>>>>>> to
>> >>>>>>>> know it it's worth the time. If everyone is in favor of the old
>> >>>>>>>> style
>> >>>>>>>> with alternating grey and white, I will not pursue this approach.
>> >>>>>>>
>> >>>>>>> Personally, I like the new style (no alternating black and grey),
>> >>>>>>> but I might be in a minority here. If we come up with some concrete
>> >>>>>>> re-designs, I can make a poll so people can vote on their preferred design.
>> >>>>>>>
>> >>>>>>> Donna
>> >>>>>>
>> >>>>>
>> >>>
>> >>>
>> >>
>> >
>> >
>> >
>> > --
>> > Bill Venners
>> > Artima, Inc.
>> > http://www.artima.com
>> >
>
>
>
> --
> ----------------------------------------------
> Martin Odersky
> Prof., EPFL and CEO, Scala Solutions
> PSED, 1015 Lausanne, Switzerland
>
>
>

Hi Bill,

please find my comments below.

2011/3/21 Bill Venners :
> Hi Ruediger,
>
> I generated Scaladoc for the ScalaTest trunk with the latest
> 2.9.0-SNAPSHOT, then put your three .css files in there. I then
> deployed it here:
>
> http://www.artima.com/sdp/ruediger2/
>
> Comparing this to my suggestion:
>
> http://www.artima.com/sdp/suggestion/
>
> I think your line height of 1.2 might be an improvement, but I could
> live with either for 2.9.0. I think I actually prefer the alternating
> gray/white background of current Scaladoc to the all-white with
> separator lines you're suggesting.
>
> There are some other issues I'm seeing in ruediger2. For example, on
> trait Suite:
>
> http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html
>
> There's extra white space at the top before the first comment line
> that begins, "A suite of tests. A Suite instance encapsulates..."

That's intentional, to separate the signature from the text. Instead
of this, I will experiment with bigger font sizes for signatures.

>
> There's missing white space after lists. Look at the list in the
> Extensability section down at the bottom for an example. After
> "expectedTestCount - override this method to count this Suite's...",
> there's no white space before the start of the next paragraph.

Ok, that needs to be fixed.

>
> I think also the paragraphs are not quite far enough apart to visually
> separate them.

I have no problem changing it to your suggestion. The reason I didn't
make the spacing between the paragraphs as large as in your version
was that I used the scala.collection.Seq page for reference and there
are mostly single sentence paragraphs. IMHO these look a bit strange
with such a large spacing. But perhaps the comments need fixing here,
not the layout.

>
> One thing I think we should separate is what would go into 2.9.0 and
> what would go later. This is very last minute for 2.9.0. I should have
> gone through and done my second pass looking for remaining issues
> earlier, but I was very busy. So at this point I think only critical
> problems should be addressed, and for layout I think just adding a bit
> of white space here and there is probably all we should try to do for
> 2.9.0. After that Donna can lead a more careful and thorough redesign
> of the layout, if need be.

I agree. I did not mean to force any changes into 2.9.

>
> In my suggestion I was trying to be minimal so that the change would
> be low risk and easy enough to go into 2.9.0. I'll make one more pass
> today using your suggestions (line height of 1.2, and evening out
> those descriptions, which you pointed out yesterday.) After that I'll
> stop and I think that will be good enough for 2.9.0 as far as layout
> goes. The kind of changes your suggesting are more appropriate to
> consider for post-2.9.0 in my opinion.

Agreed.

>
> I will follow up with another email clarifying what Scaladoc bugs I am
> hoping to see closed for 2.9.0. Several we submitted yesterday are
> minutia that could wait until later, but there are still a few that
> result in documentation being dropped and inaccessible to the user,
> which I think we should try and fix for 2.9.0.

Again, I agree with you.

If I have time this evening, I will create an updated version of my
suggestions, that addresses some of your concerns and also Martin's
suggestion, if possible. Again, I do not mean to ship bigger changes
with 2.9. I'm 100% OK with the smaller set of changes you propose for
2.9.

Regards,
Rüdiger

Hi Ruediger,

All sounds fine. If the Seq docs look funny with that much white
space, then maybe it is better to use a bit less. I.e., we should
optimize for the Scala Scaladoc, not the ScalaTest one. I can always
increase the space between paragraphs for ScalaTest.

I feel like I'm peeling off layers of the onion, but I think I just
found another Scaladoc bug. Suite has a companion object, but not a
public one. Now that I just learned I can click to get more info about
Suite, I noticed there's a link to the companion object. When I click
on it, I get a page not found. I think the link to companion objects
may be showing up without considering whether they are actually
public. I can live with that one too in 2.9.0. Will submit a trak
issue tomorrow.

Bill

On Mon, Mar 21, 2011 at 2:44 AM, Rüdiger Keller
wrote:
> Hi Bill,
>
> please find my comments below.
>
>
> 2011/3/21 Bill Venners :
>> Hi Ruediger,
>>
>> I generated Scaladoc for the ScalaTest trunk with the latest
>> 2.9.0-SNAPSHOT, then put your three .css files in there. I then
>> deployed it here:
>>
>> http://www.artima.com/sdp/ruediger2/
>>
>> Comparing this to my suggestion:
>>
>> http://www.artima.com/sdp/suggestion/
>>
>> I think your line height of 1.2 might be an improvement, but I could
>> live with either for 2.9.0. I think I actually prefer the alternating
>> gray/white background of current Scaladoc to the all-white with
>> separator lines you're suggesting.
>>
>> There are some other issues I'm seeing in ruediger2. For example, on
>> trait Suite:
>>
>> http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html
>>
>> There's extra white space at the top before the first comment line
>> that begins, "A suite of tests. A Suite instance encapsulates..."
>
>
> That's intentional, to separate the signature from the text. Instead
> of this, I will experiment with bigger font sizes for signatures.
>
>
>>
>> There's missing white space after lists. Look at the list in the
>> Extensability section down at the bottom for an example. After
>> "expectedTestCount - override this method to count this Suite's...",
>> there's no white space before the start of the next paragraph.
>
>
> Ok, that needs to be fixed.
>
>
>>
>> I think also the paragraphs are not quite far enough apart to visually
>> separate them.
>
>
> I have no problem changing it to your suggestion. The reason I didn't
> make the spacing between the paragraphs as large as in your version
> was that I used the scala.collection.Seq page for reference and there
> are mostly single sentence paragraphs. IMHO these look a bit strange
> with such a large spacing. But perhaps the comments need fixing here,
> not the layout.
>
>
>>
>> One thing I think we should separate is what would go into 2.9.0 and
>> what would go later. This is very last minute for 2.9.0. I should have
>> gone through and done my second pass looking for remaining issues
>> earlier, but I was very busy. So at this point I think only critical
>> problems should be addressed, and for layout I think just adding a bit
>> of white space here and there is probably all we should try to do for
>> 2.9.0. After that Donna can lead a more careful and thorough redesign
>> of the layout, if need be.
>
>
> I agree. I did not mean to force any changes into 2.9.
>
>
>>
>> In my suggestion I was trying to be minimal so that the change would
>> be low risk and easy enough to go into 2.9.0. I'll make one more pass
>> today using your suggestions (line height of 1.2, and evening out
>> those descriptions, which you pointed out yesterday.) After that I'll
>> stop and I think that will be good enough for 2.9.0 as far as layout
>> goes. The kind of changes your suggesting are more appropriate to
>> consider for post-2.9.0 in my opinion.
>
>
> Agreed.
>
>
>>
>> I will follow up with another email clarifying what Scaladoc bugs I am
>> hoping to see closed for 2.9.0. Several we submitted yesterday are
>> minutia that could wait until later, but there are still a few that
>> result in documentation being dropped and inaccessible to the user,
>> which I think we should try and fix for 2.9.0.
>
>
> Again, I agree with you.
>
> If I have time this evening, I will create an updated version of my
> suggestions, that addresses some of your concerns and also Martin's
> suggestion, if possible. Again, I do not mean to ship bigger changes
> with 2.9. I'm 100% OK with the smaller set of changes you propose for
> 2.9.
>
> Regards,
> Rüdiger
>

Hi Bill,

as I said in my previous mail, I didn't really mean to change the CSS
for 2.9 but for the release after that.

I think your smaller set of suggestions are a strict improvement over
the current layout, so for me it would be perfectly OK to ship 2.9
with only your suggested changes.

If it is decided that the all white version should go into 2.9, I can
provide a minimal change set for that, as you suggest based
onsuggestion2. That would be:

Remove the "background-color" style from the ".signature" rule and add
a style "border-bottom: 1px solid lightgray;" to the "div.members > ol
> li" rule.

But perhaps we should wait until after 2.9 with such bigger changes.

Also, I like your idea of using blue consistently for clickable
things. Perhaps also adding underlining, as that is currently already
used in many places in the current scaladocs. I will explorer some
more on this when I have some time for it.

Regards,
Rüdiger

2011/3/21 Bill Venners :
> Hi Martin, Ruediger, Donna,
>
> I just realized that this non-obvious place to click problem exists at
> the top. I just figured out now that you can click on the name of a
> trait/class/object to get more information about it. I didn't know I
> could do that. The ones below in ruediger2 look click-on-able to me
> because the member names are blue. But I'm not sure how obvious that
> would be if I didn't already know that I could click there.
>
> Anyway, if you're going to move away from the alternating gray
> background for 2.9.0, I'd request that you fork suggestion2 and just
> make that one change. I.e., start with this file:
>
> http://www.artima.com/sdp/suggestion2/lib/template.css
>
> A couple things got broken in ruediger2, which I mentioned on an
> earlier previous email. To see my concern, look at the difference
> between the last two sections here on ruediger2:
>
> http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html#errorHandling
>
> versus suggestion2:
>
> http://www.artima.com/sdp/suggestion2/org/scalatest/Suite.html#errorHand...
>
> My main hope for a css tweak for 2.9.0 is that we can add a bit more
> space between paragraphs and lines. ScalaTest docs are hard to read
> without that whitespace.
>
> Perhaps, Ruediger, you could start with the above suggestion2 css file
> and just add only whatever you did to replace the alternating gray and
> white background with the thin gray separator lines?
>
> One other suggestion I have now that I know I can click on the top
> line is to make the name of the trait/class/object the same blue color
> as the member names. Blue still tends to mean "I can click here" to
> people. That way there's a consistent signal about clicking to get
> more info.
>
> I'd stop there as a base line. Then if you want to try a triangle go
> for it, but things like that can send you down a rabbit hole. For
> 2.9.0 it seems prudent to just do some very minimalist improvements at
> this late point, and then a more thorough, careful makeover can be
> done for a future release.
>
> Thanks for your attention to this.
>
> Bill
>
> 2011/3/20 martin odersky :
>> I like Ruediger's layout. I think the grey / white altrenations detract from
>> what's most important: the member names, so that's why I like it to be all
>> white with thin separation lines. Agreed though that there should be an
>> element that identifies open vs short comments -- maybe the rihg/downwards
>> pointing triangle of standard outline views?
>>
>> Cheers
>>
>>  -- Martin
>>
>> On Mon, Mar 21, 2011 at 1:54 AM, Rüdiger Keller
>> wrote:
>>>
>>> Hi Bill,
>>> Hi list,
>>>
>>> I did not mean to force any changes into 2.9, I just hijacked the
>>> "wrong" thread. Sorry for that.
>>>
>>> I wanted to start a constructive discussion by offering something for
>>> trying, that I personally like better than the current scaladocs. And
>>> it seems I reached my goal even though most of my changes don't seem
>>> to be well received.
>>>
>>> Bill, I will address your individual concerns later tomorrow.
>>>
>>> Now I need to sleep.
>>>
>>> Regards,
>>> Rüdiger
>>>
>>>
>>> 2011/3/21 Bill Venners :
>>> > Hi Ruediger,
>>> >
>>> > I generated Scaladoc for the ScalaTest trunk with the latest
>>> > 2.9.0-SNAPSHOT, then put your three .css files in there. I then
>>> > deployed it here:
>>> >
>>> > http://www.artima.com/sdp/ruediger2/
>>> >
>>> > Comparing this to my suggestion:
>>> >
>>> > http://www.artima.com/sdp/suggestion/
>>> >
>>> > I think your line height of 1.2 might be an improvement, but I could
>>> > live with either for 2.9.0. I think I actually prefer the alternating
>>> > gray/white background of current Scaladoc to the all-white with
>>> > separator lines you're suggesting.
>>> >
>>> > There are some other issues I'm seeing in ruediger2. For example, on
>>> > trait Suite:
>>> >
>>> > http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html
>>> >
>>> > There's extra white space at the top before the first comment line
>>> > that begins, "A suite of tests. A Suite instance encapsulates..."
>>> >
>>> > There's missing white space after lists. Look at the list in the
>>> > Extensability section down at the bottom for an example. After
>>> > "expectedTestCount - override this method to count this Suite's...",
>>> > there's no white space before the start of the next paragraph.
>>> >
>>> > I think also the paragraphs are not quite far enough apart to visually
>>> > separate them.
>>> >
>>> > One thing I think we should separate is what would go into 2.9.0 and
>>> > what would go later. This is very last minute for 2.9.0. I should have
>>> > gone through and done my second pass looking for remaining issues
>>> > earlier, but I was very busy. So at this point I think only critical
>>> > problems should be addressed, and for layout I think just adding a bit
>>> > of white space here and there is probably all we should try to do for
>>> > 2.9.0. After that Donna can lead a more careful and thorough redesign
>>> > of the layout, if need be.
>>> >
>>> > In my suggestion I was trying to be minimal so that the change would
>>> > be low risk and easy enough to go into 2.9.0. I'll make one more pass
>>> > today using your suggestions (line height of 1.2, and evening out
>>> > those descriptions, which you pointed out yesterday.) After that I'll
>>> > stop and I think that will be good enough for 2.9.0 as far as layout
>>> > goes. The kind of changes your suggesting are more appropriate to
>>> > consider for post-2.9.0 in my opinion.
>>> >
>>> > I will follow up with another email clarifying what Scaladoc bugs I am
>>> > hoping to see closed for 2.9.0. Several we submitted yesterday are
>>> > minutia that could wait until later, but there are still a few that
>>> > result in documentation being dropped and inaccessible to the user,
>>> > which I think we should try and fix for 2.9.0.
>>> >
>>> > Thanks.
>>> >
>>> > Bill
>>> >
>>> >
>>> > On Sun, Mar 20, 2011 at 11:14 AM, Rüdiger Keller
>>> > wrote:
>>> >> Ok, I will do so.
>>> >>
>>> >> I have again made some changes. I think I'm quite happy with the
>>> >> results now. Again, the files are attached.
>>> >>
>>> >> Regards,
>>> >> Rüdiger
>>> >>
>>> >>
>>> >> 2011/3/20 Donna Malayeri :
>>> >>> Yes, please do create tickets (assuming non-duplicates). Thanks for
>>> >>> your work and the explanations!  I will set up a site with both versions for
>>> >>> comparison, probably on Monday or Tuesday.
>>> >>>
>>> >>> thanks,
>>> >>> Donna
>>> >>>
>>> >>> On Mar 20, 2011, at 2:33 PM, Rüdiger Keller wrote:
>>> >>>
>>> >>>> Perhaps I should say something about *what* I changed. :-)
>>> >>>>
>>> >>>> First, I used the Scaladoc files from the latest 2.10 nightly build
>>> >>>> as
>>> >>>> the basis for my changes, with Bill's changes on top. Although I must
>>> >>>> admit that I reverted some of his changes.
>>> >>>>
>>> >>>> The biggest change is the layout of the member lists. No more gray
>>> >>>> headers, everything is white now, with light gray separators in
>>> >>>> between. Light gray is a much better choice than my previous black, I
>>> >>>> think.
>>> >>>>
>>> >>>> Then I changed the spacing in many places to be more even / regular
>>> >>>> and to ensure that things line up properly. Also I added some spacing
>>> >>>> to emphasize the separation of separate things. Does that sentence
>>> >>>> make sense? :-)
>>> >>>>
>>> >>>> Also, I changed the line height to the default which is something
>>> >>>> like
>>> >>>> 1.2. This makes everything much easier to read.
>>> >>>>
>>> >>>> I changed the separators at the bottom of the expanded method / type
>>> >>>> descriptions to be somewhat lighter and I also removed the separating
>>> >>>> lines in between the parameter descriptions.
>>> >>>>
>>> >>>> Last but not least, I changed the line breaking behavior when the
>>> >>>> window is not wide enough to display a signature in a single line.
>>> >>>> Just compare it with the original version, you will notice the
>>> >>>> improvement.
>>> >>>>
>>> >>>> There might be some other minor things, I forgot.
>>> >>>>
>>> >>>>
>>> >>>> I wanted to add that I would like the colons for defining the types
>>> >>>> not to have leading white space, just as Randall noted before. But I
>>> >>>> cannot change that with the CSS, because the HTML files generated
>>> >>>> contain white space (and even line breaks) before the colons.
>>> >>>>
>>> >>>> Another thing I thought had been fixed already, but is not: if I
>>> >>>> click
>>> >>>> "display packages only" in the left panel, the packages collapse as
>>> >>>> expected, but the "hide" links next to the package names do not
>>> >>>> change
>>> >>>> into "show" links. IMHO this is clearly a bug and should be fixed.
>>> >>>>
>>> >>>> Should I create tickets for this? Although I think there already
>>> >>>> exists one for the latter.
>>> >>>>
>>> >>>> Regards,
>>> >>>> Rüdiger
>>> >>>>
>>> >>>>
>>> >>>>
>>> >>>> 2011/3/20 Rüdiger Keller :
>>> >>>>> Ok, I'm done with the first iteration. I just attached the new
>>> >>>>> template.css and index.css. I hope that is not too inconvenient.
>>> >>>>>
>>> >>>>> If there is demand for it, I can put my modified version of the
>>> >>>>> Scaladocs on my own web space, but I would prefer not to. I only
>>> >>>>> have
>>> >>>>> 20MB and the Scaladocs are 200MB in size. I hope Donna or Bill can
>>> >>>>> set
>>> >>>>> up comparison sites again.
>>> >>>>>
>>> >>>>> Also, I used Firefox and Firebug to create my changes, but a (very)
>>> >>>>> quick check with IE8 and Chrome showed no problems.
>>> >>>>>
>>> >>>>> Ok, I'm waiting for feedback then.
>>> >>>>>
>>> >>>>> Regards,
>>> >>>>> Rüdiger
>>> >>>>>
>>> >>>>>
>>> >>>>> 2011/3/20 Ruediger Keller :
>>> >>>>>> Ok. I'm working on it right now and it's coming along nicely, I
>>> >>>>>> think.
>>> >>>>>>
>>> >>>>>>
>>> >>>>>> 2011/3/20 Donna Malayeri :
>>> >>>>>>>> I think my suggestion can be improved further, but first I want
>>> >>>>>>>> to
>>> >>>>>>>> know it it's worth the time. If everyone is in favor of the old
>>> >>>>>>>> style
>>> >>>>>>>> with alternating grey and white, I will not pursue this approach.
>>> >>>>>>>
>>> >>>>>>> Personally, I like the new style (no alternating black and grey),
>>> >>>>>>> but I might be in a minority here. If we come up with some concrete
>>> >>>>>>> re-designs, I can make a poll so people can vote on their preferred design.
>>> >>>>>>>
>>> >>>>>>> Donna
>>> >>>>>>
>>> >>>>>
>>> >>>
>>> >>>
>>> >>
>>> >
>>> >
>>> >
>>> > --
>>> > Bill Venners
>>> > Artima, Inc.
>>> > http://www.artima.com
>>> >
>>
>>
>>
>> --
>> ----------------------------------------------
>> Martin Odersky
>> Prof., EPFL and CEO, Scala Solutions
>> PSED, 1015 Lausanne, Switzerland
>>
>>
>>
>
>
>
> --
> Bill Venners
> Artima, Inc.
> http://www.artima.com
>

On Mon, Mar 21, 2011 at 11:01 AM, Rüdiger Keller <ruediger.keller@googlemail.com> wrote:

Hi Bill,

as I said in my previous mail, I didn't really mean to change the CSS
for 2.9 but for the release after that.

I think your smaller set of suggestions are a strict improvement over
the current layout, so for me it would be perfectly OK to ship 2.9
with only your suggested changes.

The first RC of 2.9 will likely go out this week, with a final version expected in about 2-6 weeks, depending on how the RC goes. Scaladoc is a bit decoupled, so we can do some changes between the RC and the final.

I believe it would be good to do changes in layout, if they improve things and aere feasible without taking too much time or possing too much risk.

Cheers

 -- Martin

On Mar 21, 2011, at 10:55 AM, Bill Venners wrote:
> I feel like I'm peeling off layers of the onion, but I think I just
> found another Scaladoc bug. Suite has a companion object, but not a
> public one. Now that I just learned I can click to get more info about
> Suite, I noticed there's a link to the companion object. When I click
> on it, I get a page not found. I think the link to companion objects
> may be showing up without considering whether they are actually
> public. I can live with that one too in 2.9.0. Will submit a trak
> issue tomorrow.

Ah, indeed. The searchable index is (correctly) not showing the companion, but the link is generated anyway. I'll create the Trac ticket and do the fix.

Donna

Agreed on the while thin separation lines.
One thing I'd like to pop more is the return type, so that one can quickly scan for return types. Is there a way that return type could do something to accomplish that, perhaps have return type right justified?
Thanks,Jon

2011/3/21 martin odersky <martin.odersky@epfl.ch>

I like Ruediger's layout. I think the grey / white altrenations detract from what's most important: the member names, so that's why I like it to be all white with thin separation lines. Agreed though that there should be an element that identifies open vs short comments -- maybe the rihg/downwards pointing triangle of standard outline views?

Cheers

 -- Martin

On Mon, Mar 21, 2011 at 1:54 AM, Rüdiger Keller <ruediger.keller@googlemail.com> wrote:

Hi Bill,
Hi list,

I did not mean to force any changes into 2.9, I just hijacked the
"wrong" thread. Sorry for that.

I wanted to start a constructive discussion by offering something for
trying, that I personally like better than the current scaladocs. And
it seems I reached my goal even though most of my changes don't seem
to be well received.

Bill, I will address your individual concerns later tomorrow.

Now I need to sleep.

Regards,
Rüdiger


2011/3/21 Bill Venners <bill@artima.com>:
> Hi Ruediger,
>
> I generated Scaladoc for the ScalaTest trunk with the latest
> 2.9.0-SNAPSHOT, then put your three .css files in there. I then
> deployed it here:
>
> http://www.artima.com/sdp/ruediger2/
>
> Comparing this to my suggestion:
>
> http://www.artima.com/sdp/suggestion/
>
> I think your line height of 1.2 might be an improvement, but I could
> live with either for 2.9.0. I think I actually prefer the alternating
> gray/white background of current Scaladoc to the all-white with
> separator lines you're suggesting.
>
> There are some other issues I'm seeing in ruediger2. For example, on
> trait Suite:
>
> http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html
>
> There's extra white space at the top before the first comment line
> that begins, "A suite of tests. A Suite instance encapsulates..."
>
> There's missing white space after lists. Look at the list in the
> Extensability section down at the bottom for an example. After
> "expectedTestCount - override this method to count this Suite's...",
> there's no white space before the start of the next paragraph.
>
> I think also the paragraphs are not quite far enough apart to visually
> separate them.
>
> One thing I think we should separate is what would go into 2.9.0 and
> what would go later. This is very last minute for 2.9.0. I should have
> gone through and done my second pass looking for remaining issues
> earlier, but I was very busy. So at this point I think only critical
> problems should be addressed, and for layout I think just adding a bit
> of white space here and there is probably all we should try to do for
> 2.9.0. After that Donna can lead a more careful and thorough redesign
> of the layout, if need be.
>
> In my suggestion I was trying to be minimal so that the change would
> be low risk and easy enough to go into 2.9.0. I'll make one more pass
> today using your suggestions (line height of 1.2, and evening out
> those descriptions, which you pointed out yesterday.) After that I'll
> stop and I think that will be good enough for 2.9.0 as far as layout
> goes. The kind of changes your suggesting are more appropriate to
> consider for post-2.9.0 in my opinion.
>
> I will follow up with another email clarifying what Scaladoc bugs I am
> hoping to see closed for 2.9.0. Several we submitted yesterday are
> minutia that could wait until later, but there are still a few that
> result in documentation being dropped and inaccessible to the user,
> which I think we should try and fix for 2.9.0.
>
> Thanks.
>
> Bill
>
>
> On Sun, Mar 20, 2011 at 11:14 AM, Rüdiger Keller
> <ruediger.keller@googlemail.com> wrote:
>> Ok, I will do so.
>>
>> I have again made some changes. I think I'm quite happy with the
>> results now. Again, the files are attached.
>>
>> Regards,
>> Rüdiger
>>
>>
>> 2011/3/20 Donna Malayeri <lindydonna@gmail.com>:
>>> Yes, please do create tickets (assuming non-duplicates). Thanks for your work and the explanations!  I will set up a site with both versions for comparison, probably on Monday or Tuesday.
>>>
>>> thanks,
>>> Donna
>>>
>>> On Mar 20, 2011, at 2:33 PM, Rüdiger Keller wrote:
>>>
>>>> Perhaps I should say something about *what* I changed. :-)
>>>>
>>>> First, I used the Scaladoc files from the latest 2.10 nightly build as
>>>> the basis for my changes, with Bill's changes on top. Although I must
>>>> admit that I reverted some of his changes.
>>>>
>>>> The biggest change is the layout of the member lists. No more gray
>>>> headers, everything is white now, with light gray separators in
>>>> between. Light gray is a much better choice than my previous black, I
>>>> think.
>>>>
>>>> Then I changed the spacing in many places to be more even / regular
>>>> and to ensure that things line up properly. Also I added some spacing
>>>> to emphasize the separation of separate things. Does that sentence
>>>> make sense? :-)
>>>>
>>>> Also, I changed the line height to the default which is something like
>>>> 1.2. This makes everything much easier to read.
>>>>
>>>> I changed the separators at the bottom of the expanded method / type
>>>> descriptions to be somewhat lighter and I also removed the separating
>>>> lines in between the parameter descriptions.
>>>>
>>>> Last but not least, I changed the line breaking behavior when the
>>>> window is not wide enough to display a signature in a single line.
>>>> Just compare it with the original version, you will notice the
>>>> improvement.
>>>>
>>>> There might be some other minor things, I forgot.
>>>>
>>>>
>>>> I wanted to add that I would like the colons for defining the types
>>>> not to have leading white space, just as Randall noted before. But I
>>>> cannot change that with the CSS, because the HTML files generated
>>>> contain white space (and even line breaks) before the colons.
>>>>
>>>> Another thing I thought had been fixed already, but is not: if I click
>>>> "display packages only" in the left panel, the packages collapse as
>>>> expected, but the "hide" links next to the package names do not change
>>>> into "show" links. IMHO this is clearly a bug and should be fixed.
>>>>
>>>> Should I create tickets for this? Although I think there already
>>>> exists one for the latter.
>>>>
>>>> Regards,
>>>> Rüdiger
>>>>
>>>>
>>>>
>>>> 2011/3/20 Rüdiger Keller <ruediger.keller@googlemail.com>:
>>>>> Ok, I'm done with the first iteration. I just attached the new
>>>>> template.css and index.css. I hope that is not too inconvenient.
>>>>>
>>>>> If there is demand for it, I can put my modified version of the
>>>>> Scaladocs on my own web space, but I would prefer not to. I only have
>>>>> 20MB and the Scaladocs are 200MB in size. I hope Donna or Bill can set
>>>>> up comparison sites again.
>>>>>
>>>>> Also, I used Firefox and Firebug to create my changes, but a (very)
>>>>> quick check with IE8 and Chrome showed no problems.
>>>>>
>>>>> Ok, I'm waiting for feedback then.
>>>>>
>>>>> Regards,
>>>>> Rüdiger
>>>>>
>>>>>
>>>>> 2011/3/20 Ruediger Keller <ruediger.keller@rk42.de>:
>>>>>> Ok. I'm working on it right now and it's coming along nicely, I think.
>>>>>>
>>>>>>
>>>>>> 2011/3/20 Donna Malayeri <lindydonna@gmail.com>:
>>>>>>>> I think my suggestion can be improved further, but first I want to
>>>>>>>> know it it's worth the time. If everyone is in favor of the old style
>>>>>>>> with alternating grey and white, I will not pursue this approach.
>>>>>>>
>>>>>>> Personally, I like the new style (no alternating black and grey), but I might be in a minority here. If we come up with some concrete re-designs, I can make a poll so people can vote on their preferred design.
>>>>>>>
>>>>>>> Donna
>>>>>>
>>>>>
>>>
>>>
>>
>
>
>
> --
> Bill Venners
> Artima, Inc.
> http://www.artima.com
>

--
----------------------------------------------
Martin Odersky
Prof., EPFL and CEO, Scala Solutions
PSED, 1015 Lausanne, Switzerland

Hi Ruediger,

On Mon, Mar 21, 2011 at 3:01 AM, Rüdiger Keller
wrote:
> If it is decided that the all white version should go into 2.9, I can
> provide a minimal change set for that, as you suggest based
> onsuggestion2. That would be:
>
> Remove the "background-color" style from the ".signature" rule and add
> a style "border-bottom: 1px solid lightgray;" to the "div.members > ol
>> li" rule.
>
That sounded easy so I made those mods off of suggestion2 and put an
example here:

http://www.artima.com/sdp/suggestion3/

I quickly glanced at making the class/trait/object name blue, but it
didn't look obvious and I didn't want to tweak too much. Others can
work on making it more obvious you can click up top.

So suggestion3 has the extra white space I think would help
readability at least of ScalaTest's docs, plus Ruediger's layout of
the members that gets rid of the alternating gray/white bars. Css file
is:

http://www.artima.com/sdp/suggestion3/lib/template.css

Diff from original, which I grabbed about three days ago now from
2.9.0-SNAPSHOT, is:

[sites@artima01 sdp]$ diff original/lib/template.css
suggestion3/lib/template.css
20c20
< line-height: 1;
---
> line-height: 1.2;
157a158
> border-bottom: 1px solid lightgray;
172c173
< padding: 3px;
---
> padding: 2px;
177d177
< background-color: #e5e5e5;
234,235c234,235
< margin-bottom: 0.4em;
< margin-top: 0.4em;
---
> margin-bottom: 0.9em;
> margin-top: 0.9em;
362c362
< padding: 0;
---
> padding: 2px;
368a369,370
> margin-top: 2px;
> margin-bottom: 2px;
415a418,421
> div.fullcomment dl.paramcmts dd.cmt p {
> margin-top: 2px;
> margin-bottom: 2px;
> }

I haven't tried this in as many browsers as my previous suggestions.
Should be tried in a lot of them.

Bill

> But perhaps we should wait until after 2.9 with such bigger changes.
>
> Also, I like your idea of using blue consistently for clickable
> things. Perhaps also adding underlining, as that is currently already
> used in many places in the current scaladocs. I will explorer some
> more on this when I have some time for it.
>
> Regards,
> Rüdiger
>
>
> 2011/3/21 Bill Venners :
>> Hi Martin, Ruediger, Donna,
>>
>> I just realized that this non-obvious place to click problem exists at
>> the top. I just figured out now that you can click on the name of a
>> trait/class/object to get more information about it. I didn't know I
>> could do that. The ones below in ruediger2 look click-on-able to me
>> because the member names are blue. But I'm not sure how obvious that
>> would be if I didn't already know that I could click there.
>>
>> Anyway, if you're going to move away from the alternating gray
>> background for 2.9.0, I'd request that you fork suggestion2 and just
>> make that one change. I.e., start with this file:
>>
>> http://www.artima.com/sdp/suggestion2/lib/template.css
>>
>> A couple things got broken in ruediger2, which I mentioned on an
>> earlier previous email. To see my concern, look at the difference
>> between the last two sections here on ruediger2:
>>
>> http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html#errorHandling
>>
>> versus suggestion2:
>>
>> http://www.artima.com/sdp/suggestion2/org/scalatest/Suite.html#errorHand...
>>
>> My main hope for a css tweak for 2.9.0 is that we can add a bit more
>> space between paragraphs and lines. ScalaTest docs are hard to read
>> without that whitespace.
>>
>> Perhaps, Ruediger, you could start with the above suggestion2 css file
>> and just add only whatever you did to replace the alternating gray and
>> white background with the thin gray separator lines?
>>
>> One other suggestion I have now that I know I can click on the top
>> line is to make the name of the trait/class/object the same blue color
>> as the member names. Blue still tends to mean "I can click here" to
>> people. That way there's a consistent signal about clicking to get
>> more info.
>>
>> I'd stop there as a base line. Then if you want to try a triangle go
>> for it, but things like that can send you down a rabbit hole. For
>> 2.9.0 it seems prudent to just do some very minimalist improvements at
>> this late point, and then a more thorough, careful makeover can be
>> done for a future release.
>>
>> Thanks for your attention to this.
>>
>> Bill
>>
>> 2011/3/20 martin odersky :
>>> I like Ruediger's layout. I think the grey / white altrenations detract from
>>> what's most important: the member names, so that's why I like it to be all
>>> white with thin separation lines. Agreed though that there should be an
>>> element that identifies open vs short comments -- maybe the rihg/downwards
>>> pointing triangle of standard outline views?
>>>
>>> Cheers
>>>
>>>  -- Martin
>>>
>>> On Mon, Mar 21, 2011 at 1:54 AM, Rüdiger Keller
>>> wrote:
>>>>
>>>> Hi Bill,
>>>> Hi list,
>>>>
>>>> I did not mean to force any changes into 2.9, I just hijacked the
>>>> "wrong" thread. Sorry for that.
>>>>
>>>> I wanted to start a constructive discussion by offering something for
>>>> trying, that I personally like better than the current scaladocs. And
>>>> it seems I reached my goal even though most of my changes don't seem
>>>> to be well received.
>>>>
>>>> Bill, I will address your individual concerns later tomorrow.
>>>>
>>>> Now I need to sleep.
>>>>
>>>> Regards,
>>>> Rüdiger
>>>>
>>>>
>>>> 2011/3/21 Bill Venners :
>>>> > Hi Ruediger,
>>>> >
>>>> > I generated Scaladoc for the ScalaTest trunk with the latest
>>>> > 2.9.0-SNAPSHOT, then put your three .css files in there. I then
>>>> > deployed it here:
>>>> >
>>>> > http://www.artima.com/sdp/ruediger2/
>>>> >
>>>> > Comparing this to my suggestion:
>>>> >
>>>> > http://www.artima.com/sdp/suggestion/
>>>> >
>>>> > I think your line height of 1.2 might be an improvement, but I could
>>>> > live with either for 2.9.0. I think I actually prefer the alternating
>>>> > gray/white background of current Scaladoc to the all-white with
>>>> > separator lines you're suggesting.
>>>> >
>>>> > There are some other issues I'm seeing in ruediger2. For example, on
>>>> > trait Suite:
>>>> >
>>>> > http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html
>>>> >
>>>> > There's extra white space at the top before the first comment line
>>>> > that begins, "A suite of tests. A Suite instance encapsulates..."
>>>> >
>>>> > There's missing white space after lists. Look at the list in the
>>>> > Extensability section down at the bottom for an example. After
>>>> > "expectedTestCount - override this method to count this Suite's...",
>>>> > there's no white space before the start of the next paragraph.
>>>> >
>>>> > I think also the paragraphs are not quite far enough apart to visually
>>>> > separate them.
>>>> >
>>>> > One thing I think we should separate is what would go into 2.9.0 and
>>>> > what would go later. This is very last minute for 2.9.0. I should have
>>>> > gone through and done my second pass looking for remaining issues
>>>> > earlier, but I was very busy. So at this point I think only critical
>>>> > problems should be addressed, and for layout I think just adding a bit
>>>> > of white space here and there is probably all we should try to do for
>>>> > 2.9.0. After that Donna can lead a more careful and thorough redesign
>>>> > of the layout, if need be.
>>>> >
>>>> > In my suggestion I was trying to be minimal so that the change would
>>>> > be low risk and easy enough to go into 2.9.0. I'll make one more pass
>>>> > today using your suggestions (line height of 1.2, and evening out
>>>> > those descriptions, which you pointed out yesterday.) After that I'll
>>>> > stop and I think that will be good enough for 2.9.0 as far as layout
>>>> > goes. The kind of changes your suggesting are more appropriate to
>>>> > consider for post-2.9.0 in my opinion.
>>>> >
>>>> > I will follow up with another email clarifying what Scaladoc bugs I am
>>>> > hoping to see closed for 2.9.0. Several we submitted yesterday are
>>>> > minutia that could wait until later, but there are still a few that
>>>> > result in documentation being dropped and inaccessible to the user,
>>>> > which I think we should try and fix for 2.9.0.
>>>> >
>>>> > Thanks.
>>>> >
>>>> > Bill
>>>> >
>>>> >
>>>> > On Sun, Mar 20, 2011 at 11:14 AM, Rüdiger Keller
>>>> > wrote:
>>>> >> Ok, I will do so.
>>>> >>
>>>> >> I have again made some changes. I think I'm quite happy with the
>>>> >> results now. Again, the files are attached.
>>>> >>
>>>> >> Regards,
>>>> >> Rüdiger
>>>> >>
>>>> >>
>>>> >> 2011/3/20 Donna Malayeri :
>>>> >>> Yes, please do create tickets (assuming non-duplicates). Thanks for
>>>> >>> your work and the explanations!  I will set up a site with both versions for
>>>> >>> comparison, probably on Monday or Tuesday.
>>>> >>>
>>>> >>> thanks,
>>>> >>> Donna
>>>> >>>
>>>> >>> On Mar 20, 2011, at 2:33 PM, Rüdiger Keller wrote:
>>>> >>>
>>>> >>>> Perhaps I should say something about *what* I changed. :-)
>>>> >>>>
>>>> >>>> First, I used the Scaladoc files from the latest 2.10 nightly build
>>>> >>>> as
>>>> >>>> the basis for my changes, with Bill's changes on top. Although I must
>>>> >>>> admit that I reverted some of his changes.
>>>> >>>>
>>>> >>>> The biggest change is the layout of the member lists. No more gray
>>>> >>>> headers, everything is white now, with light gray separators in
>>>> >>>> between. Light gray is a much better choice than my previous black, I
>>>> >>>> think.
>>>> >>>>
>>>> >>>> Then I changed the spacing in many places to be more even / regular
>>>> >>>> and to ensure that things line up properly. Also I added some spacing
>>>> >>>> to emphasize the separation of separate things. Does that sentence
>>>> >>>> make sense? :-)
>>>> >>>>
>>>> >>>> Also, I changed the line height to the default which is something
>>>> >>>> like
>>>> >>>> 1.2. This makes everything much easier to read.
>>>> >>>>
>>>> >>>> I changed the separators at the bottom of the expanded method / type
>>>> >>>> descriptions to be somewhat lighter and I also removed the separating
>>>> >>>> lines in between the parameter descriptions.
>>>> >>>>
>>>> >>>> Last but not least, I changed the line breaking behavior when the
>>>> >>>> window is not wide enough to display a signature in a single line.
>>>> >>>> Just compare it with the original version, you will notice the
>>>> >>>> improvement.
>>>> >>>>
>>>> >>>> There might be some other minor things, I forgot.
>>>> >>>>
>>>> >>>>
>>>> >>>> I wanted to add that I would like the colons for defining the types
>>>> >>>> not to have leading white space, just as Randall noted before. But I
>>>> >>>> cannot change that with the CSS, because the HTML files generated
>>>> >>>> contain white space (and even line breaks) before the colons.
>>>> >>>>
>>>> >>>> Another thing I thought had been fixed already, but is not: if I
>>>> >>>> click
>>>> >>>> "display packages only" in the left panel, the packages collapse as
>>>> >>>> expected, but the "hide" links next to the package names do not
>>>> >>>> change
>>>> >>>> into "show" links. IMHO this is clearly a bug and should be fixed.
>>>> >>>>
>>>> >>>> Should I create tickets for this? Although I think there already
>>>> >>>> exists one for the latter.
>>>> >>>>
>>>> >>>> Regards,
>>>> >>>> Rüdiger
>>>> >>>>
>>>> >>>>
>>>> >>>>
>>>> >>>> 2011/3/20 Rüdiger Keller :
>>>> >>>>> Ok, I'm done with the first iteration. I just attached the new
>>>> >>>>> template.css and index.css. I hope that is not too inconvenient.
>>>> >>>>>
>>>> >>>>> If there is demand for it, I can put my modified version of the
>>>> >>>>> Scaladocs on my own web space, but I would prefer not to. I only
>>>> >>>>> have
>>>> >>>>> 20MB and the Scaladocs are 200MB in size. I hope Donna or Bill can
>>>> >>>>> set
>>>> >>>>> up comparison sites again.
>>>> >>>>>
>>>> >>>>> Also, I used Firefox and Firebug to create my changes, but a (very)
>>>> >>>>> quick check with IE8 and Chrome showed no problems.
>>>> >>>>>
>>>> >>>>> Ok, I'm waiting for feedback then.
>>>> >>>>>
>>>> >>>>> Regards,
>>>> >>>>> Rüdiger
>>>> >>>>>
>>>> >>>>>
>>>> >>>>> 2011/3/20 Ruediger Keller :
>>>> >>>>>> Ok. I'm working on it right now and it's coming along nicely, I
>>>> >>>>>> think.
>>>> >>>>>>
>>>> >>>>>>
>>>> >>>>>> 2011/3/20 Donna Malayeri :
>>>> >>>>>>>> I think my suggestion can be improved further, but first I want
>>>> >>>>>>>> to
>>>> >>>>>>>> know it it's worth the time. If everyone is in favor of the old
>>>> >>>>>>>> style
>>>> >>>>>>>> with alternating grey and white, I will not pursue this approach.
>>>> >>>>>>>
>>>> >>>>>>> Personally, I like the new style (no alternating black and grey),
>>>> >>>>>>> but I might be in a minority here. If we come up with some concrete
>>>> >>>>>>> re-designs, I can make a poll so people can vote on their preferred design.
>>>> >>>>>>>
>>>> >>>>>>> Donna
>>>> >>>>>>
>>>> >>>>>
>>>> >>>
>>>> >>>
>>>> >>
>>>> >
>>>> >
>>>> >
>>>> > --
>>>> > Bill Venners
>>>> > Artima, Inc.
>>>> > http://www.artima.com
>>>> >
>>>
>>>
>>>
>>> --
>>> ----------------------------------------------
>>> Martin Odersky
>>> Prof., EPFL and CEO, Scala Solutions
>>> PSED, 1015 Lausanne, Switzerland
>>>
>>>
>>>
>>
>>
>>
>> --
>> Bill Venners
>> Artima, Inc.
>> http://www.artima.com
>>
>

Hi!

Would it be possible to have a small fade-in/fade-out effect when the
mouse is over something which can be expanded/collapsed?

I think the behavior of the class description where you can click on
anything and it will expand to show linear super types, known subclasses
and self types, but have to click on the first sentence to collapse it
again is very confusing.

Imho I would suggest to remove the whole collapsing/expanding in the
class description and show these three lines by default the whole
complication isn't worth these three lines.

Thanks everyone for their great work!

Bye,

Simon

On Mon, Mar 21, 2011 at 6:59 PM, Bill Venners <bill@artima.com> wrote:

Hi Ruediger,

On Mon, Mar 21, 2011 at 3:01 AM, Rüdiger Keller
<ruediger.keller@googlemail.com> wrote:
> If it is decided that the all white version should go into 2.9, I can
> provide a minimal change set for that, as you suggest based
> onsuggestion2. That would be:
>
> Remove the "background-color" style from the ".signature" rule and add
> a style "border-bottom: 1px solid lightgray;" to the "div.members > ol
>> li" rule.
>
That sounded easy so I made those mods off of suggestion2 and put an
example here:

http://www.artima.com/sdp/suggestion3/

Collapse works when clicking on stuff, but expand is broken, on FF4
 

I quickly glanced at making the class/trait/object name blue, but it
didn't look obvious and I didn't want to tweak too much. Others can
work on making it more obvious you can click up top.

So suggestion3 has the extra white space I think would help
readability at least of ScalaTest's docs, plus Ruediger's layout of
the members that gets rid of the alternating gray/white bars. Css file
is:

http://www.artima.com/sdp/suggestion3/lib/template.css

Diff from original, which I grabbed about three days ago now from
2.9.0-SNAPSHOT, is:

[sites@artima01 sdp]$ diff original/lib/template.css
suggestion3/lib/template.css
20c20
<   line-height: 1;
---
>   line-height: 1.2;
157a158
>   border-bottom: 1px solid lightgray;
172c173
<   padding: 3px;
---
>   padding: 2px;
177d177
<   background-color: #e5e5e5;
234,235c234,235
<       margin-bottom: 0.4em;
<       margin-top: 0.4em;
---
>       margin-bottom: 0.9em;
>       margin-top: 0.9em;
362c362
<   padding: 0;
---
>   padding: 2px;
368a369,370
>   margin-top: 2px;
>   margin-bottom: 2px;
415a418,421
> div.fullcomment dl.paramcmts dd.cmt p {
>   margin-top: 2px;
>   margin-bottom: 2px;
> }

I haven't tried this in as many browsers as my previous suggestions.
Should be tried in a lot of them.

Bill


> But perhaps we should wait until after 2.9 with such bigger changes.
>
> Also, I like your idea of using blue consistently for clickable
> things. Perhaps also adding underlining, as that is currently already
> used in many places in the current scaladocs. I will explorer some
> more on this when I have some time for it.
>
> Regards,
> Rüdiger
>
>
> 2011/3/21 Bill Venners <bill@artima.com>:
>> Hi Martin, Ruediger, Donna,
>>
>> I just realized that this non-obvious place to click problem exists at
>> the top. I just figured out now that you can click on the name of a
>> trait/class/object to get more information about it. I didn't know I
>> could do that. The ones below in ruediger2 look click-on-able to me
>> because the member names are blue. But I'm not sure how obvious that
>> would be if I didn't already know that I could click there.
>>
>> Anyway, if you're going to move away from the alternating gray
>> background for 2.9.0, I'd request that you fork suggestion2 and just
>> make that one change. I.e., start with this file:
>>
>> http://www.artima.com/sdp/suggestion2/lib/template.css
>>
>> A couple things got broken in ruediger2, which I mentioned on an
>> earlier previous email. To see my concern, look at the difference
>> between the last two sections here on ruediger2:
>>
>> http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html#errorHandling
>>
>> versus suggestion2:
>>
>> http://www.artima.com/sdp/suggestion2/org/scalatest/Suite.html#errorHandling
>>
>> My main hope for a css tweak for 2.9.0 is that we can add a bit more
>> space between paragraphs and lines. ScalaTest docs are hard to read
>> without that whitespace.
>>
>> Perhaps, Ruediger, you could start with the above suggestion2 css file
>> and just add only whatever you did to replace the alternating gray and
>> white background with the thin gray separator lines?
>>
>> One other suggestion I have now that I know I can click on the top
>> line is to make the name of the trait/class/object the same blue color
>> as the member names. Blue still tends to mean "I can click here" to
>> people. That way there's a consistent signal about clicking to get
>> more info.
>>
>> I'd stop there as a base line. Then if you want to try a triangle go
>> for it, but things like that can send you down a rabbit hole. For
>> 2.9.0 it seems prudent to just do some very minimalist improvements at
>> this late point, and then a more thorough, careful makeover can be
>> done for a future release.
>>
>> Thanks for your attention to this.
>>
>> Bill
>>
>> 2011/3/20 martin odersky <martin.odersky@epfl.ch>:
>>> I like Ruediger's layout. I think the grey / white altrenations detract from
>>> what's most important: the member names, so that's why I like it to be all
>>> white with thin separation lines. Agreed though that there should be an
>>> element that identifies open vs short comments -- maybe the rihg/downwards
>>> pointing triangle of standard outline views?
>>>
>>> Cheers
>>>
>>>  -- Martin
>>>
>>> On Mon, Mar 21, 2011 at 1:54 AM, Rüdiger Keller
>>> <ruediger.keller@googlemail.com> wrote:
>>>>
>>>> Hi Bill,
>>>> Hi list,
>>>>
>>>> I did not mean to force any changes into 2.9, I just hijacked the
>>>> "wrong" thread. Sorry for that.
>>>>
>>>> I wanted to start a constructive discussion by offering something for
>>>> trying, that I personally like better than the current scaladocs. And
>>>> it seems I reached my goal even though most of my changes don't seem
>>>> to be well received.
>>>>
>>>> Bill, I will address your individual concerns later tomorrow.
>>>>
>>>> Now I need to sleep.
>>>>
>>>> Regards,
>>>> Rüdiger
>>>>
>>>>
>>>> 2011/3/21 Bill Venners <bill@artima.com>:
>>>> > Hi Ruediger,
>>>> >
>>>> > I generated Scaladoc for the ScalaTest trunk with the latest
>>>> > 2.9.0-SNAPSHOT, then put your three .css files in there. I then
>>>> > deployed it here:
>>>> >
>>>> > http://www.artima.com/sdp/ruediger2/
>>>> >
>>>> > Comparing this to my suggestion:
>>>> >
>>>> > http://www.artima.com/sdp/suggestion/
>>>> >
>>>> > I think your line height of 1.2 might be an improvement, but I could
>>>> > live with either for 2.9.0. I think I actually prefer the alternating
>>>> > gray/white background of current Scaladoc to the all-white with
>>>> > separator lines you're suggesting.
>>>> >
>>>> > There are some other issues I'm seeing in ruediger2. For example, on
>>>> > trait Suite:
>>>> >
>>>> > http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html
>>>> >
>>>> > There's extra white space at the top before the first comment line
>>>> > that begins, "A suite of tests. A Suite instance encapsulates..."
>>>> >
>>>> > There's missing white space after lists. Look at the list in the
>>>> > Extensability section down at the bottom for an example. After
>>>> > "expectedTestCount - override this method to count this Suite's...",
>>>> > there's no white space before the start of the next paragraph.
>>>> >
>>>> > I think also the paragraphs are not quite far enough apart to visually
>>>> > separate them.
>>>> >
>>>> > One thing I think we should separate is what would go into 2.9.0 and
>>>> > what would go later. This is very last minute for 2.9.0. I should have
>>>> > gone through and done my second pass looking for remaining issues
>>>> > earlier, but I was very busy. So at this point I think only critical
>>>> > problems should be addressed, and for layout I think just adding a bit
>>>> > of white space here and there is probably all we should try to do for
>>>> > 2.9.0. After that Donna can lead a more careful and thorough redesign
>>>> > of the layout, if need be.
>>>> >
>>>> > In my suggestion I was trying to be minimal so that the change would
>>>> > be low risk and easy enough to go into 2.9.0. I'll make one more pass
>>>> > today using your suggestions (line height of 1.2, and evening out
>>>> > those descriptions, which you pointed out yesterday.) After that I'll
>>>> > stop and I think that will be good enough for 2.9.0 as far as layout
>>>> > goes. The kind of changes your suggesting are more appropriate to
>>>> > consider for post-2.9.0 in my opinion.
>>>> >
>>>> > I will follow up with another email clarifying what Scaladoc bugs I am
>>>> > hoping to see closed for 2.9.0. Several we submitted yesterday are
>>>> > minutia that could wait until later, but there are still a few that
>>>> > result in documentation being dropped and inaccessible to the user,
>>>> > which I think we should try and fix for 2.9.0.
>>>> >
>>>> > Thanks.
>>>> >
>>>> > Bill
>>>> >
>>>> >
>>>> > On Sun, Mar 20, 2011 at 11:14 AM, Rüdiger Keller
>>>> > <ruediger.keller@googlemail.com> wrote:
>>>> >> Ok, I will do so.
>>>> >>
>>>> >> I have again made some changes. I think I'm quite happy with the
>>>> >> results now. Again, the files are attached.
>>>> >>
>>>> >> Regards,
>>>> >> Rüdiger
>>>> >>
>>>> >>
>>>> >> 2011/3/20 Donna Malayeri <lindydonna@gmail.com>:
>>>> >>> Yes, please do create tickets (assuming non-duplicates). Thanks for
>>>> >>> your work and the explanations!  I will set up a site with both versions for
>>>> >>> comparison, probably on Monday or Tuesday.
>>>> >>>
>>>> >>> thanks,
>>>> >>> Donna
>>>> >>>
>>>> >>> On Mar 20, 2011, at 2:33 PM, Rüdiger Keller wrote:
>>>> >>>
>>>> >>>> Perhaps I should say something about *what* I changed. :-)
>>>> >>>>
>>>> >>>> First, I used the Scaladoc files from the latest 2.10 nightly build
>>>> >>>> as
>>>> >>>> the basis for my changes, with Bill's changes on top. Although I must
>>>> >>>> admit that I reverted some of his changes.
>>>> >>>>
>>>> >>>> The biggest change is the layout of the member lists. No more gray
>>>> >>>> headers, everything is white now, with light gray separators in
>>>> >>>> between. Light gray is a much better choice than my previous black, I
>>>> >>>> think.
>>>> >>>>
>>>> >>>> Then I changed the spacing in many places to be more even / regular
>>>> >>>> and to ensure that things line up properly. Also I added some spacing
>>>> >>>> to emphasize the separation of separate things. Does that sentence
>>>> >>>> make sense? :-)
>>>> >>>>
>>>> >>>> Also, I changed the line height to the default which is something
>>>> >>>> like
>>>> >>>> 1.2. This makes everything much easier to read.
>>>> >>>>
>>>> >>>> I changed the separators at the bottom of the expanded method / type
>>>> >>>> descriptions to be somewhat lighter and I also removed the separating
>>>> >>>> lines in between the parameter descriptions.
>>>> >>>>
>>>> >>>> Last but not least, I changed the line breaking behavior when the
>>>> >>>> window is not wide enough to display a signature in a single line.
>>>> >>>> Just compare it with the original version, you will notice the
>>>> >>>> improvement.
>>>> >>>>
>>>> >>>> There might be some other minor things, I forgot.
>>>> >>>>
>>>> >>>>
>>>> >>>> I wanted to add that I would like the colons for defining the types
>>>> >>>> not to have leading white space, just as Randall noted before. But I
>>>> >>>> cannot change that with the CSS, because the HTML files generated
>>>> >>>> contain white space (and even line breaks) before the colons.
>>>> >>>>
>>>> >>>> Another thing I thought had been fixed already, but is not: if I
>>>> >>>> click
>>>> >>>> "display packages only" in the left panel, the packages collapse as
>>>> >>>> expected, but the "hide" links next to the package names do not
>>>> >>>> change
>>>> >>>> into "show" links. IMHO this is clearly a bug and should be fixed.
>>>> >>>>
>>>> >>>> Should I create tickets for this? Although I think there already
>>>> >>>> exists one for the latter.
>>>> >>>>
>>>> >>>> Regards,
>>>> >>>> Rüdiger
>>>> >>>>
>>>> >>>>
>>>> >>>>
>>>> >>>> 2011/3/20 Rüdiger Keller <ruediger.keller@googlemail.com>:
>>>> >>>>> Ok, I'm done with the first iteration. I just attached the new
>>>> >>>>> template.css and index.css. I hope that is not too inconvenient.
>>>> >>>>>
>>>> >>>>> If there is demand for it, I can put my modified version of the
>>>> >>>>> Scaladocs on my own web space, but I would prefer not to. I only
>>>> >>>>> have
>>>> >>>>> 20MB and the Scaladocs are 200MB in size. I hope Donna or Bill can
>>>> >>>>> set
>>>> >>>>> up comparison sites again.
>>>> >>>>>
>>>> >>>>> Also, I used Firefox and Firebug to create my changes, but a (very)
>>>> >>>>> quick check with IE8 and Chrome showed no problems.
>>>> >>>>>
>>>> >>>>> Ok, I'm waiting for feedback then.
>>>> >>>>>
>>>> >>>>> Regards,
>>>> >>>>> Rüdiger
>>>> >>>>>
>>>> >>>>>
>>>> >>>>> 2011/3/20 Ruediger Keller <ruediger.keller@rk42.de>:
>>>> >>>>>> Ok. I'm working on it right now and it's coming along nicely, I
>>>> >>>>>> think.
>>>> >>>>>>
>>>> >>>>>>
>>>> >>>>>> 2011/3/20 Donna Malayeri <lindydonna@gmail.com>:
>>>> >>>>>>>> I think my suggestion can be improved further, but first I want
>>>> >>>>>>>> to
>>>> >>>>>>>> know it it's worth the time. If everyone is in favor of the old
>>>> >>>>>>>> style
>>>> >>>>>>>> with alternating grey and white, I will not pursue this approach.
>>>> >>>>>>>
>>>> >>>>>>> Personally, I like the new style (no alternating black and grey),
>>>> >>>>>>> but I might be in a minority here. If we come up with some concrete
>>>> >>>>>>> re-designs, I can make a poll so people can vote on their preferred design.
>>>> >>>>>>>
>>>> >>>>>>> Donna
>>>> >>>>>>
>>>> >>>>>
>>>> >>>
>>>> >>>
>>>> >>
>>>> >
>>>> >
>>>> >
>>>> > --
>>>> > Bill Venners
>>>> > Artima, Inc.
>>>> > http://www.artima.com
>>>> >
>>>
>>>
>>>
>>> --
>>> ----------------------------------------------
>>> Martin Odersky
>>> Prof., EPFL and CEO, Scala Solutions
>>> PSED, 1015 Lausanne, Switzerland
>>>
>>>
>>>
>>
>>
>>
>> --
>> Bill Venners
>> Artima, Inc.
>> http://www.artima.com
>>
>



--
Bill Venners
Artima, Inc.
http://www.artima.com

--
Viktor Klang,
Code Connoisseur
Work:   Scalable Solutions
Code:   github.com/viktorklang
Follow: twitter.com/viktorklang
Read:   klangism.tumblr.com

On Mon, Mar 21, 2011 at 10:44 AM, Bill Venners wrote:
> http://www.artima.com/sdp/suggestion2/org/scalatest/Suite.html#errorHand...

Not sure, if that means anything, but in your examples something seems
to be broken with the font on Google Chrome (Ubuntu 10.10): after some
lines all text will be bold.

Hi Johannes,

Yes, that's annoying, isn't it? It is a manifestation of this Scaladoc bug:

https://lampsvn.epfl.ch/trac/scala/ticket/4366

Bill

On Mon, Mar 21, 2011 at 12:21 PM, Johannes Rudolph
wrote:
> On Mon, Mar 21, 2011 at 10:44 AM, Bill Venners wrote:
>> http://www.artima.com/sdp/suggestion2/org/scalatest/Suite.html#errorHand...
>
> Not sure, if that means anything, but in your examples something seems
> to be broken with the font on Google Chrome (Ubuntu 10.10): after some
> lines all text will be bold.
>
> --
> Johannes
>
> -----------------------------------------------
> Johannes Rudolph
> http://virtual-void.net
>

Hi Viktor,

FF4 on which platform? I only had time to check this one on FF3 and
Safari on the Mac. Donna, I assume, will be doing a more thorough,
careful job of making changes to the css.

Bill

On Mon, Mar 21, 2011 at 11:37 AM, √iktor Klang wrote:
>
>
> On Mon, Mar 21, 2011 at 6:59 PM, Bill Venners wrote:
>>
>> Hi Ruediger,
>>
>> On Mon, Mar 21, 2011 at 3:01 AM, Rüdiger Keller
>> wrote:
>> > If it is decided that the all white version should go into 2.9, I can
>> > provide a minimal change set for that, as you suggest based
>> > onsuggestion2. That would be:
>> >
>> > Remove the "background-color" style from the ".signature" rule and add
>> > a style "border-bottom: 1px solid lightgray;" to the "div.members > ol
>> >> li" rule.
>> >
>> That sounded easy so I made those mods off of suggestion2 and put an
>> example here:
>>
>> http://www.artima.com/sdp/suggestion3/
>>
>
> Collapse works when clicking on stuff, but expand is broken, on FF4
>
>>
>> I quickly glanced at making the class/trait/object name blue, but it
>> didn't look obvious and I didn't want to tweak too much. Others can
>> work on making it more obvious you can click up top.
>>
>> So suggestion3 has the extra white space I think would help
>> readability at least of ScalaTest's docs, plus Ruediger's layout of
>> the members that gets rid of the alternating gray/white bars. Css file
>> is:
>>
>> http://www.artima.com/sdp/suggestion3/lib/template.css
>>
>> Diff from original, which I grabbed about three days ago now from
>> 2.9.0-SNAPSHOT, is:
>>
>> [sites@artima01 sdp]$ diff original/lib/template.css
>> suggestion3/lib/template.css
>> 20c20
>> <   line-height: 1;
>> ---
>> >   line-height: 1.2;
>> 157a158
>> >   border-bottom: 1px solid lightgray;
>> 172c173
>> <   padding: 3px;
>> ---
>> >   padding: 2px;
>> 177d177
>> <   background-color: #e5e5e5;
>> 234,235c234,235
>> <       margin-bottom: 0.4em;
>> <       margin-top: 0.4em;
>> ---
>> >       margin-bottom: 0.9em;
>> >       margin-top: 0.9em;
>> 362c362
>> <   padding: 0;
>> ---
>> >   padding: 2px;
>> 368a369,370
>> >   margin-top: 2px;
>> >   margin-bottom: 2px;
>> 415a418,421
>> > div.fullcomment dl.paramcmts dd.cmt p {
>> >   margin-top: 2px;
>> >   margin-bottom: 2px;
>> > }
>>
>> I haven't tried this in as many browsers as my previous suggestions.
>> Should be tried in a lot of them.
>>
>> Bill
>>
>>
>> > But perhaps we should wait until after 2.9 with such bigger changes.
>> >
>> > Also, I like your idea of using blue consistently for clickable
>> > things. Perhaps also adding underlining, as that is currently already
>> > used in many places in the current scaladocs. I will explorer some
>> > more on this when I have some time for it.
>> >
>> > Regards,
>> > Rüdiger
>> >
>> >
>> > 2011/3/21 Bill Venners :
>> >> Hi Martin, Ruediger, Donna,
>> >>
>> >> I just realized that this non-obvious place to click problem exists at
>> >> the top. I just figured out now that you can click on the name of a
>> >> trait/class/object to get more information about it. I didn't know I
>> >> could do that. The ones below in ruediger2 look click-on-able to me
>> >> because the member names are blue. But I'm not sure how obvious that
>> >> would be if I didn't already know that I could click there.
>> >>
>> >> Anyway, if you're going to move away from the alternating gray
>> >> background for 2.9.0, I'd request that you fork suggestion2 and just
>> >> make that one change. I.e., start with this file:
>> >>
>> >> http://www.artima.com/sdp/suggestion2/lib/template.css
>> >>
>> >> A couple things got broken in ruediger2, which I mentioned on an
>> >> earlier previous email. To see my concern, look at the difference
>> >> between the last two sections here on ruediger2:
>> >>
>> >>
>> >> http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html#errorHandling
>> >>
>> >> versus suggestion2:
>> >>
>> >>
>> >> http://www.artima.com/sdp/suggestion2/org/scalatest/Suite.html#errorHand...
>> >>
>> >> My main hope for a css tweak for 2.9.0 is that we can add a bit more
>> >> space between paragraphs and lines. ScalaTest docs are hard to read
>> >> without that whitespace.
>> >>
>> >> Perhaps, Ruediger, you could start with the above suggestion2 css file
>> >> and just add only whatever you did to replace the alternating gray and
>> >> white background with the thin gray separator lines?
>> >>
>> >> One other suggestion I have now that I know I can click on the top
>> >> line is to make the name of the trait/class/object the same blue color
>> >> as the member names. Blue still tends to mean "I can click here" to
>> >> people. That way there's a consistent signal about clicking to get
>> >> more info.
>> >>
>> >> I'd stop there as a base line. Then if you want to try a triangle go
>> >> for it, but things like that can send you down a rabbit hole. For
>> >> 2.9.0 it seems prudent to just do some very minimalist improvements at
>> >> this late point, and then a more thorough, careful makeover can be
>> >> done for a future release.
>> >>
>> >> Thanks for your attention to this.
>> >>
>> >> Bill
>> >>
>> >> 2011/3/20 martin odersky :
>> >>> I like Ruediger's layout. I think the grey / white altrenations
>> >>> detract from
>> >>> what's most important: the member names, so that's why I like it to be
>> >>> all
>> >>> white with thin separation lines. Agreed though that there should be
>> >>> an
>> >>> element that identifies open vs short comments -- maybe the
>> >>> rihg/downwards
>> >>> pointing triangle of standard outline views?
>> >>>
>> >>> Cheers
>> >>>
>> >>>  -- Martin
>> >>>
>> >>> On Mon, Mar 21, 2011 at 1:54 AM, Rüdiger Keller
>> >>> wrote:
>> >>>>
>> >>>> Hi Bill,
>> >>>> Hi list,
>> >>>>
>> >>>> I did not mean to force any changes into 2.9, I just hijacked the
>> >>>> "wrong" thread. Sorry for that.
>> >>>>
>> >>>> I wanted to start a constructive discussion by offering something for
>> >>>> trying, that I personally like better than the current scaladocs. And
>> >>>> it seems I reached my goal even though most of my changes don't seem
>> >>>> to be well received.
>> >>>>
>> >>>> Bill, I will address your individual concerns later tomorrow.
>> >>>>
>> >>>> Now I need to sleep.
>> >>>>
>> >>>> Regards,
>> >>>> Rüdiger
>> >>>>
>> >>>>
>> >>>> 2011/3/21 Bill Venners :
>> >>>> > Hi Ruediger,
>> >>>> >
>> >>>> > I generated Scaladoc for the ScalaTest trunk with the latest
>> >>>> > 2.9.0-SNAPSHOT, then put your three .css files in there. I then
>> >>>> > deployed it here:
>> >>>> >
>> >>>> > http://www.artima.com/sdp/ruediger2/
>> >>>> >
>> >>>> > Comparing this to my suggestion:
>> >>>> >
>> >>>> > http://www.artima.com/sdp/suggestion/
>> >>>> >
>> >>>> > I think your line height of 1.2 might be an improvement, but I
>> >>>> > could
>> >>>> > live with either for 2.9.0. I think I actually prefer the
>> >>>> > alternating
>> >>>> > gray/white background of current Scaladoc to the all-white with
>> >>>> > separator lines you're suggesting.
>> >>>> >
>> >>>> > There are some other issues I'm seeing in ruediger2. For example,
>> >>>> > on
>> >>>> > trait Suite:
>> >>>> >
>> >>>> > http://www.artima.com/sdp/ruediger2/org/scalatest/Suite.html
>> >>>> >
>> >>>> > There's extra white space at the top before the first comment line
>> >>>> > that begins, "A suite of tests. A Suite instance encapsulates..."
>> >>>> >
>> >>>> > There's missing white space after lists. Look at the list in the
>> >>>> > Extensability section down at the bottom for an example. After
>> >>>> > "expectedTestCount - override this method to count this
>> >>>> > Suite's...",
>> >>>> > there's no white space before the start of the next paragraph.
>> >>>> >
>> >>>> > I think also the paragraphs are not quite far enough apart to
>> >>>> > visually
>> >>>> > separate them.
>> >>>> >
>> >>>> > One thing I think we should separate is what would go into 2.9.0
>> >>>> > and
>> >>>> > what would go later. This is very last minute for 2.9.0. I should
>> >>>> > have
>> >>>> > gone through and done my second pass looking for remaining issues
>> >>>> > earlier, but I was very busy. So at this point I think only
>> >>>> > critical
>> >>>> > problems should be addressed, and for layout I think just adding a
>> >>>> > bit
>> >>>> > of white space here and there is probably all we should try to do
>> >>>> > for
>> >>>> > 2.9.0. After that Donna can lead a more careful and thorough
>> >>>> > redesign
>> >>>> > of the layout, if need be.
>> >>>> >
>> >>>> > In my suggestion I was trying to be minimal so that the change
>> >>>> > would
>> >>>> > be low risk and easy enough to go into 2.9.0. I'll make one more
>> >>>> > pass
>> >>>> > today using your suggestions (line height of 1.2, and evening out
>> >>>> > those descriptions, which you pointed out yesterday.) After that
>> >>>> > I'll
>> >>>> > stop and I think that will be good enough for 2.9.0 as far as
>> >>>> > layout
>> >>>> > goes. The kind of changes your suggesting are more appropriate to
>> >>>> > consider for post-2.9.0 in my opinion.
>> >>>> >
>> >>>> > I will follow up with another email clarifying what Scaladoc bugs I
>> >>>> > am
>> >>>> > hoping to see closed for 2.9.0. Several we submitted yesterday are
>> >>>> > minutia that could wait until later, but there are still a few that
>> >>>> > result in documentation being dropped and inaccessible to the user,
>> >>>> > which I think we should try and fix for 2.9.0.
>> >>>> >
>> >>>> > Thanks.
>> >>>> >
>> >>>> > Bill
>> >>>> >
>> >>>> >
>> >>>> > On Sun, Mar 20, 2011 at 11:14 AM, Rüdiger Keller
>> >>>> > wrote:
>> >>>> >> Ok, I will do so.
>> >>>> >>
>> >>>> >> I have again made some changes. I think I'm quite happy with the
>> >>>> >> results now. Again, the files are attached.
>> >>>> >>
>> >>>> >> Regards,
>> >>>> >> Rüdiger
>> >>>> >>
>> >>>> >>
>> >>>> >> 2011/3/20 Donna Malayeri :
>> >>>> >>> Yes, please do create tickets (assuming non-duplicates). Thanks
>> >>>> >>> for
>> >>>> >>> your work and the explanations!  I will set up a site with both
>> >>>> >>> versions for
>> >>>> >>> comparison, probably on Monday or Tuesday.
>> >>>> >>>
>> >>>> >>> thanks,
>> >>>> >>> Donna
>> >>>> >>>
>> >>>> >>> On Mar 20, 2011, at 2:33 PM, Rüdiger Keller wrote:
>> >>>> >>>
>> >>>> >>>> Perhaps I should say something about *what* I changed. :-)
>> >>>> >>>>
>> >>>> >>>> First, I used the Scaladoc files from the latest 2.10 nightly
>> >>>> >>>> build
>> >>>> >>>> as
>> >>>> >>>> the basis for my changes, with Bill's changes on top. Although I
>> >>>> >>>> must
>> >>>> >>>> admit that I reverted some of his changes.
>> >>>> >>>>
>> >>>> >>>> The biggest change is the layout of the member lists. No more
>> >>>> >>>> gray
>> >>>> >>>> headers, everything is white now, with light gray separators in
>> >>>> >>>> between. Light gray is a much better choice than my previous
>> >>>> >>>> black, I
>> >>>> >>>> think.
>> >>>> >>>>
>> >>>> >>>> Then I changed the spacing in many places to be more even /
>> >>>> >>>> regular
>> >>>> >>>> and to ensure that things line up properly. Also I added some
>> >>>> >>>> spacing
>> >>>> >>>> to emphasize the separation of separate things. Does that
>> >>>> >>>> sentence
>> >>>> >>>> make sense? :-)
>> >>>> >>>>
>> >>>> >>>> Also, I changed the line height to the default which is
>> >>>> >>>> something
>> >>>> >>>> like
>> >>>> >>>> 1.2. This makes everything much easier to read.
>> >>>> >>>>
>> >>>> >>>> I changed the separators at the bottom of the expanded method /
>> >>>> >>>> type
>> >>>> >>>> descriptions to be somewhat lighter and I also removed the
>> >>>> >>>> separating
>> >>>> >>>> lines in between the parameter descriptions.
>> >>>> >>>>
>> >>>> >>>> Last but not least, I changed the line breaking behavior when
>> >>>> >>>> the
>> >>>> >>>> window is not wide enough to display a signature in a single
>> >>>> >>>> line.
>> >>>> >>>> Just compare it with the original version, you will notice the
>> >>>> >>>> improvement.
>> >>>> >>>>
>> >>>> >>>> There might be some other minor things, I forgot.
>> >>>> >>>>
>> >>>> >>>>
>> >>>> >>>> I wanted to add that I would like the colons for defining the
>> >>>> >>>> types
>> >>>> >>>> not to have leading white space, just as Randall noted before.
>> >>>> >>>> But I
>> >>>> >>>> cannot change that with the CSS, because the HTML files
>> >>>> >>>> generated
>> >>>> >>>> contain white space (and even line breaks) before the colons.
>> >>>> >>>>
>> >>>> >>>> Another thing I thought had been fixed already, but is not: if I
>> >>>> >>>> click
>> >>>> >>>> "display packages only" in the left panel, the packages collapse
>> >>>> >>>> as
>> >>>> >>>> expected, but the "hide" links next to the package names do not
>> >>>> >>>> change
>> >>>> >>>> into "show" links. IMHO this is clearly a bug and should be
>> >>>> >>>> fixed.
>> >>>> >>>>
>> >>>> >>>> Should I create tickets for this? Although I think there already
>> >>>> >>>> exists one for the latter.
>> >>>> >>>>
>> >>>> >>>> Regards,
>> >>>> >>>> Rüdiger
>> >>>> >>>>
>> >>>> >>>>
>> >>>> >>>>
>> >>>> >>>> 2011/3/20 Rüdiger Keller :
>> >>>> >>>>> Ok, I'm done with the first iteration. I just attached the new
>> >>>> >>>>> template.css and index.css. I hope that is not too
>> >>>> >>>>> inconvenient.
>> >>>> >>>>>
>> >>>> >>>>> If there is demand for it, I can put my modified version of the
>> >>>> >>>>> Scaladocs on my own web space, but I would prefer not to. I
>> >>>> >>>>> only
>> >>>> >>>>> have
>> >>>> >>>>> 20MB and the Scaladocs are 200MB in size. I hope Donna or Bill
>> >>>> >>>>> can
>> >>>> >>>>> set
>> >>>> >>>>> up comparison sites again.
>> >>>> >>>>>
>> >>>> >>>>> Also, I used Firefox and Firebug to create my changes, but a
>> >>>> >>>>> (very)
>> >>>> >>>>> quick check with IE8 and Chrome showed no problems.
>> >>>> >>>>>
>> >>>> >>>>> Ok, I'm waiting for feedback then.
>> >>>> >>>>>
>> >>>> >>>>> Regards,
>> >>>> >>>>> Rüdiger
>> >>>> >>>>>
>> >>>> >>>>>
>> >>>> >>>>> 2011/3/20 Ruediger Keller :
>> >>>> >>>>>> Ok. I'm working on it right now and it's coming along nicely,
>> >>>> >>>>>> I
>> >>>> >>>>>> think.
>> >>>> >>>>>>
>> >>>> >>>>>>
>> >>>> >>>>>> 2011/3/20 Donna Malayeri :
>> >>>> >>>>>>>> I think my suggestion can be improved further, but first I
>> >>>> >>>>>>>> want
>> >>>> >>>>>>>> to
>> >>>> >>>>>>>> know it it's worth the time. If everyone is in favor of the
>> >>>> >>>>>>>> old
>> >>>> >>>>>>>> style
>> >>>> >>>>>>>> with alternating grey and white, I will not pursue this
>> >>>> >>>>>>>> approach.
>> >>>> >>>>>>>
>> >>>> >>>>>>> Personally, I like the new style (no alternating black and
>> >>>> >>>>>>> grey),
>> >>>> >>>>>>> but I might be in a minority here. If we come up with some
>> >>>> >>>>>>> concrete
>> >>>> >>>>>>> re-designs, I can make a poll so people can vote on their
>> >>>> >>>>>>> preferred design.
>> >>>> >>>>>>>
>> >>>> >>>>>>> Donna
>> >>>> >>>>>>
>> >>>> >>>>>
>> >>>> >>>
>> >>>> >>>
>> >>>> >>
>> >>>> >
>> >>>> >
>> >>>> >
>> >>>> > --
>> >>>> > Bill Venners
>> >>>> > Artima, Inc.
>> >>>> > http://www.artima.com
>> >>>> >
>> >>>
>> >>>
>> >>>
>> >>> --
>> >>> ----------------------------------------------
>> >>> Martin Odersky
>> >>> Prof., EPFL and CEO, Scala Solutions
>> >>> PSED, 1015 Lausanne, Switzerland
>> >>>
>> >>>
>> >>>
>> >>
>> >>
>> >>
>> >> --
>> >> Bill Venners
>> >> Artima, Inc.
>> >> http://www.artima.com
>> >>
>> >
>>
>>
>>
>> --
>> Bill Venners
>> Artima, Inc.
>> http://www.artima.com
>
>
>
> --
> Viktor Klang,
> Code Connoisseur
> Work:   Scalable Solutions
> Code:   github.com/viktorklang
> Follow: twitter.com/viktorklang
> Read:   klangism.tumblr.com
>
>

On Mon, Mar 21, 2011 at 9:30 PM, Donna Malayeri <lindydonna@gmail.com> wrote:

> Hi Viktor,
>
> FF4 on which platform? I only had time to check this one on FF3 and
> Safari on the Mac. Donna, I assume, will be doing a more thorough,
> careful job of making changes to the css.
>
> Bill

Yes, I'll check FF3, FF4, Chrome, and Safari on the Mac, and FF and IE on Windows. I don't have a linux box, however.

Oh, sorry, on OS X 10.6

I tried to reproduce the problem a second ago and couldn't, so it might be that somewhere a javascript breaks under some conditions. Haven't got firebug installed since it for some reason didn't work with FF4, otherwise it'd be easier to debug if I get it to manifest again.
 

Viktor: does the expand functionality work on other platforms?  Can you try it with the other CSS samples that Bill has uploaded?

thanks,
Donna

--
Viktor Klang,
Code Connoisseur
Work:   Scalable Solutions
Code:   github.com/viktorklang
Follow: twitter.com/viktorklang
Read:   klangism.tumblr.com

Hi Viktor,

I'm pretty sure I've had similar problems with 2.8 Scaladoc, probably
on Safari on the Mac, where the open and close would stop working
after a while. What I had to do was close the browser window and
reopen it, and it would work again. That happened maybe two or three
times to me since 2.8 came out, so it was pretty rare.

Bill

On Mon, Mar 21, 2011 at 1:37 PM, √iktor Klang wrote:
>
>
> On Mon, Mar 21, 2011 at 9:30 PM, Donna Malayeri
> wrote:
>>
>> > Hi Viktor,
>> >
>> > FF4 on which platform? I only had time to check this one on FF3 and
>> > Safari on the Mac. Donna, I assume, will be doing a more thorough,
>> > careful job of making changes to the css.
>> >
>> > Bill
>>
>> Yes, I'll check FF3, FF4, Chrome, and Safari on the Mac, and FF and IE on
>> Windows. I don't have a linux box, however.
>
> Oh, sorry, on OS X 10.6
>
> I tried to reproduce the problem a second ago and couldn't, so it might be
> that somewhere a javascript breaks under some conditions. Haven't got
> firebug installed since it for some reason didn't work with FF4, otherwise
> it'd be easier to debug if I get it to manifest again.
>
>>
>> Viktor: does the expand functionality work on other platforms?  Can you
>> try it with the other CSS samples that Bill has uploaded?
>>
>> thanks,
>> Donna
>
>
> --
> Viktor Klang,
> Code Connoisseur
> Work:   Scalable Solutions
> Code:   github.com/viktorklang
> Follow: twitter.com/viktorklang
> Read:   klangism.tumblr.com
>
>

> Hi Viktor,
>
> FF4 on which platform? I only had time to check this one on FF3 and
> Safari on the Mac. Donna, I assume, will be doing a more thorough,
> careful job of making changes to the css.
>
> Bill

Yes, I'll check FF3, FF4, Chrome, and Safari on the Mac, and FF and IE on Windows. I don't have a linux box, however.

Viktor: does the expand functionality work on other platforms? Can you try it with the other CSS samples that Bill has uploaded?

thanks,
Donna

Hi Bill,

On Mon, Mar 21, 2011 at 9:41 PM, Bill Venners <bill@artima.com> wrote:

Hi Viktor,

I'm pretty sure I've had similar problems with 2.8 Scaladoc, probably
on Safari on the Mac, where the open and close would stop working
after a while. What I had to do was close the browser window and
reopen it, and it would work again. That happened maybe two or three
times to me since 2.8 came out, so it was pretty rare.

Alright, that doesn't sound like something to waste time debugging.

Cheers,
 

Bill

On Mon, Mar 21, 2011 at 1:37 PM, √iktor Klang <viktor.klang@gmail.com> wrote:
>
>
> On Mon, Mar 21, 2011 at 9:30 PM, Donna Malayeri <lindydonna@gmail.com>
> wrote:
>>
>> > Hi Viktor,
>> >
>> > FF4 on which platform? I only had time to check this one on FF3 and
>> > Safari on the Mac. Donna, I assume, will be doing a more thorough,
>> > careful job of making changes to the css.
>> >
>> > Bill
>>
>> Yes, I'll check FF3, FF4, Chrome, and Safari on the Mac, and FF and IE on
>> Windows. I don't have a linux box, however.
>
> Oh, sorry, on OS X 10.6
>
> I tried to reproduce the problem a second ago and couldn't, so it might be
> that somewhere a javascript breaks under some conditions. Haven't got
> firebug installed since it for some reason didn't work with FF4, otherwise
> it'd be easier to debug if I get it to manifest again.
>
>>
>> Viktor: does the expand functionality work on other platforms?  Can you
>> try it with the other CSS samples that Bill has uploaded?
>>
>> thanks,
>> Donna
>
>
> --
> Viktor Klang,
> Code Connoisseur
> Work:   Scalable Solutions
> Code:   github.com/viktorklang
> Follow: twitter.com/viktorklang
> Read:   klangism.tumblr.com
>
>



--
Bill Venners
Artima, Inc.
http://www.artima.com

--
Viktor Klang,
Code Connoisseur
Work:   Scalable Solutions
Code:   github.com/viktorklang
Follow: twitter.com/viktorklang
Read:   klangism.tumblr.com

Hi Viktor,

Actually I may have just realized what you hit. There are two bugs I
reported that may be two different instances of the same class of bug.
One causes closing strong tags to be dropped (4366), and the other
closing ie tags (4358). These both cause everything after the problem
to be either bold or italics. It also causes open/closing to not work
thereafter on Firefox. So if you go to Suite, for example, the strong
problem happens on the groups method. After that things are not only
bold, but don't open and close correctly on Firefox:

http://www.artima.com/sdp/suggestion3/org/scalatest/Suite.html

If you go to EasyMockSugar, which has the ie problem, then things
don't open and close correctly:

http://www.artima.com/sdp/suggestion3/org/scalatest/Suite.html

The call method has the ie problem and everything after that doesn't
open/close correctly on Firefox. If that's what you saw then it should
get fixed when 4358 and 4366 get fixed.

Thanks.

Bill

On Mon, Mar 21, 2011 at 1:50 PM, √iktor Klang wrote:
> Hi Bill,
>
> On Mon, Mar 21, 2011 at 9:41 PM, Bill Venners wrote:
>>
>> Hi Viktor,
>>
>> I'm pretty sure I've had similar problems with 2.8 Scaladoc, probably
>> on Safari on the Mac, where the open and close would stop working
>> after a while. What I had to do was close the browser window and
>> reopen it, and it would work again. That happened maybe two or three
>> times to me since 2.8 came out, so it was pretty rare.
>
> Alright, that doesn't sound like something to waste time debugging.
>
> Cheers,
>
>>
>> Bill
>>
>> On Mon, Mar 21, 2011 at 1:37 PM, √iktor Klang
>> wrote:
>> >
>> >
>> > On Mon, Mar 21, 2011 at 9:30 PM, Donna Malayeri
>> > wrote:
>> >>
>> >> > Hi Viktor,
>> >> >
>> >> > FF4 on which platform? I only had time to check this one on FF3 and
>> >> > Safari on the Mac. Donna, I assume, will be doing a more thorough,
>> >> > careful job of making changes to the css.
>> >> >
>> >> > Bill
>> >>
>> >> Yes, I'll check FF3, FF4, Chrome, and Safari on the Mac, and FF and IE
>> >> on
>> >> Windows. I don't have a linux box, however.
>> >
>> > Oh, sorry, on OS X 10.6
>> >
>> > I tried to reproduce the problem a second ago and couldn't, so it might
>> > be
>> > that somewhere a javascript breaks under some conditions. Haven't got
>> > firebug installed since it for some reason didn't work with FF4,
>> > otherwise
>> > it'd be easier to debug if I get it to manifest again.
>> >
>> >>
>> >> Viktor: does the expand functionality work on other platforms?  Can you
>> >> try it with the other CSS samples that Bill has uploaded?
>> >>
>> >> thanks,
>> >> Donna
>> >
>> >
>> > --
>> > Viktor Klang,
>> > Code Connoisseur
>> > Work:   Scalable Solutions
>> > Code:   github.com/viktorklang
>> > Follow: twitter.com/viktorklang
>> > Read:   klangism.tumblr.com
>> >
>> >
>>
>>
>>
>> --
>> Bill Venners
>> Artima, Inc.
>> http://www.artima.com
>
>
>
> --
> Viktor Klang,
> Code Connoisseur
> Work:   Scalable Solutions
> Code:   github.com/viktorklang
> Follow: twitter.com/viktorklang
> Read:   klangism.tumblr.com
>
>

Hello,

I updated my style with somewhat bigger spacing between paragraphs and
fixed the bug with no spacing after list (I hope). And some other
minor things.

Also, I made an experiment and changed all names to have a somewhat
bigger font size. What do you think?

Bill, is it possible to download the ScalaTest Scaladocs that you put
up for testing? That would make my life easier testing how my changes
look for the ScalaTest Docs. I tried the 1.3 release but that is not
compatible with the current trunks CSS files.

Regards,
Rüdiger

2011/3/21 Bill Venners :
> Hi Viktor,
>
> Actually I may have just realized what you hit. There are two bugs I
> reported that may be two different instances of the same class of bug.
> One causes closing strong tags to be dropped (4366), and the other
> closing ie tags (4358). These both cause everything after the problem
> to be either bold or italics. It also causes open/closing to not work
> thereafter on Firefox. So if you go to Suite, for example, the strong
> problem happens on the groups method. After that things are not only
> bold, but don't open and close correctly on Firefox:
>
> http://www.artima.com/sdp/suggestion3/org/scalatest/Suite.html
>
> If you go to EasyMockSugar, which has the ie problem, then things
> don't open and close correctly:
>
> http://www.artima.com/sdp/suggestion3/org/scalatest/Suite.html
>
> The call method has the ie problem and everything after that doesn't
> open/close correctly on Firefox. If that's what you saw then it should
> get fixed when 4358 and 4366 get fixed.
>
> Thanks.
>
> Bill
>
> On Mon, Mar 21, 2011 at 1:50 PM, √iktor Klang wrote:
>> Hi Bill,
>>
>> On Mon, Mar 21, 2011 at 9:41 PM, Bill Venners wrote:
>>>
>>> Hi Viktor,
>>>
>>> I'm pretty sure I've had similar problems with 2.8 Scaladoc, probably
>>> on Safari on the Mac, where the open and close would stop working
>>> after a while. What I had to do was close the browser window and
>>> reopen it, and it would work again. That happened maybe two or three
>>> times to me since 2.8 came out, so it was pretty rare.
>>
>> Alright, that doesn't sound like something to waste time debugging.
>>
>> Cheers,
>>
>>>
>>> Bill
>>>
>>> On Mon, Mar 21, 2011 at 1:37 PM, √iktor Klang
>>> wrote:
>>> >
>>> >
>>> > On Mon, Mar 21, 2011 at 9:30 PM, Donna Malayeri
>>> > wrote:
>>> >>
>>> >> > Hi Viktor,
>>> >> >
>>> >> > FF4 on which platform? I only had time to check this one on FF3 and
>>> >> > Safari on the Mac. Donna, I assume, will be doing a more thorough,
>>> >> > careful job of making changes to the css.
>>> >> >
>>> >> > Bill
>>> >>
>>> >> Yes, I'll check FF3, FF4, Chrome, and Safari on the Mac, and FF and IE
>>> >> on
>>> >> Windows. I don't have a linux box, however.
>>> >
>>> > Oh, sorry, on OS X 10.6
>>> >
>>> > I tried to reproduce the problem a second ago and couldn't, so it might
>>> > be
>>> > that somewhere a javascript breaks under some conditions. Haven't got
>>> > firebug installed since it for some reason didn't work with FF4,
>>> > otherwise
>>> > it'd be easier to debug if I get it to manifest again.
>>> >
>>> >>
>>> >> Viktor: does the expand functionality work on other platforms?  Can you
>>> >> try it with the other CSS samples that Bill has uploaded?
>>> >>
>>> >> thanks,
>>> >> Donna
>>> >
>>> >
>>> > --
>>> > Viktor Klang,
>>> > Code Connoisseur
>>> > Work:   Scalable Solutions
>>> > Code:   github.com/viktorklang
>>> > Follow: twitter.com/viktorklang
>>> > Read:   klangism.tumblr.com
>>> >
>>> >
>>>
>>>
>>>
>>> --
>>> Bill Venners
>>> Artima, Inc.
>>> http://www.artima.com
>>
>>
>>
>> --
>> Viktor Klang,
>> Code Connoisseur
>> Work:   Scalable Solutions
>> Code:   github.com/viktorklang
>> Follow: twitter.com/viktorklang
>> Read:   klangism.tumblr.com
>>
>>
>
>
>
> --
> Bill Venners
> Artima, Inc.
> http://www.artima.com
>

Hi Ruediger,

You can use this branch:

https://scalatest.googlecode.com/svn/branches/scaladocprobs

It grabs 2.9.0-SNAPSHOT. The tests were not compiling as of a couple
days ago, hitting a 2.9 compiler bug. That may be fixed now. But you
don't need them. You need may need more memory to build the docs. I
do:

source ./addmem.sh
ant doc

To build the docs. the addmem script increased a mem size used by ant.

Bill

On Mon, Mar 21, 2011 at 4:04 PM, Rüdiger Keller
wrote:
> Hello,
>
> I updated my style with somewhat bigger spacing between paragraphs and
> fixed the bug with no spacing after list (I hope). And some other
> minor things.
>
> Also, I made an experiment and changed all names to have a somewhat
> bigger font size. What do you think?
>
> Bill, is it possible to download the ScalaTest Scaladocs that you put
> up for testing? That would make my life easier testing how my changes
> look for the ScalaTest Docs. I tried the 1.3 release but that is not
> compatible with the current trunks CSS files.
>
> Regards,
> Rüdiger
>
>
>
> 2011/3/21 Bill Venners :
>> Hi Viktor,
>>
>> Actually I may have just realized what you hit. There are two bugs I
>> reported that may be two different instances of the same class of bug.
>> One causes closing strong tags to be dropped (4366), and the other
>> closing ie tags (4358). These both cause everything after the problem
>> to be either bold or italics. It also causes open/closing to not work
>> thereafter on Firefox. So if you go to Suite, for example, the strong
>> problem happens on the groups method. After that things are not only
>> bold, but don't open and close correctly on Firefox:
>>
>> http://www.artima.com/sdp/suggestion3/org/scalatest/Suite.html
>>
>> If you go to EasyMockSugar, which has the ie problem, then things
>> don't open and close correctly:
>>
>> http://www.artima.com/sdp/suggestion3/org/scalatest/Suite.html
>>
>> The call method has the ie problem and everything after that doesn't
>> open/close correctly on Firefox. If that's what you saw then it should
>> get fixed when 4358 and 4366 get fixed.
>>
>> Thanks.
>>
>> Bill
>>
>> On Mon, Mar 21, 2011 at 1:50 PM, √iktor Klang wrote:
>>> Hi Bill,
>>>
>>> On Mon, Mar 21, 2011 at 9:41 PM, Bill Venners wrote:
>>>>
>>>> Hi Viktor,
>>>>
>>>> I'm pretty sure I've had similar problems with 2.8 Scaladoc, probably
>>>> on Safari on the Mac, where the open and close would stop working
>>>> after a while. What I had to do was close the browser window and
>>>> reopen it, and it would work again. That happened maybe two or three
>>>> times to me since 2.8 came out, so it was pretty rare.
>>>
>>> Alright, that doesn't sound like something to waste time debugging.
>>>
>>> Cheers,
>>>
>>>>
>>>> Bill
>>>>
>>>> On Mon, Mar 21, 2011 at 1:37 PM, √iktor Klang
>>>> wrote:
>>>> >
>>>> >
>>>> > On Mon, Mar 21, 2011 at 9:30 PM, Donna Malayeri
>>>> > wrote:
>>>> >>
>>>> >> > Hi Viktor,
>>>> >> >
>>>> >> > FF4 on which platform? I only had time to check this one on FF3 and
>>>> >> > Safari on the Mac. Donna, I assume, will be doing a more thorough,
>>>> >> > careful job of making changes to the css.
>>>> >> >
>>>> >> > Bill
>>>> >>
>>>> >> Yes, I'll check FF3, FF4, Chrome, and Safari on the Mac, and FF and IE
>>>> >> on
>>>> >> Windows. I don't have a linux box, however.
>>>> >
>>>> > Oh, sorry, on OS X 10.6
>>>> >
>>>> > I tried to reproduce the problem a second ago and couldn't, so it might
>>>> > be
>>>> > that somewhere a javascript breaks under some conditions. Haven't got
>>>> > firebug installed since it for some reason didn't work with FF4,
>>>> > otherwise
>>>> > it'd be easier to debug if I get it to manifest again.
>>>> >
>>>> >>
>>>> >> Viktor: does the expand functionality work on other platforms?  Can you
>>>> >> try it with the other CSS samples that Bill has uploaded?
>>>> >>
>>>> >> thanks,
>>>> >> Donna
>>>> >
>>>> >
>>>> > --
>>>> > Viktor Klang,
>>>> > Code Connoisseur
>>>> > Work:   Scalable Solutions
>>>> > Code:   github.com/viktorklang
>>>> > Follow: twitter.com/viktorklang
>>>> > Read:   klangism.tumblr.com
>>>> >
>>>> >
>>>>
>>>>
>>>>
>>>> --
>>>> Bill Venners
>>>> Artima, Inc.
>>>> http://www.artima.com
>>>
>>>
>>>
>>> --
>>> Viktor Klang,
>>> Code Connoisseur
>>> Work:   Scalable Solutions
>>> Code:   github.com/viktorklang
>>> Follow: twitter.com/viktorklang
>>> Read:   klangism.tumblr.com
>>>
>>>
>>
>>
>>
>> --
>> Bill Venners
>> Artima, Inc.
>> http://www.artima.com
>>
>

I like the idea of removing the collapsing/expanding for the class
descriptions. It seems superfluous and unnecessary. What do others
think?

Regarding the idea of "a small fade-in/fade-out effect", I don't
really understand how you think this should work/look. Can you
describe it in more detail? What should fade? The mouse cursor?

Regards,
Rüdiger

2011/3/21 Simon Ochsenreither :
> Hi!
>
> Would it be possible to have a small fade-in/fade-out effect when the mouse
> is over something which can be expanded/collapsed?
>
> I think the behavior of the class description where you can click on
> anything and it will expand to show linear super types, known subclasses and
> self types, but have to click on the first sentence to collapse it again is
> very confusing.
>
> Imho I would suggest to remove the whole collapsing/expanding in the class
> description and show these three lines by default the whole complication
> isn't worth these three lines.
>
> Thanks everyone for their great work!
>
> Bye,
>
>
> Simon
>

On Mar 22, 2011, at 10:10 AM, Rüdiger Keller wrote:

> I like the idea of removing the collapsing/expanding for the class
> descriptions. It seems superfluous and unnecessary. What do others
> think?

I agree with this as well--it produces a strange visual effect, and as Bill said, it's not obvious that it's there.

Donna

On Tue, Mar 22, 2011 at 06:53, Donna Malayeri <lindydonna@gmail.com> wrote:

On Mar 22, 2011, at 10:10 AM, Rüdiger Keller wrote:

> I like the idea of removing the collapsing/expanding for the class
> descriptions. It seems superfluous and unnecessary. What do others
> think?

I agree with this as well--it produces a strange visual effect, and as Bill said, it's not obvious that it's there.

The obviousness thing is a concern, but look at http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/scala/collection/Seq.html. When class information is expanded, it pushes the methods of of screen. Worse yet, it looks scary. :-)
So, at the very least I'd keep linearization and known subclasses collapsible.
At any rate, if we figure out how to do a clear indication that methods descriptions are collapsible,  we can probably apply the same principle to the class.

--
Daniel C. Sobral

I travel to the future all the time.

Hi,

I don't think that "pushes the methods of of screen" is a problem.
Depending on the class documentation they may not be visible to begin
with (see http://www.artima.com/sdp/suggestion3/org/scalatest/Suite.html).
Also, IMHO it is fairly obvious that you have to scroll the page to
see everything there is.

But I agree that linearization and known subclasses look somewhat
scary for most of the collection classes. If there was a button / link
("Show linearization and known subclasses") specifically for showing
these, it would be nice, I think. The clickable signatures / comments
don't seem to be ideal. For the class descriptions space is not an
issue, so a separate line with such a link would be a good solution.

For the methods we probably need a more compact solution.

Regards,
Rüdiger

2011/3/22 Daniel Sobral :
> On Tue, Mar 22, 2011 at 06:53, Donna Malayeri wrote:
>>
>> On Mar 22, 2011, at 10:10 AM, Rüdiger Keller wrote:
>>
>> > I like the idea of removing the collapsing/expanding for the class
>> > descriptions. It seems superfluous and unnecessary. What do others
>> > think?
>>
>> I agree with this as well--it produces a strange visual effect, and as
>> Bill said, it's not obvious that it's there.
>>
>
> The obviousness thing is a concern, but look at
> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/....
> When class information is expanded, it pushes the methods of of screen.
> Worse yet, it looks scary. :-)
> So, at the very least I'd keep linearization and known
> subclasses collapsible.
> At any rate, if we figure out how to do a clear indication that methods
> descriptions are collapsible,  we can probably apply the same principle to
> the class.
>
> --
> Daniel C. Sobral
>
> I travel to the future all the time.
>

That's an excellent suggestion: a link for showing the additional information. I can certainly change the generated HTML, but I'm not sure which distribution this will go in. (Some RC between RC1 and final?)

Do you happen to know why it produces such a strange visual effect when the additional information is displayed? I imagine it has to do with JavaScript and CSS.

For methods, I think some sort of triangle icon would be good, but that's a bigger change.

thanks,
Donna

On Mar 22, 2011, at 1:33 PM, Ruediger Keller wrote:

> Hi,
>
> I don't think that "pushes the methods of of screen" is a problem.
> Depending on the class documentation they may not be visible to begin
> with (see http://www.artima.com/sdp/suggestion3/org/scalatest/Suite.html).
> Also, IMHO it is fairly obvious that you have to scroll the page to
> see everything there is.
>
> But I agree that linearization and known subclasses look somewhat
> scary for most of the collection classes. If there was a button / link
> ("Show linearization and known subclasses") specifically for showing
> these, it would be nice, I think. The clickable signatures / comments
> don't seem to be ideal. For the class descriptions space is not an
> issue, so a separate line with such a link would be a good solution.
>
> For the methods we probably need a more compact solution.
>
> Regards,
> Rüdiger
>
>
> 2011/3/22 Daniel Sobral :
>> On Tue, Mar 22, 2011 at 06:53, Donna Malayeri wrote:
>>>
>>> On Mar 22, 2011, at 10:10 AM, Rüdiger Keller wrote:
>>>
>>>> I like the idea of removing the collapsing/expanding for the class
>>>> descriptions. It seems superfluous and unnecessary. What do others
>>>> think?
>>>
>>> I agree with this as well--it produces a strange visual effect, and as
>>> Bill said, it's not obvious that it's there.
>>>
>>
>> The obviousness thing is a concern, but look at
>> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/....
>> When class information is expanded, it pushes the methods of of screen.
>> Worse yet, it looks scary. :-)
>> So, at the very least I'd keep linearization and known
>> subclasses collapsible.
>> At any rate, if we figure out how to do a clear indication that methods
>> descriptions are collapsible, we can probably apply the same principle to
>> the class.
>>
>> --
>> Daniel C. Sobral
>>
>> I travel to the future all the time.
>>

I think some form of gradient background for panels could look good, and also work well as visual separator.  You could then use a change in colour to distinguish between expanded/collapsed.


On 22 March 2011 12:37, Donna Malayeri <lindydonna@gmail.com> wrote:

Ruediger:

That's an excellent suggestion: a link for showing the additional information. I can certainly change the generated HTML, but I'm not sure which distribution this will go in. (Some RC between RC1 and final?)

Do you happen to know why it produces such a strange visual effect when the additional information is displayed?  I imagine it has to do with JavaScript and CSS.

For methods, I think some sort of triangle icon would be good, but that's a bigger change.

thanks,
Donna

On Mar 22, 2011, at 1:33 PM, Ruediger Keller wrote:

> Hi,
>
> I don't think that "pushes the methods of of screen" is a problem.
> Depending on the class documentation they may not be visible to begin
> with (see http://www.artima.com/sdp/suggestion3/org/scalatest/Suite.html).
> Also, IMHO it is fairly obvious that you have to scroll the page to
> see everything there is.
>
> But I agree that linearization and known subclasses look somewhat
> scary for most of the collection classes. If there was a button / link
> ("Show linearization and known subclasses") specifically for showing
> these, it would be nice, I think. The clickable signatures / comments
> don't seem to be ideal. For the class descriptions space is not an
> issue, so a separate line with such a link would be a good solution.
>
> For the methods we probably need a more compact solution.
>
> Regards,
> Rüdiger
>
>
> 2011/3/22 Daniel Sobral <dcsobral@gmail.com>:
>> On Tue, Mar 22, 2011 at 06:53, Donna Malayeri <lindydonna@gmail.com> wrote:
>>>
>>> On Mar 22, 2011, at 10:10 AM, Rüdiger Keller wrote:
>>>
>>>> I like the idea of removing the collapsing/expanding for the class
>>>> descriptions. It seems superfluous and unnecessary. What do others
>>>> think?
>>>
>>> I agree with this as well--it produces a strange visual effect, and as
>>> Bill said, it's not obvious that it's there.
>>>
>>
>> The obviousness thing is a concern, but look at
>> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/scala/collection/Seq.html.
>> When class information is expanded, it pushes the methods of of screen.
>> Worse yet, it looks scary. :-)
>> So, at the very least I'd keep linearization and known
>> subclasses collapsible.
>> At any rate, if we figure out how to do a clear indication that methods
>> descriptions are collapsible,  we can probably apply the same principle to
>> the class.
>>
>> --
>> Daniel C. Sobral
>>
>> I travel to the future all the time.
>>

--
Kevin Wright

gtalk / msn : kev.lee.wright@gmail.comkev.lee.wright@gmail.commail: kevin.wright@scalatechnology.com
vibe / skype: kev.lee.wrightquora: http://www.quora.com/Kevin-Wright
twitter: @thecoda

"My point today is that, if we wish to count lines of code, we should not regard them as "lines produced" but as "lines spent": the current conventional wisdom is so foolish as to book that count on the wrong side of the ledger" ~ Dijkstra

Hi Donna,

I also noticed the strange effect when expanding comments. I seems the
short comment is slid upwards, out of view, and at the same time the
full comment is slid downwards into view. That probably results in
this strange effect. The problem is that short and full comment are
completely separate things, where the full comment duplicates
everything in the short comment + more. Therefore we cannot just slide
in the additional information in the full comment, but we also need to
remove the short comment. The sliding is probably used to avoid big
jumps in the page when opening the full comments. I'm not sure if we
can improve upon this without changing the structure of the generated
HTML, but I can look into this when I find some time.

Also, I really like the idea of using triangles for the methods. I
will throw together an example for this, if I have some spare time
this evening. I think it should be doable via CSS only, so no too big
changes are required.

Regards,
Rüdiger

2011/3/22 Donna Malayeri :
> Ruediger:
>
> That's an excellent suggestion: a link for showing the additional information. I can certainly change the generated HTML, but I'm not sure which distribution this will go in. (Some RC between RC1 and final?)
>
> Do you happen to know why it produces such a strange visual effect when the additional information is displayed?  I imagine it has to do with JavaScript and CSS.
>
> For methods, I think some sort of triangle icon would be good, but that's a bigger change.
>
> thanks,
> Donna
>
> On Mar 22, 2011, at 1:33 PM, Ruediger Keller wrote:
>
>> Hi,
>>
>> I don't think that "pushes the methods of of screen" is a problem.
>> Depending on the class documentation they may not be visible to begin
>> with (see http://www.artima.com/sdp/suggestion3/org/scalatest/Suite.html).
>> Also, IMHO it is fairly obvious that you have to scroll the page to
>> see everything there is.
>>
>> But I agree that linearization and known subclasses look somewhat
>> scary for most of the collection classes. If there was a button / link
>> ("Show linearization and known subclasses") specifically for showing
>> these, it would be nice, I think. The clickable signatures / comments
>> don't seem to be ideal. For the class descriptions space is not an
>> issue, so a separate line with such a link would be a good solution.
>>
>> For the methods we probably need a more compact solution.
>>
>> Regards,
>> Rüdiger
>>
>>
>> 2011/3/22 Daniel Sobral :
>>> On Tue, Mar 22, 2011 at 06:53, Donna Malayeri wrote:
>>>>
>>>> On Mar 22, 2011, at 10:10 AM, Rüdiger Keller wrote:
>>>>
>>>>> I like the idea of removing the collapsing/expanding for the class
>>>>> descriptions. It seems superfluous and unnecessary. What do others
>>>>> think?
>>>>
>>>> I agree with this as well--it produces a strange visual effect, and as
>>>> Bill said, it's not obvious that it's there.
>>>>
>>>
>>> The obviousness thing is a concern, but look at
>>> http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/....
>>> When class information is expanded, it pushes the methods of of screen.
>>> Worse yet, it looks scary. :-)
>>> So, at the very least I'd keep linearization and known
>>> subclasses collapsible.
>>> At any rate, if we figure out how to do a clear indication that methods
>>> descriptions are collapsible,  we can probably apply the same principle to
>>> the class.
>>>
>>> --
>>> Daniel C. Sobral
>>>
>>> I travel to the future all the time.
>>>
>
>

> I also noticed the strange effect when expanding comments. I seems the
> short comment is slid upwards, out of view, and at the same time the
> full comment is slid downwards into view. That probably results in
> this strange effect. The problem is that short and full comment are
> completely separate things, where the full comment duplicates
> everything in the short comment + more. Therefore we cannot just slide
> in the additional information in the full comment, but we also need to
> remove the short comment. The sliding is probably used to avoid big
> jumps in the page when opening the full comments. I'm not sure if we
> can improve upon this without changing the structure of the generated
> HTML, but I can look into this when I find some time.

I can change the generated HTML, as long as I know how it should be changed.

> Also, I really like the idea of using triangles for the methods. I
> will throw together an example for this, if I have some spare time
> this evening. I think it should be doable via CSS only, so no too big
> changes are required.

If it's doable with CSS only, that would be fantastic, but I think the class comment issue is more important. Or were you referring to the method comments in above?

I'm so glad a CSS person is looking at this stuff. :)

thanks,
Donna

Hi,

>> http://www.artima.com/sdp/suggestion2/org/scalatest/Suite.html#errorHand...
> Not sure, if that means anything, but in your examples something seems
> to be broken with the font on Google Chrome (Ubuntu 10.10): after some
> lines all text will be bold.
Additionally, if I click on method "group", it collapses, but doesn't
expand after that anymore.

Bye,

Simon

Hi Simon,

The issues you saw was caused by this bug:

https://lampsvn.epfl.ch/trac/scala/ticket/4366

which has been fixed! I verified that this bug and the similar one
caused by italics no longer exists in the latest 2.9.0-SNAPSHOT.
Thanks to all who are working to improve Scaladoc.

Bill

On Tue, Mar 22, 2011 at 11:38 AM, Simon Ochsenreither
wrote:
> Hi,
>
>>>
>>> http://www.artima.com/sdp/suggestion2/org/scalatest/Suite.html#errorHand...
>>
>> Not sure, if that means anything, but in your examples something seems
>> to be broken with the font on Google Chrome (Ubuntu 10.10): after some
>> lines all text will be bold.
>
> Additionally, if I click on method "group", it collapses, but doesn't expand
> after that anymore.
>
> Bye,
>
> Simon
>