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

At Fri, 11 Oct 2013 15:35:38 -0700, Matthew Butterick wrote:
> I’ve been working on some potential improvements to the default CSS
> files used by Scribble for Racket documentation.

Great!

A few weeks ago, I started documenting the styles that Scribble uses,
but I ran out of time.

The enclosed document is meant to demonstrate every style used by
`scribble/base` and defined in "scribble.css", so it may be useful. Try
rendering it both in single-page mode and multi-page mode.

I didn't get as far as documenting the styles used by `scribble/racket`
and defined in "racket.css".

> 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.

Running `raco setup` should copy a changed "scribble.css" into place.
That's a lot slower than just copying manually, though.

> 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.)

That sounds fine. Another possibility is to put your changes in
"doc-site.css" while you're developing them --- because "doc-site.css"
is never replaced if it exists, it's created as an empty file if it
doesn't exist, and it is loaded after "scribble.css" with the intent of
allowing site-specific customization --- and then copy to
"scribble.css" when you're done.

(The "doc-site.css" file is new in v5.90.x.)

> 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/t
> ree/master/pkgs/scribble-pkgs/scribble-lib/scribble>/
> ?

That would be great.

> 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).

Your technique may be best for now.

> 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.

Having others try out styles as "doc-site.css" is probably best.

> 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).

Changes to the renderer to make the output more configurable would be
welcome. There's a backward-compatibility issue, in that others have
style files that replace "scribble.css" for their documents; if you can
keep that in mind and minimize incompatibilities, so much the better.

Thanks!!
-------------- next part --------------
A non-text attachment was scrubbed...
Name: ex.scrbl
Type: application/octet-stream
Size: 9931 bytes
Desc: not available
URL: <http://lists.racket-lang.org/users/archive/attachments/20131011/a0e97911/attachment-0001.obj>