[plt-dev] Scribble-generate HTML documentation is too wide

The documentation is too wide for my taste with some browsers on some
platforms --- mostly Windows with IE, where the monospace font is too
large or too wide relative to the serif font. I tried and failed to
come up with a better font configuration in the Scribble CSS file, but
I wonder whether a font change that would make the docs more readable
for you.

But to answer your suggestions....

At Mon, 23 Feb 2009 00:17:04 -0500, Neil Van Dyke wrote:
> There are two main layout changes that I'd like to suggest:
> 
> 1. Get rid of the left and right margins.  The "margin notes" in the 
> right margin can be moved inline in the main column.  The TOC in the 
> left margin can be moved to an "autohiding" box that floats in the 
> upper-right of the window.  The autohiding TOC box could be anchored 
> with a click.

These changes could make sense for some users, but I think they'd be
the wrong defaults.

Many pages are designed around the TOC being readily apparent. The main
documentation page is an extreme example, but in general, I find myself
leaning on the existence of a TOC when I design a document. I worry
that if the TOC is autohiding, some readers won't know that it's there.

Margin notes are similar. They exist to encourage cross-referencing
without interrupting the flow of a document, especially in a tutorial
or overview. If I knew that they would be inlined, then I would use
them much less frequently.

But is there a good way to allow readers to customize the view? Or is
configuration via CSS about the best we can do?

> 2. Don't enforce a fixed width for the text.  Let user narrow window to 
> fit on screen without having to do horizontal scrolling.

A Noel says, a fixed width relative to the monospace font is important
for rendering examples, function contracts, and grammars. Those element
become difficult to read if line breaks occur in places that the author
didn't expect. It seems impossible abstract a readable layout of code
over the width of the document. (A "pretty print PLT Scheme code"
functionality built into browsers would help a lot, but even that
probably would not solve everything).

Instead of making the whole page body a fixed width, we could apply a
fixed width to just the elements that need it. But those are exactly
the elements that you're likely to be reading in the docs, so I don't
think it would change the effective width of the document.

Overall, then, I see little hope for this one, even for readers who are
willing to configure via CSS.