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.a...@gmail.com>wrote: > 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 > > ____________________ > Racket Users list: > http://lists.racket-lang.org/users > >
____________________ Racket Users list: http://lists.racket-lang.org/users
