[plt-scheme] Questions about PLaneT documentation options

From: Jacob Matthews (jacobm at cs.uchicago.edu)
Date: Sat Nov 6 11:34:54 EST 2004

On Fri, 5 Nov 2004, Williams, M. Douglas wrote:

> The doc.txt format isn't suitable for complete user documentation of complex
> collections.  Should I provide a doc.txt that provides rudimentary
> documentation?  Should doc.txt provide directions on getting the complete
> reference manual?  Should the pdf file be distributed as part of the
> collection?

Of course this is up to your preference, but the way I would do it is
distribute the pdf file as part of the collection and have a doc.txt file
that points people to the PDF. Advantages: it's easy to do, PLaneT
supports it right now, and you don't have to do a lot of work to make it
happen. Disadvantages: the Help Desk isn't ever going to be able to let
users search within that PDF for help on specific functions or features.

> The other alternative is to convert everything to HTML and use the doc
> collection.  Does PLaneT support downloading of HTML documentation and
> installation in the doc collection?  If not, what is the proper way to
> insure that the HTML documentation for a collection in PLaneT is tied to the
> PLT Scheme help system?

It doesn't at the moment, but expanding PLaneT's support for documentation
is one of my two top PLaneT goals at the moment. For now, there's not
really a good way to connect docs to planet packages in a way that works
well with the help desk. This will change in PLT Scheme v300.

-jacob


Posted on the users mailing list.