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

First, this is great!  I tried it on my Nexus 7 tablet, and it worked very well.

Second, a very minor bug: on Chrome on the Nexus 7 (but not on Chrome
on my desktop, or on Firefox on the tablet), the grey search box when
you scroll down doesn't quite go down far enough -- the "p" in "up"
extends below the grey.

Sam

On Sat, Nov 9, 2013 at 2:12 AM, Matthew Butterick
<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>
> 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> 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
>