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
<greghendersh...@gmail.com <mailto:greghendersh...@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.a...@gmail.com <mailto:mb.list.a...@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
<ro...@eecs.northwestern.edu <mailto:ro...@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.a...@gmail.com <mailto:mb.list.a...@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
