On 10/29/09, Stavros Macrakis <macrakis at alum.mit.edu> wrote:
> 1) When a loadfile changes name, leave a stub behind with the old name that
> prints a warning that the file has been moved, and then loads it from the
> new location. This is easy to do.
Agreed.
> 2) Include at least a one-line description of all share functions (not
> including contrib) in the main help library, mentioning what file to load
> them from. This requires some labor, but not specialized knowledge.
I wouldn't mind seeing a documentation summary function,
not limited to share functions. E.g. print just the name of a
function and the first line of documentation.
If it isn't built-in, mention what to load as well (not sure how to
detect that automatically).
> 3) Add some specific help functionality to help find share files. This
> requires some programming as well as as more documentation data.
Well, in the html documentation at least, there is a category
for share packages. At present all that is shown is a list of links
(as with all categories); maybe it should show a 1-line summary
as in (2). If the category system is generally useful, maybe we
can somehow adapt it to the "describe" system.
> 4) When a load file is loaded, full documentation should come with it. I
> haven't looked at the help system, so I don't know how hard this would be.
Well, my preference here is that a share package should own its
own documentation (i.e. source code, test script, & documentation
all in the same directory). I figured out a way to get the per-package
Texinfo documentation merged into the general Texinfo index so that
it would be known to "describe".
At that point someone else argued that the Texinfo documentation
for all packages should be in the same place (maxima/doc/info)
and I didn't feel like arguing the point so I gave up. But it would
be easy to resurrect the per-package info stuff.
I think it should be possible to read a package's documentation
without loading the package, by the way.
> 5) Add some easy way to load up-to-date share files from the sourceforge
> server without requiring CVS knowledge. The R system includes functions to
> install and update packages (and their prerequisites) so you neither have to
> be a systems programmer nor have to reinstall the whole system every time
> one package is updated. This requires real work, especially if it's going to
> be cross-platform.
I think we should just create a simplified CVS client (might or
might not be Lisp). Trying to figure out a separate scheme seems
like a waste of time.
best
Robert Dodier