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

From: Neil Van Dyke (neil at neilvandyke.org)
Date: Wed Nov 20 12:27:22 EST 2013

Before people agonize too much over how to fix the layout of 
"margin-note"s, I'll suggest that it's not just a layout problem...

The ways I use Racket manuals, the "margin-note"s have almost always 
been a problem (and would even if they weren't complicating fitting 
documentation and code editor windows onto my screen at the same time).

The most common scenario seems to be that the information in the 
"margin-note" is actually relevant to the text column -- sometimes even 
some of the most important information -- but it's not in the text 
column where people are actually reading.

In the scenario that the "margin-note" is for an aside/tangent that 
could be would be a distraction from the main text (like a sidebar in a 
magazine page layout), the "margin-note"s are too prominent.

In the scenario of making references to academic literature, the 
"margin-note" seems like a promising way to format that within a Web 
browser page.  It would need decreased prominence relative to the main 
text, and some unambiguous anchor (e.g., footnote number) to exactly 
which bit of text is supported by the footnote.  However, I haven't seen 
hardly any academic footnotes in the Racket manuals.

Thankfully, Racket manuals have not taken up the old convention of doing 
lots of flow-breaking "tip" and "warning" boxes, like used to be more 
popular in sold-by-the-pound paper computer books.

The documentation for "http://www.neilvandyke.org/rackonsole/" 
demonstrates what I think of "margin-note"s in Racket manuals.

Neil V.


Posted on the users mailing list.