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

Establishing a max width is definitely something that we want to do. I see
now that I was confused by the two different failure modes. I've pushed a
fix for the contract-out docs.

Thanks,
Robby


On Sun, Nov 10, 2013 at 12:01 AM, Matthew Butterick <mb at mbtype.com> wrote:

> On Sat, Nov 9, 2013 at 8:44 AM, Robby Findler <robby at eecs.northwestern.edu
> > wrote:
>
>
>> A technical question: in the docs for contract-out (
>> http://mbutterick.github.io/racket-doc-redo/doc/reference/attaching-contracts-to-values.html),
>> I see that the code oversteps its box in the new version, but not the old.
>> Is that something we'd have to fix by editing the docs to make the lines
>> have fewer chars in them?
>>
>
>
> The current CSS is ambiguous about the policy & intended result.
>
> The code samples are inside a table (class Rboxed) that expands as needed
> to accommodate the width of the code. But this table is inside a div (class
> SVInsetFlow) that's intended to be no wider than the main column (but does
> not actually clip the table).
>
> As a matter of CSS, it's simple to make this look right (by applying the
> background fill to the table rather than the div).
>
> Whether this is desirable as a matter of Racket documentation policy is a
> broader issue. Scribble files are meant to be renderable to multiple
> targets. But if there's no established max width for code samples, it makes
> life difficult for those who want to write new renderers (or CSS styles or
> PDF styles), because code samples can't be soft-wrapped. Thus a
> sufficiently motivated writer of docs can break any renderer just by making
> a ludicrously wide code sample.
>
> So while one wants to avoid pushing design constraints onto writers, code
> samples are special, thus it would be useful to adopt a max width.
>
>
> PS As for the specific page you mention, I notice that it's gotten wider
> compared to the current web docs:
>
> http://docs.racket-lang.org/reference/attaching-contracts-to-values.html
>
>
>
>
>
>
>
>
>
>
>
> On Sat, Nov 9, 2013 at 8:44 AM, Robby Findler <robby at eecs.northwestern.edu
> > wrote:
>
>> I like it! Making the window smaller and see the font shrink is
>> especially amazing.
>>
>> A technical question: in the docs for contract-out (
>> http://mbutterick.github.io/racket-doc-redo/doc/reference/attaching-contracts-to-values.html),
>> I see that the code oversteps its box in the new version, but not the old.
>> Is that something we'd have to fix by editing the docs to make the lines
>> have fewer chars in them?
>>
>> Also, the margin comment in the "Set..." section here
>> http://mbutterick.github.io/racket-doc-redo/doc/quick/index.html seems
>> to have moved into the middle of the page.
>>
>> Robby
>>
>>
>> On Sat, Nov 9, 2013 at 1: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<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
>>>
>>>
>>
>
>
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20131110/fdb72ef2/attachment.html>