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

From: Eli Barzilay (eli at barzilay.org)
Date: Mon Feb 23 09:15:35 EST 2009

On Feb 23, Matthew Flatt wrote:
> 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.

I strongly agree with the TOC comment -- but perhaps it will work to
put the margins in divs that float to the right?


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

It might be possible to have a setting that a JS script will read
(from a cookie), and change the CSS accordingly.  But I don't think
that these things are too effective (last time I tried, it would
render the page as usual, then run the script and move things around.)

-- 
          ((lambda (x) (x x)) (lambda (x) (x x)))          Eli Barzilay:
                  http://www.barzilay.org/                 Maze is Life!


Posted on the dev mailing list.