Magnus Therning writes:

On Wed, Aug 4, 2010 at 06:00, Mark Lentczner wrote:

...

The Haddock team has spent the last few months revamping the look of the generated output. We're pretty close to done, but we'd like to get the community's input before we put it in the main release.

Please take a look, and then give us your feedback through a short survey

Sample pages:  http://www.ozonehouse.com/mark/snap-xhtml/index.html

I really like it, especially the synopsis tab on the right. Brilliant! The TOC is nice too! The over-all impression is that it doesn't look as auto-generated as the old style.

Agreed; I'm also glad that the usage of a middle column isn't a fixed width but resizes as the text resizes (the lack of this is something that annoys me to no end on some websites).

...

Frame version: http://www.ozonehouse.com/mark/snap-xhtml/frames.html

Also very good looking. Does the current stable version of Haddock really create a frame version? I've never seen one before...

There is, but I for one don't use it (and there was an email sent out in May asking if anyone did: http://www.mail-archive.com/haskell-cafe@haskell.org/msg75269.html ). I quite like this new approach, however, but with one caveat: the empty frame on the bottom left at default. Especially with my weird firefox setup (which has almost grown organically over the years and should really be wiped), it doesn't display too well; is it possible to have _something_ there by default just to make it look more interesting (Haskell logo, a message saying "stuff will appear here when you click on something above", etc.) ? However, I would still be highly tempted to use the framed version by default with that new layout. -- Ivan Lazar Miljenovic Ivan.Miljenovic@gmail.com IvanMiljenovic.wordpress.com

On Aug 4, 2010, at 5:11 AM, Magnus Therning wrote:

Does the current stable version of Haddock really create a frame version? I've never seen one before...

Yes it does. For example, the standaed GHC book packages doc has the frames version here: http://www.haskell.org/ghc/docs/6.12.2/html/libraries/frames.html Documentation on Hackage doesn't seems to be missing two of the generated files to enable the frames version to work for each package. - Mark

On Wed, Aug 4, 2010 at 2:11 AM, Magnus Therning wrote:

On Wed, Aug 4, 2010 at 06:00, Mark Lentczner wrote:

...

The Haddock team has spent the last few months revamping the look of the generated output. We're pretty close to done, but we'd like to get the community's input before we put it in the main release.

Please take a look, and then give us your feedback through a short survey

Sample pages: http://www.ozonehouse.com/mark/snap-xhtml/index.html

I really like it, especially the synopsis tab on the right.

Likewise, although I notice that the synopsis tab closes if I click on a link inside it, which seems unfortunate. Mark, thanks for the great work!

On 4 August 2010 15:44, aditya siram wrote:

I really like the color scheme and the Javadoc looking frames.

One suggestion I can make is to have the index show all the functions with type signatures without having to pick a letter. A lot of times I'll be looking for a function of a certain signature as opposed to a name. Indeed an index of type signatures would great! I remember wishing I had this when trying the understand the Parsec package.

-deech

Wouldn't hoogle be better for this kind of use case? The index can become very large already. More direct hoogle/hayoo integration (at least on Hackage) sounds like a worthwhile goal, though. Noted.

On Wed, Aug 4, 2010 at 8:55 AM, Yitzchak Gale wrote:

...

Mark Lentczner wrote:

...

The Haddock team... Please take a look, and then give us your feedback

Very very nice. I took the survey, but here are some comments I left out.

I like the idea of the Snappy style the best, but there are two serious problems with it, at least in my browser (Safari):

1. The black on dark blue of the "Snap Packages" title makes it nearly unreadable for me. 2. The wide fonts stretch things out so far on my screen that the page becomes almost unusable.

The other styles are fine, I would use them instead.

Here is a comment I'll repeat from the survey because of its importance: Please add a "collapse all" button for the tree on the contents page. For me, that is perhaps the most urgent thing missing in all of Haddock. It would make that tree so much more usable.

Thanks for the great work, Yitz _______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

_______________________________________________ Haskell-Cafe mailing list Haskell-Cafe@haskell.org http://www.haskell.org/mailman/listinfo/haskell-cafe

-- If it looks like a duck, and quacks like a duck, we have at least to consider the possibility that we have a small aquatic bird of the family Anatidae on our hands.

On Thu, Aug 5, 2010 at 3:35 PM, Dino Morelli wrote:

On Wed, 4 Aug 2010, Mark Lentczner wrote:

...

The Haddock team has spent the last few months revamping the look of the generated output. We're pretty close to done, but we'd like to get the community's input before we put it in the main release.

Please take a look, and then give us your feedback through a short survey

Sample pages: http://www.ozonehouse.com/mark/snap-xhtml/index.html Frame version: http://www.ozonehouse.com/mark/snap-xhtml/frames.html

One thing I haven't seen anyone else comment on is the width of the new docs. I have a large (26") monitor and use the browser full-screen (with xmonad, so even more screen space). When I load these pages, particularly the non-frame one, something like 50% of my screen real-estate is empty whitespace on either side of the doc content. There is also wasted space in the frames version, just a little less of it. I wish the docs were using that space like the current Haddock does. Is the plan to use a fixed width like this?

Yes. There's research suggesting that the line length should be between 65 and 75 characters per line. http://psychology.wichita.edu/surl/usabilitynews/42/text_length.htm

On Thu, 5 Aug 2010, Johan Tibell wrote:

...

On Thu, Aug 5, 2010 at 3:35 PM, Dino Morelli wrote:

One thing I haven't seen anyone else comment on is the width of the new docs. I have a large (26") monitor and use the browser full-screen (with xmonad, so even more screen space). When I load these pages, particularly the non-frame one, something like 50% of my screen real-estate is empty whitespace on either side of the doc content. There is also wasted space in the frames version, just a little less of it. I wish the docs were using that space like the current Haddock does. Is the plan to use a fixed width like this?

Yes. There's research suggesting that the line length should be between 65 and 75 characters per line.

I understand, I've read that too in the context of publishing with long paragraph style material. But I think the majority of generated programming API docs are not done with fixed width. Here are several examples: JavaDoc at Sun: http://download.oracle.com/javase/7/docs/api/ Scala API docs, very recently redesigned for 2.8.x: http://www.scala-lang.org/api/current/index.html Google Android API docs: http://developer.android.com/reference/packages.html Erlang docs: http://www.erlang.org/doc/ Microsoft F# lang and API docs: http://msdn.microsoft.com/library/dd233154%28VS.100%29.aspx The Python Standard Library: http://docs.python.org/library/ Ruby-doc: http://www.ruby-doc.org/core/ I did find one that uses fixed width though, this Perl5 documentation site: http://perldoc.perl.org/perlapi.html -- Dino Morelli email: dino@ui3.info web: http://ui3.info/d/ irc: dino- pubkey: http://ui3.info/d/dino-4AA4F02D-pub.gpg twitter: dino8352

On 06/08/10 03:15, Jeff Zaroyko wrote:

On Thu, Aug 5, 2010 at 11:48 PM, Johan Tibell wrote:

...

On Thu, Aug 5, 2010 at 3:35 PM, Dino Morelli wrote:

...

On Wed, 4 Aug 2010, Mark Lentczner wrote: One thing I haven't seen anyone else comment on is the width of the new docs. I have a large (26") monitor and use the browser full-screen (with xmonad, so even more screen space). When I load these pages, particularly the non-frame one, something like 50% of my screen real-estate is empty whitespace on either side of the doc content. There is also wasted space in the frames version, just a little less of it. I wish the docs were using that space like the current Haddock does. Is the plan to use a fixed width like this?

Yes. There's research suggesting that the line length should be between 65 and 75 characters per line. http://psychology.wichita.edu/surl/usabilitynews/42/text_length.htm

http://psychology.wichita.edu/surl/usabilitynews/72/LineLength.asp

"This study examined the effects of line length on reading speed, comprehension, and user satisfaction of online news articles."

I completely agree with the case of news articles, but not in the case of Haskell documentation, it's structured differently and different parts such as bold or larger typeface serve as points of reference when reading, in contrast to plain old paragraphs found in a news article.

The current layout works very well for me, I don't like the additional whitespace in the proposed version. I feel the colour scheme is a step backwards from what we have already, which offers high visibility.

Personally I think the way the current layout expands to the full width of the window makes it really hard to read with a wide browser, but since many sites suffer from the same problem I normally use a narrower browser window and fill up the rest of the screen space with IRC windows :-) The great thing about the Haddock redesign is that the content has been separated from the style. If opinions about the style are sufficiently divided we can provide a style switcher on the docs we ship with GHC, and make that the default for Cabal-generated docs. Although the opinions I've seen so far suggest that the majority of people prefer the new style. Cheers, Simon

-----BEGIN PGP SIGNED MESSAGE----- Hash: SHA1 On 8/5/10 09:35 , Dino Morelli wrote:

Please say no, it's a disappointing trend that you see everywhere. Like Twitter's web interface, for instance, very narrow.

Twitter's web interface isn't really intended for serious use, IMO. Tweetdeck for desktops, tweetgrid/hootsuite/etc. for browser based. - -- brandon s. allbery [linux,solaris,freebsd,perl] allbery@kf8nh.com system administrator [openafs,heimdal,too many hats] allbery@ece.cmu.edu electrical and computer engineering, carnegie mellon university KF8NH -----BEGIN PGP SIGNATURE----- Version: GnuPG v2.0.10 (Darwin) Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/ iEYEARECAAYFAkxa2PgACgkQIn7hlCsL25UUtACggsp0tOxK9GqPU6qZYunpuFq0 egEAoKjqmjOGlCgkVJTGHE98MX9+HvoZ =PhUs -----END PGP SIGNATURE-----

On Thu, Aug 5, 2010 at 2:35 PM, Dino Morelli wrote:

One thing I haven't seen anyone else comment on is the width of the new docs. I have a large (26") monitor and use the browser full-screen (with xmonad, so even more screen space). When I load these pages, particularly the non-frame one, something like 50% of my screen real-estate is empty whitespace on either side of the doc content. There is also wasted space in the frames version, just a little less of it. I wish the docs were using that space like the current Haddock does. Is the plan to use a fixed width like this?

Please say no, it's a disappointing trend that you see everywhere. Like Twitter's web interface, for instance, very narrow.

Yeah, I wrote about this in my survey response. It seems to me that if I find text in a narrow page more readable, I can easily just resize my browser window, this doesn't need to be enforced by the webpage itself. I'm also not so enthusiastic about tabbed synposis. I'm not convinced you can easily use the synopsis and doc text simultaneously, so I don't see any reason for it to be apart from the text body. Simplicity is a virtue :) I do think that in terms of colours, fonts etc. it's prettier, but the fixed max width and kind of gimmicky synopsis tab are steps backward in my opinion.

I prefer the new look. That being said, I'd rather like haddock handling unicode characters in comments, at the moment it's unusable if I want to write comments in French.

On Sat, Aug 7, 2010 at 7:54 AM, Magnus Therning wrote:

<joke>Wouldn't the docs be unusable if it were in French even if Haddock handled unicode characters correctly?</joke>

Joke aside, for software to be released, a French documentation indeed wouldn't be of much use. The langage of technology and science and les internets is English, and I'm fine with that. I would only document software in French that is written for my company, and isn't supposed to be released. I hope we're not hijacking the thread here :) David.

Hi Lars, On Mon, Aug 9, 2010 at 10:23 AM, Lars Viklund wrote:

The survey seems to be inactive, by the way.

It's because Mark already posted the results. :) Cheers, Johan