[plt-scheme] PLaneT Packages with Scribbled Documentation

From: Doug Williams (m.douglas.williams at gmail.com)
Date: Mon Oct 22 12:56:31 EDT 2007

I have a couple questions about how PLaneT packages with scribbled
documentation will work.  I guess most of these are for Jacob, but I welcome
input/opinions from anyone.

1. Will there be some backward compatible mechanism so that new (or updated)
PLaneT packages with scribbled documentation can be loaded in older PLT
Scheme instances?  Specifically, what will happen when someone is running
V370 (or V360, whenever the cutover is/was) and requires a PLaneT packages
with scribbled documentation?  Will it warn about the scribblings entry in
info.ss, quietly ignore it (and not load the documentation), or something
else?

2. Will there be a new PLaneT repository for post-scribble PLaneT packages -
similar to the 2xx/3xx split now?

3. If we have examples in a PLaneT package that refer to that package
itself, will this be loaded properly?  That is, can an example in the
scribbled documentation within a PLaneT package that contains a require for
that package be run within scribble to produce the output?  Alternatively,
will the documentation have to be static and contain the expected results -
the way we (or at least I) do it now?

4. Should we avoid even trying to upgrade to scribble for released packages
for now?  Or, is there a safer way to start with scribbled documentation?
For example, can we develop scribbled documentation, generate the HTML, and
manually add it to the package before creating the .plt file?

5. Are there any PLaneT packages currently using scribbled documentation we
can look at for guidance?

6. Have the PLT guys thought about any 'standards' for developing the
scribbled documentation?

7. Are there any plans to have PLaneT automatically generate a pdf file for
those who want better hardcopy documentation?

I'm sure I'll come up with others as I dig into it more.

Doug
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20071022/7cb36544/attachment.html>

Posted on the users mailing list.