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

I know, but I don't want to do that in general :)


On Thu, Nov 14, 2013 at 1:34 PM, Robby Findler
<robby at eecs.northwestern.edu>wrote:

> Does it help to make your browser window smaller?
>
> Robby
>
>
> On Thu, Nov 14, 2013 at 2:40 AM, Laurent <laurent.orseau at gmail.com> wrote:
>
>> For me, the font is slightly too big.
>> I prefer 1.1rem instead of 1.18.
>>  I had noticed that the first time, thought I could deal with it with
>> time, but now that I come back to it I still find it too big.
>> (Plus, a bit smaller looks more professional/less childish to me).
>> But maybe I'm the only one in this case?
>>
>> I also agree with David that it's sometimes not sufficiently contrasted.
>> Also, depending on the ambient light and on the video device (projectors
>> often are much less contrasted than screens), it's more or less readable.
>>
>> Otherwise I still like it :)
>>
>> Laurent
>>
>>
>> On Thu, Nov 14, 2013 at 3:55 AM, Matthew Butterick <mb at mbtype.com> wrote:
>>
>>> I've made a number of updates to the Scribble CSS, and posted more
>>> sample docs, if you care to revisit:
>>>
>>> http://mbutterick.github.io/racket-doc-redo/doc/
>>>
>>>
>>> As for the specific requests & suggestions, I considered them all, tried
>>> most of them, and left in the ones that worked best, e.g.—
>>>
>>> + search box & prev/next buttons are no longer fixed to the top left
>>> corner.
>>> + less gray & more color, especially for the definition boxes.
>>> + interior cross-reference links are no longer bold, & are colored.
>>> + TOC bar goes away on narrow windows, yielding a one-column layout
>>> + white lines separate elements in @deftogether
>>>
>>> Still have some issues to fix (e.g., not all the boxes in "How to
>>> Program Racket" are working right yet [1]) but if you find lurking horrors,
>>> let me know. Thanks for your help.
>>>
>>>
>>> [1]
>>> http://mbutterick.github.io/racket-doc-redo/doc/style/Choosing_the_Right_Construct.html
>>>
>>>
>>>
>>>
>>>
>>>
>>> On Sun, Nov 10, 2013 at 1:28 PM, David Vanderson <
>>> david.vanderson at gmail.com> wrote:
>>>
>>>>  This is amazing! Thank you very much!
>>>>
>>>> Given all the little rendering things that people are pointing out, I
>>>> should say that the docs are currently using a transitional DOCTYPE, which
>>>> could be part of the problem. You probably have good reasons for it, but I
>>>> thought I'd mention it just in case.
>>>>
>>>> Thanks again!
>>>> Dave
>>>>
>>>>
>>>> On 11/10/2013 12:16 AM, Matthew Butterick wrote:
>>>>
>>>>  Thank you for the comments so far. As for the gentleman who was
>>>> "reluctant to say anthing negative," please don't be — the point of making
>>>> a prototype is to find out what doesn't work.
>>>>
>>>>  I won't cover every suggestion here on the mailing list because it
>>>> will become unwieldy. But I'll move the trickier topics onto the github
>>>> repo as issues, and those interested can comment further there.
>>>>
>>>>
>>>>
>>>>
>>>> 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
>>>>> >
>>>>>
>>>>
>>>>
>>>>
>>>> ____________________
>>>>   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
>>>
>>>
>>
>> ____________________
>>   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/20131114/4a672706/attachment-0001.html>