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

Just to underline the positive part of my comment:

I used your version of the docs for awhile last night, for some real work.

When I eventually needed something that was outside what you opted to
port in your test, and I had to go back to the old/real docs, I was
bummed. I missed your new version.

Very nice.


On Sat, Nov 9, 2013 at 5:52 PM, Greg Hendershott
<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> 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
>>