Just to underline the positive part of my comment: I used your version of the docs for awhile last night, for some real work.
When I eventually needed something that was outside what you opted to port in your test, and I had to go back to the old/real docs, I was bummed. I missed your new version. Very nice. On Sat, Nov 9, 2013 at 5:52 PM, Greg Hendershott <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> 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> >> 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> 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
