An alternative CSS for Scaladoc

[Kato Kazuyoshi]

Hi,

I've wrote an alternative CSS for Scaladoc. Original Scaladoc uses
many colors, but I don't like (yes, it's just a preference) this.

Then my version uses a few colors: white, black and gray. And I've
added button-like style for clickable area.

You can see my version at http://8-p.info/tmp/scaladoc/library/ and
you can clone from https://github.com/kzys/scala/tree/white.

Regards,

--
Kato Kazuyoshi

[Rüdiger Keller]

Hi Kazuyoshi,

yes, I think everybody has been bothered by the "too many colors"
syndrome of the current scaladoc. I really like some of you changes.
:-)

Though, as far as I heard, Donna finally found someone with design
experience and that someone is currently creating a new layout for
scaladoc. We should probably put our css efforts on hold until we see
the results.

Also, currently it seems that at least three persons are trying to
change the css simultaneously, and that's probably not gonna work out
too well. :-)

Regards,
Rüdiger

2011/4/6 Kato Kazuyoshi <kato.ka...@gmail.com>:

[Nils Kilden-Pedersen]

On Wed, Apr 6, 2011 at 11:02 AM, Rüdiger Keller <ruedige...@googlemail.com> wrote:

Also, currently it seems that at least three persons are trying to
change the css simultaneously, and that's probably not gonna work out
too well. :-)

Depends on the use case. Yes, the Scala library will ultimately only have one CSS, but other projects could pick and choose among any number of alternative stylesheets for their own API.

[Jon Steelman]

Hi Kato,

I like your minimalist styling and hope the new official design is at least influenced by this.

Thanks,

Jon

[Martin Grigorov]

I prefer the old (green) version.

[L. Stitz]

I like how you used spacing to seperate the page into subsections of
different concerns, that you hid complex and overpowering info like
the list of linear supertypes (which is probably confusing to many
newbies) and that you managed to communicate clearly that the
paragraphs of Ordering, Inherited and Visibility consist of toggle
buttons. I also think that the lighter colours in the main area at the
right hand side facilitate reading the actual documentation.

Thanks for your work. :)

And while we're at it - it would be great if one could select the one
of maybe a handful of different ScalaDoc CSS layouts that suits
personal preference and taste...

Regards, Lars

[Daniel Sobral]

It seems most of the things you liked are, actually, already on trunk: http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html

Oops, just checked. It seems the commit has been reversed. I wonder why...

--
Daniel C. Sobral

I travel to the future all the time.

[martin odersky]

On Wed, Apr 6, 2011 at 5:49 PM, Kato Kazuyoshi <kato.ka...@gmail.com> wrote:

Hi,

I've wrote an alternative CSS for Scaladoc. Original Scaladoc uses
many colors, but I don't like (yes, it's just a preference) this.

Then my version uses a few colors: white, black and gray. And I've
added button-like style for clickable area.

Hi Kato,

I like your design, it brings out well what's important. One small problem I had is that on my browser (Firofox on MacOS) each class/trait/object symbol on the left appears in a box with a white background in a black frame. I assume that's not intentional?

Best,

 -- Martin

[Donna Malayeri]

I like many aspects of Kato's design, and I will incorporate some of them into the css. I also like the idea of including several CSS versions that people can choose from.

Donna

[Donna Malayeri]

Daniel,

Which commit are you referring to?  I don't see anything reverted.

Donna

[Donna Malayeri]

Martin,

Can you be more specific about what you like about Kato's design?  Personally, I like the reduced number of colors, the increased font size, the use of a different font for comments, and the fact that things that act like buttons look more like buttons. I also like the color coding of things like "def", "type", etc.

thanks,
Donna

[martin odersky]

On Thu, Apr 7, 2011 at 1:55 PM, Donna Malayeri <lindy...@gmail.com> wrote:

Martin,

Can you be more specific about what you like about Kato's design?  Personally, I like the reduced number of colors, the increased font size, the use of a different font for comments, and the fact that things that act like buttons look more like buttons. I also like the color coding of things like "def", "type", etc.

Yes, that's what I linked about it as well. Plus he triangle's left of defs that open (but i think that was also present in some other designs)?

 -- martin
 

thanks,
Donna

I like your design, it brings out well what's important. One small problem I had is that on my browser (Firofox on MacOS) each class/trait/object symbol on the left appears in a box with a white background in a black frame. I assume that's not intentional?

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

[Donna Malayeri]

Yes, the triangle to the left of defs is also in the nightly Scaladoc (http://www.scala-lang.org/archives/downloads/distrib/files/nightly/docs/library/index.html). 

It's great that so many people are contributing improvements!

Donna

[David Bernard]

OT:

VScaladoc2 was crearted with multi-skin in mind. so users can
customize layout of information, currently only for a local
installation but for every api.
If someone is interested by more details, ask me privatly or in an other thread.

/davidB

[Ruediger Keller]

As I said before, I think there are many improvements in Kazuyoshi's suggestion.

But there are also things I don't like. For one, the color coding of
the different types (class, object, trait) is missing and I think that
was a good thing in the old scaladoc. Also, for me, the suggested
design is missing a consistent style. Different areas seem to follow
different styles. Also, the various spacings in general seem a bit
random.

I'm also thinking about creating a completely overhauled layout, but
Donna says I should wait for the new layout by her secret design
contact. :-)

But, I feel we are getting closer to the real thing. A few more of
these iterations and we will have something really good.

Regards,
Rüdiger

2011/4/7 Donna Malayeri <lindy...@gmail.com>:

[Sciss]

my two cents:

although a very reduced design can be good, i think the color coding of the 2.10.0 nightly that donna posted looks marvellous and underlines the creativity in scala that makes it different from the grey computer world. while i think the spaciousness in the class list on the left is improved in the kato design, in the main right frame it is a bit too exaggerated -- the ordering/ inherited/ visibility box takes like almost half of my browser height. also although i like the idea of the buttons i can barely see a difference between a selected and unselected button (again this might be a firefox problem).

the main issue imo is that the "concrete value members" are much less readable in the kato design -- the lines between each method are very useful (although they don't need to have such a big contrast) and the underlined slightly blueish argument types that link are more pleasant than having a slightly grey background. I also like the use of oblique type for the "Definition Classes".

on the left side the contrast of the packages is very low that makes reading very difficult. the white on blue is nice imo and consistent with the blue and blue-green colour scheme.

using the 2.8.1 docs all the time, i must say i'm very positively surprised by the current 2.10.0 look. the crispy slightly sharpened icons (O, C, t) are great, and the new colours, too. god job!!
the only thing that seems to have gone is the button to switch to the companion type -- i found that incredibly useful. why did it disappear?

all in all switchable CSS is the solution i think, because different people will have different scenarios ("creative" vs. "business" vs. "scientific")

best, -sciss-

[Donna Malayeri]

> using the 2.8.1 docs all the time, i must say i'm very positively surprised by the current 2.10.0 look. the crispy slightly sharpened icons (O, C, t) are great, and the new colours, too. god job!!
> the only thing that seems to have gone is the button to switch to the companion type -- i found that incredibly useful. why did it disappear?

I turned it into a link on the large class/trait/object name, next to the image. I was worried it wasn't noticeable enough, and it seems maybe I am right!

Donna

[Sciss]

ok. true that it's not obvious. but once you know that, i think it's a good solution, saves space and is fast to access...

[Ruediger Keller]

Hi Sciss,

thank you for your detailed feedback! This kind of feedback is exactly
what we need to improve scaladoc further. Most people only say "i like
it" or "i don't like it", but they don't say what changes/elements
they like or dislike.

This is really appreciated!

Regards,
Rüdiger

2011/4/7 Sciss <con...@sciss.de>:

[Kato Kazuyoshi]

On Thu, Apr 7, 2011 at 1:02 AM, Rüdiger Keller
<ruedige...@googlemail.com> wrote:
>
> Though, as far as I heard, Donna finally found someone with design
> experience and that someone is currently creating a new layout for
> scaladoc. We should probably put our css efforts on hold until we see
> the results.
>

Great news! Donna, can you share the plan?

--
Kato Kazuyoshi

[Kato Kazuyoshi]

On Thu, Apr 7, 2011 at 8:42 PM, Donna Malayeri <lindy...@gmail.com> wrote:
> Daniel,
>
> Which commit are you referring to?  I don't see anything reverted.
>

Sorry, My branch is forked from
http://lampsvn.epfl.ch/trac/scala/changeset/24687 and I haven't
rebased yet.

--
Kato Kazuyoshi

[Kato Kazuyoshi]

On Thu, Apr 7, 2011 at 4:54 PM, martin odersky <martin....@epfl.ch> wrote:
>
> I like your design, it brings out well what's important. One small problem I
> had is that on my browser (Firofox on MacOS) each class/trait/object symbol
> on the left appears in a box with a white background in a black frame. I
> assume that's not intentional?
>

Thank you. I'm glad to hear from the designer of Scala!
However I can't reproduce the problem yet. What is the version of
Firefox you are using?

--
Kato Kazuyoshi

[martin odersky]

3.6.11. I'll try to update and see whether it still appears. -- Martin

[L. Stitz]

Yeah, that looks a lot better (e.g. cleaner) than the ScalaDoc
currently released, too. To everybody whom it concerns: thanks for
your great work :-)

[Daniel Sobral]

On Thu, Apr 7, 2011 at 08:42, Donna Malayeri <lindy...@gmail.com> wrote:

Daniel,

Which commit are you referring to?  I don't see anything reverted.

I must have screwed up somehow. I swear I double checked, but, alas, everything is as it should.

[Johannes Rudolph]

While we're at it:

I don't like the small trait/object/class icons too much. I find a
color gradient on this size (13x13?) makes the icons look blurred
somehow. As another point, for me it looks as if the anti-aliasing is
cut off at the borders, another pixel of white border would probably
help here.

With my limited ability as a designer I quickly hacked these together:

https://gist.github.com/909558

--
Johannes

-----------------------------------------------
Johannes Rudolph
http://virtual-void.net

[Johannes Rudolph]

Another question:

What's the exact purpose of the rubber band below the alphabet short
cuts? Why would you want to use that?

[Donna Malayeri]

The rubber band I don't know about. You're right that it seems unnecessary.

I like the non-gradient icons better--they are indeed easier to read. I'm going to do another version similar to yours, without the gradient.

Donna

[Johannes Rudolph]

On Fri, Apr 8, 2011 at 11:40 AM, Johannes Rudolph
<johannes...@googlemail.com> wrote:

> https://gist.github.com/909558

I uploaded a version with my icons:

http://jrudolph.github.com/scaladocs-proposal/

[Kevin Wright]

That's a shame... I personally liked the gradients, though I am concerned that the colours to distinguish classes from traits are a bit too similar.

Perhaps we could all have different shaped icons for classes/traits/objects (in addition to the embedded letters) to help with accessibility for anyone who's colour-blind.

--
Kevin Wright

gtalk / msn : kev.lee...@gmail.com

mail: kevin....@scalatechnology.com

vibe / skype: kev.lee.wright

quora: 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

[Ruediger Keller]

I also liked the current version with gradients better, although I
agree that in the latest iteration the images borders seem somewhat
blurry / fuzzy, which I don't like.

To me it seems Johannes icons are just missing a border?

Btw. experimenting with different shapes might be an idea, although i
fear it might just look odd.

Regards,
Rüdiger

2011/4/8 Kevin Wright <kev.lee...@gmail.com>:

[Kevin Wright]

I reckon: Circle for objects, triangle for traits, square for classes

[Simon Ochsenreither]

+1

[Stefan Wagner]

Hi Kato, hi List,

Kato Kazuyoshi schrieb:
> > I've wrote an alternative CSS for Scaladoc. Original Scaladoc uses
> > many colors, but I don't like (yes, it's just a preference) this.

Sorry, I don't appreciate it.

If I open, for instance, the page of Math, all the 'def, def, def' jump
bold emphasized into my eye, and 'double, double, double, long, int'
with colored background. Repeated information I'm rarely looking for.
Instead the name of the methods should be emphasized: 'abs, acos, asin,
atan'. That's what I'm looking for.

Ergonomic aspects should lead, not so much aesthetical ones.

[Sciss]

ah nooo. the cripsy new icons with gradients look absolute phantastic. they are somewhat sharpened compared to 2.8 and look absolutely not blurry here, and no pixels are cut off. maybe it's a problem with your browser? on ff4 they look very nice:

[Ruediger Keller]

Hmmm, strange. For me it's just the opposite. The new ones look
blurred, the old ones were crisp. I have FF4, too, so that's not the
problem.

2011/4/8 Sciss <con...@sciss.de>:

> ah nooo. the cripsy new icons with gradients look absolute phantastic. they are somewhat sharpened compared to 2.8 and look absolutely not blurry here, and no pixels are cut off. maybe it's a problem with your browser? on ff4 they look very nice:
>
>
>
>

> improvement impossible :)

[Daniel Sobral]

Do you mean the thingy that hides/shows the alphabet if you click on it?

[coach3pete]

Looks like the default value for a function param gets erased when the function is assigned to a value and used. Can someone explain what's happening here? Is this expected?

Welcome to Scala version 2.9.0.RC1 (Java HotSpot(TM) 64-Bit Server VM, Java 1.6.0_24).

...

//define a function

scala> def log(code:Int, msg:String = "ok") = {println(code + ", " + msg)}

log: (code: Int,msg: String)Unit

//use all params

scala> log(5,"error")

5, error

//leverage default for msg

scala> log(5)

5, ok

//assign function to a value

scala> val entry = log _

entry: (Int, String) => Unit = <function2>

//use all params

scala> entry(5,"error")

5, error

//fails when trying to use msg default

scala> entry(5)

<console>:10: error: not enough arguments for method apply: (v1: Int,v2: String)Unit in trait Function2.

Unspecified value parameter v2.

       entry(5)

[Jason Zaugg]

On Sat, Apr 9, 2011 at 9:01 AM, coach3pete <coach...@gmail.com> wrote:
> Looks like the default value for a function param gets erased when the
> function is assigned to a value and used. Can someone explain what's
> happening here? Is this expected?

Yep, that's expected: Methods can have defaults; functions can't.

http://stackoverflow.com/questions/2529184/difference-between-method-and-function-in-scala

-jason

[Luc Duponcheel]

somewhat along the same lines ...

here is another example (dealing with implicits)
where function values might not be treated the way
you would (at first sight) expect

scala> implicit def implicitInt: Int = 0
implicitInt: Int

scala> def bar(implicit x: Int): String => String = s => s
bar: (implicit x: Int)(String) => String

scala> bar("bar")
<console>:8: error: type mismatch;
 found   : java.lang.String("bar")
 required: Int
       bar("bar")
           ^

scala> bar.apply("bar")
res1: String = bar

--
   __~O
  -\ <,
(*)/ (*)

reality goes far beyond imagination

[coach3pete]

Oh, wow didn't understand the nuances between methods and functions. So my method below is being converted to a function...and removes param defaults. Is there a way in the REPL to see more of whats happening under the hood? Also, any insight or readings to guide the use of methods vs functions would be helpful. 

scala> def log(code:Int, msg:String = "ok") = {println(code + ", " + msg)}

log: (code: Int,msg: String)Unit

scala> val entry = log _

entry: (Int, String) => Unit = <function2>

[Paul Phillips]

On 4/9/11 9:09 AM, coach3pete wrote:
> Oh, wow didn't understand the nuances between methods and functions. So
> my method below is being converted to a function...and removes param
> defaults. Is there a way in the REPL to see more of whats happening
> under the hood?

It depends on what you mean by "under the hood", but as to this
particular question, it's in the type signature.

> scala> def log(code:Int, msg:String = "ok") = {println(code + ", " + msg)}
> log: (code: Int,msg: String)Unit

That's a method type signature: (foo: Foo, bar: Bar)C

(Notice the names are in the signature.)

> scala> val entry = log _
> entry: (Int, String) => Unit = <function2>

That's a function type signature: (Foo, Bar) => C

(Notice the absence of names.)

[Johannes Rudolph]

On Fri, Apr 8, 2011 at 7:36 PM, Daniel Sobral <dcso...@gmail.com> wrote:
> Do you mean the thingy that hides/shows the alphabet if you click on it?

Ah, yes, this one. Good to know, that it has some purpose at least.
However, I don't think this feature is useful or obvious enough to
warrant adding visual clutter. YMMV

[Johannes Rudolph]

On Fri, Apr 8, 2011 at 4:25 PM, Sciss <con...@sciss.de> wrote:
> ah nooo. the cripsy new icons with gradients look absolute phantastic. they are somewhat sharpened compared to 2.8 and look absolutely not blurry here, and no pixels are cut off. maybe it's a problem with your browser? on ff4 they look very nice:

Finally, it probably comes down to a matter of taste. However, it may
also depend on how far away you sit away from your monitor and what
the resolution of your monitor is. I agree, they look much better on
my 100 dpi monitor than at the other one I used when I made the other
comment. But that's probably exactly the problem with using
anti-aliasing and gradients with icons such small in size.