A couple things related to scribble for user documentation:<br><br>1. Is there a pdf version of the scribble manual?<br><br>2. Is there a good way yet to include graphics in scribbled documents? I haven't looked at the manual in a couple months, but it wasn't obvious back then and no one came forward with any suggestions on the mailing list at the time.
<br><br>3. Are there any plans for equation rendering? <br><br>4. How will scribblings be used by PLaneT? And, what will be the best way to transition our documentation for the transition to V4?<br><br>Doug<br><br><div class="gmail_quote">
On Jan 7, 2008 8:31 AM, Matthew Flatt <<a href="mailto:firstname.lastname@example.org">email@example.com</a>> wrote:<br><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
The three most important improvements in PLT Scheme v4 will be:<br><br> 1. documentation (better organized)<br><br> 2. documentation (more readable "guides" and examples)<br><br> 3. documentation (better integration with tools like DrScheme)
<br><br>There are also some languages changes, such as the library<br>reorganization and keyword arguments, but mostly those are in the<br>service of better documentation.<br><br>The new core documentation is starting to come together. The
<br>`scheme/base', `scheme', and `scheme/gui' languages are fairly<br>thoroughly documented, for example, as are Scribble itself, the FFI,<br>and Inside PLT Scheme. We have plenty of work to do on the guide, but
<br>that can improve and evolve after we get the reference documentation in<br>place.<br><br>One big remaining task is all of the "doc.txt" files --- former<br>second-class citizens that need to ported as fully fledged, scribbled
<br>parts of the PLT documentation. We have considered trying to fit<br>"doc.txt" files into the new documentation system, but it's awkward.<br>Anyway, we want *good* documentation for everything, and that means
<br>scribbling it.<br><br><br>We could use your help scribbling "doc.txt" files!<br><br>See<br><br> <a href="http://www.cs.utah.edu/%7Emflatt/tmp/doc-to-do.txt" target="_blank">http://www.cs.utah.edu/~mflatt/tmp/doc-to-do.txt
</a><br><br>for a list of things to be done. This is not a complete list; it's a<br>list of documents that could easily be ported by someone other than the<br>authors of the relevant libraries (who are either no longer active or
<br>have plenty of other documents to port).<br><br><br>Here's how you can help:<br><br> * Pick a document (some are easier than others) that doesn't yet have<br> a name next to it, and send mail to claim it as your responsibility.
<br><br> I recommend replying to this message and keeping the plt-scheme list<br> cc'ed, but if you're a bit shy (I would be), you can send mail<br> directly to me, and I'll quietly add your name next to a choice.
<br><br> * Read the Scribble manual:<br><br> <a href="http://pre.plt-scheme.org/docs/html/scribble/" target="_blank">http://pre.plt-scheme.org/docs/html/scribble/</a><br><br> Chapter 1 will get you started, but you'll likely need to read
<br> through Chapter 3. Pay attention to the style guide at the end of<br> Chapter 1:<br><br> <a href="http://pre.plt-scheme.org/docs/html/scribble/" target="_blank">http://pre.plt-scheme.org/docs/html/scribble/</a>
<br> How_to_Scribble_Documentation.html#(part~20reference-style)<br><br> There are lots of examples in the "scribblings" collection, which is<br> where the core doc sources reside.<br><br> * Port the "
doc.txt" to "doc/manual.scrbl". You can call<br> "manual.scrbl" whatever you want, but "manual.scrbl" is a good<br> default, especially for single-file sources. Use multiple files<br>
(with `include-section') if you think it's appropriate.<br><br> You'll need an "info.ss" file in your "doc" sub-collection so that<br> `setup-plt' will build the document. See "mrlib/doc/info.ss" for an
<br> example.<br><br> * Re-read the style guide after you've scribbled. Probably you'll<br> notice things the second time around that affect the text that you<br> wrote or ported.<br><br> * E-mail me your scribblings as "
doc.tgz" or "doc.zip". I will likely<br> edit for content and style, but you will have saved us a huge amount<br> of time by getting it mostly in shape --- and thus help get v4 out<br> the door sooner.
<br><br>Your reward will be a hearty "thanks!" from the PLT Scheme community, a<br>place in an acknowledgments section, and the satisfaction of knowing<br>that you've done your part.<br><br>Longer term, we welcome contributions in the form of high-level
<br>explanations and examples to complement the reference documentation.<br>For now, moving over the old documentation is our most pressing need.<br><br>Thanks,<br>Matthew<br><br>_________________________________________________
<br> For list-related administrative tasks:<br> <a href="http://list.cs.brown.edu/mailman/listinfo/plt-scheme" target="_blank">http://list.cs.brown.edu/mailman/listinfo/plt-scheme</a><br></blockquote></div><br>