Hi, all,
There has been some talk about how to deliver documentation. You all
might want to take a look at R ( at http://cran.r-project.org/ ). This
has a really slick documentation facility, which includes their function
package.skeleton(), which takes a list of functions, data sets, and so
on, and produces, among other things, template files for the programmer
to fill out for each of them. This eases the task of documenting what
you've done. R has some of the best help files I've seen, and I suspect
that this is why.
The really slick part is the delivery. When a package is installed part
of the job is to generate dvi and html documentation from the
document.Rd files (except on windows, I gather). The .Rd files have a
markup language which is essentially LaTeX. What I mean by that is that
it uses the LaTeX syntax in a way that causes no surprises to me where
it can be rendered sensibly in html, and lets you embed real LaTeX code
for equations, e.g., \eqn{put the latex version here}{put the ascii
version here} will give the dvi file the proper equation and will give
the best approximation you can dream up for the html file.
When you execute the function help.start(), R starts a browser
(typically netscape) which displays the html help pages. The dvi pages
are generated from the same files, so there is never a problem with the
two being out of sync.
R is GPL'ed, so copying would be easy, except that it's not written in
Lisp. I am fairly sure, from what I remember of the documentation, that
the facilities for building the help files are written in Perl. I would
think that requiring Perl is not unreasonable on a Unix system. Windows
will simply have to have binaries with no building required, anyway.
I hope that this gives you all some usable ideas.
Nels
maxima-request@www.ma.utexas.edu wrote:
[lots of stuff...]