[racket-dev] Cross-Collection Documentation - a PLaneT Philosophy Question (or Two)

On Thu, Sep 22, 2011 at 8:54 AM, Doug Williams
<m.douglas.williams at gmail.com> wrote:
> I have three PLaneT packages that together implement a knowledge-based
> simulation capability. I did this because each of the packages is useful in
> its own right. The science collection provides the basic mathematical
> framework - I use it separately in many analysis applications. The
> simulation collection provides a hybrid discrete-event and continuous
> simulation engine. The inference collection provides a hybrid
> forward-chaining and backward-chaining inference engine.
>
> Although they were developed together and I often use them together, they
> are separate collections. As such, they are documented separately and the
> examples in each are specific to that collection. Now, I have written a good
> example knowledge-based simulation that cuts across all of them and I am
> planning on developing documentation on how to use the packages together.
> Should I package this up as a PLaneT package itself although it doesn't add
> any new functionality? Is there a better way to distribute something like
> this - more like an application note than an applicaton? It seems to be the
> only way to do it in the current framework. [It will be in the Schematics
> repository on Sourceforge. But I pretty much just use that as my development
> repository.]

I think the best thing, for now, is to make a new planet package. I
don't know if the new planned planet 2.0 would have a better answer
for this or not.

> Also, when using the simulation collection one (almost) always uses the
> random distributions from the science collection. In my development branch,
> I have now just re-exported the random distributions in the science
> collection from the simulation collection. Thus, I only have the one PLaneT
> require in user code instead of two. [I don't want to move the random
> distributions to the simulation collection because they really are part of
> the mathematical framework and logically belong in the science collection.]
> Is this going to bite me later if someone needs other elements of the
> science collection and does a separate require - i.e., will the names
> conflict even though they are (ultimately) the same objects?

If the exports are re-exports from another file (say using (provide
(all-from-out ...))), then there are no conflicts and no worries.

If they are re-exported with, say, different contracts, then you get
different bindings and your clients would have to use a prefix on the
import or something like that to have all of the bindings in the same
file.

If you want to support mixing and matching of planet versions (e.g.
use a recent version of the simulation collection and an old version
of the science collection) then you could run into problems as you
would have two different versions of the same planet package
instantiated in a single namespace. Planet doesn't allow that by
default, but you can add declarations to your planet package to
explicitly allow that.

Robby