[racket] Best way to propose changes to Scribble CSS files

From: Neil Van Dyke (neil at neilvandyke.org)
Date: Wed Nov 20 17:55:46 EST 2013

Comments on documentation based on looking at 
"http://www.cs.utah.edu/plt/snapshots/current/doc/reference/strings.html"...

* Overall, a big improvement.

* I don't like the zooming text size for these manuals, especially not 
when it's larger than user's preferred body text size in browser. 
  People's program editors and other Web documents don't do that, and it 
takes people's eyes a while to adjust when going between different text 
sizes.  @margin-note{A long time ago, as some know, right after Mosaic, 
`Web designers' immediately disregarded some of the original intent and 
guidance of HTML, and started trying to specify all text in pixels or 
points, regardless of the size/resolution/clarity of the display and the 
vision and position of the user.  (Then designers tried to do Web pages 
as GIFs, then as PDFs, then as Flash, before we beat it out of them.) 
  Recently, more than a decade later, Web designers are finally starting 
to backpedal on HTML, only calling it a new thing, ``responsive 
design,'' like it's something new that only they were insightful and 
stylishly-dressed enough to invent, not what engineers were telling them 
from very the beginning.  The preferred body text size and some other 
basics of device independence have been there from the start in HTML and 
Web browsers.}

* Too much vertical spacing between entries in left-bar TOC. It's 
noticeably big, and makes the difference between some TOCs fitting on my 
screen and not fitting on my screen.

* I'm trying to get used to the desaturated colors and pallete tweaks, 
especially when it means that Racket identifiers in body text appear to 
be the same color as various section links and "@hyperlink", as well as 
"@tech" links.  I was accustomed to all three things looking different, 
but now they're conflated.  With "tech" links, they previously looked 
like body text except for a muted underline, so I felt OK using them for 
an important technical terms that a reader of this paragraph might well 
not know; now, paragraphs are full of lots of indistinguishable cyan 
links, and the "tech" links are more prominent than previously. 
  Similarly, with Racket identifiers, we knew that Racket identifiers 
were generally links, so we didn't have to color them as links, and the 
near-text-color was less disruptive to reading flow.  I'm still missing 
identifiers and "tech" links looking more like body text, and the rare 
*other* kind of links being the ones we think are worth breaking flow 
and making more distinguished.

* Not a big fan of the font for the chapter/section/etc. headings.  The 
font looks OK at lower sizes, but is not scaling well, and becomes less 
readable (I'm referring to how scalable fonts don't necessarily just use 
just an X-Y transform).  If it looked more like a non-bold variant of 
the same license plate-ish font used for the title, that might be 
better, although that font looks almost fixed-pitch.  The old Helvetica, 
Arial, etc. implementations tend to scale better, and they look OK but 
aren't as stylish.

* Again, overall, a big improvement.

Neil V.

Matthew Butterick wrote at 11/20/2013 12:27 AM:
> Asumu + Greg + others who find bugs in the new doc layout: I will look into anything posted on this thread or emailed to me directly (mb at mbtype.com). I've found a few nits as well.


Posted on the users mailing list.