[racket-dev] Tweaked doc pages

Two hours ago, Matthew Flatt wrote:
> At Wed, 27 Feb 2013 11:36:54 -0500, Eli Barzilay wrote:
> > 
> > * The layout should have the main column centered.  (I thought that it
> >   was fine initially if the left column is part of the contents.)
> 
> That column alignment looks good, now. Also, I like the PDF links.

(Actually, I didn't get to talk mention that it's in its current
improved state... but obviously it is...)


> The content column is wider than in the normal documentation
> display.  That makes line-spanning paragraphs a little less nice to
> read, and it makes right-margin notes more likely to fall out of the
> display area, but those are not big problems.

Yeah, I've noticed that too.  Since at the global layout level it's
all plain em constants, I can maybe shave off a few ems on both sides
so it'll still be centered and more easy to read.  It will, however,
lose a little from the "centeredness" feeling.

Another option is to make the text a little bigger to compensate for
the narrowness.

(Either way, or leaving it as is, is fine with me, so I'll appreciate
opinions about it.)


> > * There might be a need for a shorter banner for the textual
> >   pages, to save some space.  (I'm not sure whether this is really
> >   needed...)
> 
> I feel like the banner takes up too much space, so that I have to
> scroll more when browsing, and I doubt that I would ever want the
> banner content when I'm trying to read the documentation.

I think that I missed this being a problem for the same reason that
Robby did...  In any case, one option that I wanted to play with is
having a smaller banner logo + text which will make the whole navbar
shorter.

But maybe what Robby suggests works out better?  I generally dislike
links that don't go to the top of a page, but maybe it's fine here.

Another compromise is to just have the "top-of-web-page" anchor be
right before the nav links, so you will have the links visible, and
the rest available.  How does that sound?


> Would it make sense to add the banner only on the main documentation
> page? That would provide more consistency (especially when clicking
> "Documentation" in the banner), but it would take less space when
> reading documentation, searching, etc.

(Two things that make not like this: it's not clear to me which pages
would have the banner and which won't; and secondly, the main property
of the banner and the uniform look is that it's all in the same place,
and breaking it won't look good.)


Two hours ago, Danny Yoo wrote:
> 
> The docs look good.  I'm a little confused at what looks like a
> regression to PR 13305 though: when I look at the underscore-leading
> identifiers of:
> 
>     http://newdocs.racket-lang.org/foreign/Other_Atomic_Types.html
> 
> both of them in the "On this page" are misrendered.  But when I look
> at the page in my local HEAD-generated documentation, it's rendering
> ok.  Do you know what's happening there?

These pages are not built from scratch -- they're tweaked versions of
the existing docs.  So you see there the web-variant of the released
5.3.3 docs, which, IIRC, precedes the fix you're talking about.


A few minutes ago, Robby Findler wrote:
> 
> In that spirit, could we change the section links to use an anchor
> at the top of the docs? That would probably have the same effect as
> Matthew's suggestion.  Not sure if it easier or otherwise better,
> tho.

(BTW, I'm assuming that you're talking about internal links from the
docs to the docs which would be tweaked this way.)

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