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

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
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20131113/379051bc/attachment-0001.html>