[plt-scheme] PLaneT Packages with Scribbled Documentation

On 10/22/07, Doug Williams <m.douglas.williams at gmail.com> wrote:
> 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?

Unfortunately it will quietly ignore it, and I don't believe there's
anything I can do about that.

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

No. There may be a 4.0 split, but it won't work the same way as the
2xx/3xx split. Back then, I had thought of there being multiple
independent repositories each of which contained unrelated packages,
but I think that was a mistake in that it caused gratuitous
incompatibilities. Now an individual package can live in multiple
repositories.

> 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?

I don't know yet, but I very much hope the answer will be that
scribblings can refer to planet packages (including their own) freely.

> 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?

There's an unresolved bug with scribblings and planet packages at the
moment, so hold off on using it directly for now. There may be a way
to generate offline documentation using scribble, but I'll leave it to
someone else to say how to do that.

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

Again a question I should leave to others.

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

Not at the moment.

-jacob