[plt-scheme] please help us scribble!

A couple things related to scribble for user documentation:

1. Is there a pdf version of the scribble manual?

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.

3. Are there any plans for equation rendering?

4. How will scribblings be used by PLaneT?  And, what will be the best way
to transition our documentation for the transition to V4?

Doug

On Jan 7, 2008 8:31 AM, Matthew Flatt <mflatt at cs.utah.edu> wrote:

> The three most important improvements in PLT Scheme v4 will be:
>
>  1. documentation (better organized)
>
>  2. documentation (more readable "guides" and examples)
>
>  3. documentation (better integration with tools like DrScheme)
>
> There are also some languages changes, such as the library
> reorganization and keyword arguments, but mostly those are in the
> service of better documentation.
>
> The new core documentation is starting to come together. The
> `scheme/base', `scheme', and `scheme/gui' languages are fairly
> thoroughly documented, for example, as are Scribble itself, the FFI,
> and Inside PLT Scheme. We have plenty of work to do on the guide, but
> that can improve and evolve after we get the reference documentation in
> place.
>
> One big remaining task is all of the "doc.txt" files --- former
> second-class citizens that need to ported as fully fledged, scribbled
> parts of the PLT documentation. We have considered trying to fit
> "doc.txt" files into the new documentation system, but it's awkward.
> Anyway, we want *good* documentation for everything, and that means
> scribbling it.
>
>
> We could use your help scribbling "doc.txt" files!
>
> See
>
>  http://www.cs.utah.edu/~mflatt/tmp/doc-to-do.txt<http://www.cs.utah.edu/%7Emflatt/tmp/doc-to-do.txt>
>
> for a list of things to be done. This is not a complete list; it's a
> list of documents that could easily be ported by someone other than the
> authors of the relevant libraries (who are either no longer active or
> have plenty of other documents to port).
>
>
> Here's how you can help:
>
>  * Pick a document (some are easier than others) that doesn't yet have
>   a name next to it, and send mail to claim it as your responsibility.
>
>   I recommend replying to this message and keeping the plt-scheme list
>   cc'ed, but if you're a bit shy (I would be), you can send mail
>   directly to me, and I'll quietly add your name next to a choice.
>
>  * Read the Scribble manual:
>
>     http://pre.plt-scheme.org/docs/html/scribble/
>
>   Chapter 1 will get you started, but you'll likely need to read
>   through Chapter 3. Pay attention to the style guide at the end of
>   Chapter 1:
>
>     http://pre.plt-scheme.org/docs/html/scribble/
>     How_to_Scribble_Documentation.html#(part~20reference-style)
>
>   There are lots of examples in the "scribblings" collection, which is
>   where the core doc sources reside.
>
>  * Port the "doc.txt" to "doc/manual.scrbl". You can call
>   "manual.scrbl" whatever you want, but "manual.scrbl" is a good
>   default, especially for single-file sources. Use multiple files
>   (with `include-section') if you think it's appropriate.
>
>   You'll need an "info.ss" file in your "doc" sub-collection so that
>   `setup-plt' will build the document. See "mrlib/doc/info.ss" for an
>   example.
>
>  * Re-read the style guide after you've scribbled. Probably you'll
>   notice things the second time around that affect the text that you
>   wrote or ported.
>
>  * E-mail me your scribblings as "doc.tgz" or "doc.zip". I will likely
>   edit for content and style, but you will have saved us a huge amount
>   of time by getting it mostly in shape --- and thus help get v4 out
>   the door sooner.
>
> Your reward will be a hearty "thanks!" from the PLT Scheme community, a
> place in an acknowledgments section, and the satisfaction of knowing
> that you've done your part.
>
> Longer term, we welcome contributions in the form of high-level
> explanations and examples to complement the reference documentation.
> For now, moving over the old documentation is our most pressing need.
>
> Thanks,
> Matthew
>
> _________________________________________________
>  For list-related administrative tasks:
>  http://list.cs.brown.edu/mailman/listinfo/plt-scheme
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20080107/76ff645b/attachment.html>