C Y <smustudent1@yahoo.com> writes:
> --- Jesper Harder <harder@ifa.au.dk> wrote:
> [docstrings]
>
> My main concern is that we have a framework within which we need to
> work - namely the describe command in maxima. Ideally I'd like the
> comments we have in the source code documenting functions serve a dual
> purpose as the material for the describe command and the system
> manual. Would documentaion strings allow us to do that?
Yes. But whether they're a good idea might depend on how good we'd like
the manual to be.
If we want to put the documentation in the source, then I think
doc-strings is the obvious approach to try.
The drawback is that manuals produced this way are usually not as good
as the ones written separately from source documentation. They're
useful but not excellent -- it's hard to write a really good coherent
document, when the content is scattered across hundreds of source files.
(although there are some notable exceptions, such as The TeX book).
> I definitely want to avoid inventing a new method if possible. It looks
> like acl2 successfully makes use of doc strings, so that might be a
> guide, but we would need to be sure we can both use our describe system
> with doc-string information
The doc-strings are already available from Maxima, try:
(C1) :lisp (documentation '$context 'variable)
> and generate texi source from it in some systematic fashion. I don't
> know how much work that would be, but I suppose it is doable.
Extracting doc-strings and converting to texi is pretty easy. Try this
from the Maxima Lisp prompt:
(with-open-file (s (merge-pathnames "maxima-vars.texi") :direction :output :if-exists :supersede)
(do-symbols (var (find-package 'maxima))
(when (documentation var 'variable)
(format s "@defvar ~A~%~A~%@end defvar~2%" var
(documentation var 'variable)))))
which extracts doc-strings from all Maxima variables that have one and
writes them to the file 'maxima-vars.texi'. This is nearly a valid
Texinfo file. You just need to take care of characters which are
special in Texinfo, such as '{', '}' and '@'.
It doesn't address how to arrange the descriptions in a meaningful way
into chapters and sections, though.
> Is there a good tutorial on using doc strings somewhere?
There isn't a lot to learn :-) If you supply a doc-string when a function
(or variable etc) is defined, e.g.
(defun foo ()
"This function always returns T."
t)
then that doc-string is available with the 'documentation' function:
* (documentation 'foo 'function)
==> "This function always returns T."