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

This is amazing! Thank you very much!

Given all the little rendering things that people are pointing out, I 
should say that the docs are currently using a transitional DOCTYPE, 
which could be part of the problem. You probably have good reasons for 
it, but I thought I'd mention it just in case.

Thanks again!
Dave

On 11/10/2013 12:16 AM, Matthew Butterick wrote:
> Thank you for the comments so far. As for the gentleman who was 
> "reluctant to say anthing negative," please don't be --- the point of 
> making a prototype is to find out what doesn't work.
>
> I won't cover every suggestion here on the mailing list because it 
> will become unwieldy. But I'll move the trickier topics onto the 
> github repo as issues, and those interested can comment further there.
>
>
>
>
> On Sat, Nov 9, 2013 at 5:52 PM, Greg Hendershott 
> <greghendershott at gmail.com <mailto:greghendershott at gmail.com>> wrote:
>
>     This is so wonderful and I'm so happy you did this. It is awesomely
>     awesome. Truly.
>
>     Thank you, thank you, thank you!
>
>
>     My only gripe so far is the floating search box that insists on being
>     in the top-left corner and won't scroll away. On a desktop browser,
>     some people find that sort of thing mildly annoying. On a phone
>     browser, it's worse. For example if you double-tap the main column to
>     zoom in, the search box is still stuck up there floating on top of
>     text you want to read.  tl;dr I suggest letting it scroll off normally
>     along with "on-this-page", preferably IMO always, but at least on
>     small screens.
>
>     One other mobile issue: At least on Chrome for Android, the main text
>     is a comfortable size, but the code examples are very tiny.  (Whereas
>     on the desktop, the sizes seem relatively equal.)
>
>
>
>     On Sat, Nov 9, 2013 at 2:12 AM, Matthew Butterick
>     <mb.list.acct at gmail.com <mailto:mb.list.acct at gmail.com>> wrote:
>     > Rather than edit the Scribble CSS files in the main Racket repo,
>     I decided
>     > it would be more efficient to make a new repo to act as a
>     prototype (and
>     > serve it via github pages). That way, it's easier for others to
>     try the new
>     > CSS and report problems & suggestions. Once the changes look
>     good, I can put
>     > them into a pull request for the main repo.
>     >
>     > What I did is grab part of the docs from the built version of
>     5.90.0.9 and
>     > dropped that in the prototype repo. Then I edited the CSS files.
>     >
>     > The prototype repo is here:
>     >
>     > https://github.com/mbutterick/racket-doc-redo/tree/gh-pages
>     >
>     > To preview the pages in a web browser, start here:
>     >
>     > http://mbutterick.github.io/racket-doc-redo/doc/index.html
>     >
>     > This is my first attempt at using github pages, so if there's
>     breakage,
>     > blame me.
>     >
>     > As for the design changes, there's more refinement and
>     nitpickery to come,
>     > but the basic idea is intact, and good enough to criticize.
>     Mostly I've
>     > aimed to simplify and update the layout, while keeping the
>     character of the
>     > documentation intact. I've also tried to address one key functional
>     > shortcoming of the current CSS: its fixed width.
>     >
>     > And yes, it is somewhat less colorful overall, though not
>     because I oppose
>     > "the colors of the rainbow" ;) Rather, I just think the color
>     has better
>     > effect when it's used sparingly. Like a day spa for the mind.
>     >
>     > Matthew Butterick
>     >
>     >
>     >
>     >
>     > On Wed, Oct 16, 2013 at 3:41 PM, Robby Findler
>     <robby at eecs.northwestern.edu <mailto:robby at eecs.northwestern.edu>>
>     > wrote:
>     >>
>     >> I've just finished reading your (beautiful!) book and am
>     excitedly looking
>     >> forward to what you come up with. Do let us know if you get
>     stuck anywhere.
>     >> (And yes: we apparently like all the colors of the rainbow more
>     than you
>     >> seem to; hopefully you won't hold that against us :).
>     >>
>     >> Robby
>     >>
>     >>
>     >>
>     >> On Fri, Oct 11, 2013 at 5:35 PM, Matthew Butterick
>     >> <mb.list.acct at gmail.com <mailto:mb.list.acct at gmail.com>> wrote:
>     >>>
>     >>> Consistent with my pledge at RacketCon, I've been working on some
>     >>> potential improvements to the default CSS files used by
>     Scribble for Racket
>     >>> documentation. Before I get too far I just want to make sure
>     I'm going about
>     >>> it the right way.
>     >>>
>     >>> I've read the tutorials by Joe Politz and Greg Hendershott
>     about how to
>     >>> contribute to Racket via Github. I made a fresh fork of
>     plt/racket yesterday
>     >>> and built it from source. But the Scribble CSS files are
>     handled a little
>     >>> differently than others.
>     >>>
>     >>> I see that the documentation gets built into racket/racket/doc/,
>     >>> including the CSS files. So if I edit the files in that
>     directory, I can see
>     >>> the CSS changes reflected in the docs. However, the whole doc
>     directory is
>     >>> ignored in the git repo. And I need to edit files that git can
>     see.
>     >>>
>     >>> So I found the original home of the CSS files in
>     >>> racket/pkgs/scribble-pkgs/scribble-lib/scribble/. If I update
>     these files,
>     >>> then git sees them. But the changes aren't reflected in the live
>     >>> documentation.
>     >>>
>     >>> My workaround has just been to replace the copies in
>     racket/racket/doc
>     >>> with symlinks to the files in scribble-pkgs. That way, as I
>     update the CSS
>     >>> in scribble-pkgs, git can see the updates, but they're also
>     reflected in the
>     >>> live docs. (These symlinks will get wiped out next time I
>     rebuild from
>     >>> source, but that's the price of progress.)
>     >>>
>     >>>
>     >>> 1) What's the best way to propose Scribble CSS updates? Should
>     I assemble
>     >>> a pull request for
>     racket/pkgs/scribble-pkgs/scribble-lib/scribble/ ?
>     >>>
>     >>> 2) Is there a better way of connecting the CSS file in
>     scribble-pkgs to
>     >>> the actual CSS file used by the documentation? (i.e., other
>     than my symlink
>     >>> technique).
>     >>>
>     >>> 3) Anyone who wants to try out the new Scribble CSS files or
>     contribute
>     >>> to the update will have the same problem, however. I'm not
>     sure how to avoid
>     >>> this given that Scribble's HTML rendering policy is to bring
>     the CSS files
>     >>> along for the ride and eliminate dependency on the source
>     directory. OTOH,
>     >>> it's a drag to have to rebuild the docs just to see the effect
>     of a few CSS
>     >>> files.
>     >>>
>     >>> 4) For now I'm just working with the CSS, and not delving into the
>     >>> Scribble HTML renderer, on the idea that changing fewer files
>     is better, and
>     >>> maintaining compatibility with existing doc sources is
>     essential. That said,
>     >>> there are some occasional defects in the Scribble HTML output
>     that puts
>     >>> things out of reach of CSS (e.g., I've found styling
>     hard-coded into the
>     >>> HTML in places).
>     >>>
>     >>>
>     >>> Matthew Butterick
>     >>>
>     >>> ____________________
>     >>>   Racket Users list:
>     >>> http://lists.racket-lang.org/users
>     >>>
>     >>
>     >
>     >
>     > ____________________
>     >   Racket Users list:
>     > http://lists.racket-lang.org/users
>     >
>
>
>
>
> ____________________
>    Racket Users list:
>    http://lists.racket-lang.org/users

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20131110/9d069032/attachment-0001.html>