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

Consistent with my pledge at
RacketCon<http://www.youtube.com/watch?v=20GGVNBykaw&list=PLXr4KViVC0qLyXpinlARzSDWaQTCzaGw3&index=7>,
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<http://blog.racket-lang.org/2012/11/tutorial-contributing-to-racket.html>and
Greg
Hendershott<http://www.greghendershott.com/2013/04/a-guide-for-infrequent-contributors-to-racket.html>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<https://github.com/plt/racket/blob/master/racket/.gitignore>.
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/<https://github.com/plt/racket/tree/master/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<https://github.com/plt/racket/tree/master/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<http://docs.racket-lang.org/scribble/running.html>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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20131011/80a1a695/attachment.html>