<div dir="ltr">Establishing a max width is definitely something that we want to do. I see now that I was confused by the two different failure modes. I've pushed a fix for the contract-out docs.<div><br></div><div>Thanks,</div>
<div><div><div><div>Robby</div></div></div></div></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Sun, Nov 10, 2013 at 12:01 AM, Matthew Butterick <span dir="ltr"><<a href="mailto:mb@mbtype.com" target="_blank">mb@mbtype.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">On Sat, Nov 9, 2013 at 8:44 AM, Robby Findler <span dir="ltr"><<a href="mailto:robby@eecs.northwestern.edu" target="_blank">robby@eecs.northwestern.edu</a>></span> wrote:<div class="im">
<br><div class="gmail_extra"><div class="gmail_quote">
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr"><div><br></div><div>A technical question: in the docs for contract-out (<a href="http://mbutterick.github.io/racket-doc-redo/doc/reference/attaching-contracts-to-values.html" target="_blank">http://mbutterick.github.io/racket-doc-redo/doc/reference/attaching-contracts-to-values.html</a>), I see that the code oversteps its box in the new version, but not the old. Is that something we'd have to fix by editing the docs to make the lines have fewer chars in them?</div>
</div></blockquote></div></div><div><br></div><div><br></div></div><div>The current CSS is ambiguous about the policy & intended result. </div><div><br></div><div>The code samples are inside a table (class Rboxed) that expands as needed to accommodate the width of the code. But this table is inside a div (class SVInsetFlow) that's intended to be no wider than the main column (but does not actually clip the table). </div>
<div><br></div><div>As a matter of CSS, it's simple to make this look right (by applying the background fill to the table rather than the div). </div><div><br></div><div>Whether this is desirable as a matter of Racket documentation policy is a broader issue. Scribble files are meant to be renderable to multiple targets. But if there's no established max width for code samples, it makes life difficult for those who want to write new renderers (or CSS styles or PDF styles), because code samples can't be soft-wrapped. Thus a sufficiently motivated writer of docs can break any renderer just by making a ludicrously wide code sample. </div>
<div><br></div><div>So while one wants to avoid pushing design constraints onto writers, code samples are special, thus it would be useful to adopt a max width.</div><div><br></div><div><br></div><div>PS As for the specific page you mention, I notice that it's gotten wider compared to the current web docs:</div>
<div><br></div><div><a href="http://docs.racket-lang.org/reference/attaching-contracts-to-values.html" target="_blank">http://docs.racket-lang.org/reference/attaching-contracts-to-values.html</a><br></div><div><div class="h5">
<div><br></div><div><br></div><div>
<br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br>
</div><div><br></div>On Sat, Nov 9, 2013 at 8:44 AM, Robby Findler <span dir="ltr"><<a href="mailto:robby@eecs.northwestern.edu" target="_blank">robby@eecs.northwestern.edu</a>></span> wrote:<br><div class="gmail_extra">
<div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">I like it! Making the window smaller and see the font shrink is especially amazing.<div>
<br></div><div>A technical question: in the docs for contract-out (<a href="http://mbutterick.github.io/racket-doc-redo/doc/reference/attaching-contracts-to-values.html" target="_blank">http://mbutterick.github.io/racket-doc-redo/doc/reference/attaching-contracts-to-values.html</a>), I see that the code oversteps its box in the new version, but not the old. Is that something we'd have to fix by editing the docs to make the lines have fewer chars in them?</div>
<div><br></div><div>Also, the margin comment in the "Set..." section here <a href="http://mbutterick.github.io/racket-doc-redo/doc/quick/index.html" target="_blank">http://mbutterick.github.io/racket-doc-redo/doc/quick/index.html</a> seems to have moved into the middle of the page.</div>
<span><font color="#888888">
<div><br></div><div>Robby</div></font></span></div><div class="gmail_extra"><br><br><div class="gmail_quote"><div>On Sat, Nov 9, 2013 at 1:12 AM, Matthew Butterick <span dir="ltr"><<a href="mailto:mb.list.acct@gmail.com" target="_blank">mb.list.acct@gmail.com</a>></span> wrote:<br>
</div><div><div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">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. <div>
<br></div><div>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. </div><div><br></div><div>The prototype repo is here:</div><div><br>
</div><div><a href="https://github.com/mbutterick/racket-doc-redo/tree/gh-pages" target="_blank">https://github.com/mbutterick/racket-doc-redo/tree/gh-pages</a><br></div><div><br></div><div>To preview the pages in a web browser, start here:</div>
<div><br></div><div><a href="http://mbutterick.github.io/racket-doc-redo/doc/index.html" target="_blank">http://mbutterick.github.io/racket-doc-redo/doc/index.html</a><br></div><div><br></div><div>This is my first attempt at using github pages, so if there's breakage, blame me.</div>
<div><br></div><div>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. </div>
<div><br></div><div>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.</div>
<span><font color="#888888">
<div><br></div><div>Matthew Butterick<br></div></font></span><div><div><div><br></div><div><br></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Wed, Oct 16, 2013 at 3:41 PM, Robby Findler <span dir="ltr"><<a href="mailto:robby@eecs.northwestern.edu" target="_blank">robby@eecs.northwestern.edu</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div dir="ltr">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 :).<div>
<br></div><div>Robby</div><div><br></div></div><div class="gmail_extra"><br><br><div class="gmail_quote"><div><div>On Fri, Oct 11, 2013 at 5:35 PM, Matthew Butterick <span dir="ltr"><<a href="mailto:mb.list.acct@gmail.com" target="_blank">mb.list.acct@gmail.com</a>></span> wrote:<br>
</div></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex"><div><div><div dir="ltr">Consistent with my <a href="http://www.youtube.com/watch?v=20GGVNBykaw&list=PLXr4KViVC0qLyXpinlARzSDWaQTCzaGw3&index=7" target="_blank">pledge at RacketCon</a>, 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.<div>
<br><div>I've read the tutorials by <a href="http://blog.racket-lang.org/2012/11/tutorial-contributing-to-racket.html" target="_blank">Joe Politz</a> and <a href="http://www.greghendershott.com/2013/04/a-guide-for-infrequent-contributors-to-racket.html" target="_blank">Greg Hendershott</a> 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.</div>
</div><div><br></div><div>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 <a href="https://github.com/plt/racket/blob/master/racket/.gitignore" target="_blank">ignored in the git repo</a>. And I need to edit files that git can see. </div>
<div><br></div><div>So I found the original home of the CSS files in <a href="https://github.com/plt/racket/tree/master/pkgs/scribble-pkgs/scribble-lib/scribble" target="_blank">racket/pkgs/scribble-pkgs/scribble-lib/scribble/</a>. If I update these files, then git sees them. But the changes aren't reflected in the live documentation.<br>
</div><div><br></div><div>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.)</div>
<div><br></div><div><br></div><div>1) What's the best way to propose Scribble CSS updates? Should I assemble a pull request for <a href="https://github.com/plt/racket/tree/master/pkgs/scribble-pkgs/scribble-lib/scribble" target="_blank">racket/pkgs/scribble-pkgs/scribble-lib/scribble</a>/ ?</div>
<div><br></div><div>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). </div><div><br></div><div>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 <a href="http://docs.racket-lang.org/scribble/running.html" target="_blank">HTML rendering policy</a> 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.</div>
<div><br></div><div>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). </div>
<span><font color="#888888">
<div><br></div><div><br></div><div>Matthew Butterick<br></div></font></span></div>
<br></div></div>____________________<br>
Racket Users list:<br>
<a href="http://lists.racket-lang.org/users" target="_blank">http://lists.racket-lang.org/users</a><br>
<br></blockquote></div><br></div>
</blockquote></div><br></div></div></div></div>
<br>____________________<br>
Racket Users list:<br>
<a href="http://lists.racket-lang.org/users" target="_blank">http://lists.racket-lang.org/users</a><br>
<br></blockquote></div></div></div><br></div>
</blockquote></div><br></div><div class="gmail_extra"><br></div></div></div></div>
<br>____________________<br>
Racket Users list:<br>
<a href="http://lists.racket-lang.org/users" target="_blank">http://lists.racket-lang.org/users</a><br>
<br></blockquote></div><br></div>