[Haddock] first post-survey version

[Mark Lentczner]

On Aug 16, 2010, at 9:44 AM, Thomas Schilling wrote:
> Why do we have to set a fixed font size?  Do we
> really not trust users to adjust their defaults?  If you really feel
> you have to, then set the default size on all pages, not just the main
> docs.

It isn't set to a fixed font size. All font sizes, on all pages are relative to the user's setting. Try increasing/decreasing the text size. It should be consistent across all pages. Since these are test pages, I'm not renaming the CSS file with each revision, so you may need to expressly double-reload to get the new CSS (some browsers need to be proded.) If there are still inconsistencies, let me know where and I'll fix.

The problem with web typography is that due to some early bad choices, the "nominal" font size of text, given no styling whatsoever is 16pt. It isn't set at 16pt because people like to read text at 16pt, but because when serious concern in browsers was finally given to web typography, the vast majority of web sites were using things like <small> to achieve a readable font size thanks to the prior problems. Hence, un-styled text had to be set at 16pt, so most body text showed at a reasonable, smaller size.

The current CSS follows the standard practices as used by Yahoo, Google, A List Apart and others: The standard body text is set to 13pt (relative to the nominal 16pt of un-styled text), all other font sizes are set relative to that (via percentages, but calculated to produce linear increments in font size, which the eye perceives as step-wise). Of course, the whole thing scales up and down with the text rendering controls in browsers (even IE). See:

	http://developer.yahoo.com/yui/3/cssfonts/
	http://www.alistapart.com/articles/howtosizetextincss/

I also checked several sites, documentation and otherwise, and noted that many of them use the same 13pt size for body text. For example:

	Android	http://developer.android.com/reference/android/content/ComponentName.html
	Scala	http://www.scala-lang.org/api/current/scala/collection/Map.html
	Clojure	http://clojure.github.com/clojure/clojure.string-api.html (but, ew, monospace doc!)
	Perl		http://perldoc.perl.org/functions/chomp.html

	MSDN APIs		http://msdn.microsoft.com/en-us/library/dd233229.aspx
	Apple APIs		http://developer.apple.com/mac/library/documentation/Cocoa/Reference/Foundation/Classes/NSDictionary_Class/Reference/Reference.html
	Facebook API	http://developers.facebook.com/docs/reference/fql/

	Google News		http://www.google.com/news
	Facebook Home	http://www.facebook.com/home.php


Some use different by a hair:
	jQuery, 12pt		http://api.jquery.com/clearQueue/
	SalesForce, 12pt	http://www.salesforce.com/us/developer/docs/api/index.htm
	Ruby, 14pt		http://ruby-doc.org/stdlib/libdoc/date/rdoc/files/date_rb.html
	PHP, 14pt		http://www.php.net/manual/en/datetime.setisodate.php
	Twitter, 14pt		http://dev.twitter.com/doc/get/users/suggestions

A few leave things at 16pt:
	Python	http://docs.python.org/py3k/library/datetime.html
	Java		http://download.oracle.com/javase/6/docs/api/java/util/AbstractMap.html
	OCaml	http://caml.inria.fr/pub/docs/manual-ocaml/libref/Map.html

Of these last three, Python's doc is a cacophony of font sizes, and on the whole rather large. Java and OCaml both look un-styled, or at least, developed in 10 years ago. Java's is particularly hard to look at. All three of these have clearly not thought deeply at typography (Python's styled look not withstanding): consider how badly sized the monospace text in all cases is vis-a-vis the proportional.

Hence, I think with respect to what the user is likely to have for normal reading, the 13pt std. is probably right.

	- Mark


-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://projects.haskell.org/pipermail/haddock/attachments/20100816/39f714db/attachment.htm