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

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/50481d52/attachment-0001.html>