--- Jesper Harder <harder@ifa.au.dk> wrote:
> 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).
What I had in mind (again this is just me waving my hands) is to
document each function/variable at a local level, generate chapters
from that, and then at the beginning write the bird's eye overview of
how the pieces fit together. Or maybe discuss the overall setup at the
beginning of each chapter. That way if one wants the specifics on a
particular function they can go straight to it and get the details. The
user manual will (someday) do the job of being a coherent discussion of
the system and how to use it - the system manual is to document all the
nasty little details that make up the program. The only real trick
will be organizing where each function should show up in the system
manual. See below for my thinking on that.
> > 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)
Right, but the avarage end user isn't gonna like that unless they're
all as smart as Richard :-). We'll have to juice up the describe
command to handle that stuff. Shouldn't be too hard from the looks of
that example. Or maybe we could parse to info format. Anyway one of
the two will work.
> > 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 '@'.
Sweet!! That's a very encouraging sign :-).
> It doesn't address how to arrange the descriptions in a meaningful
> way into chapters and sections, though.
Ah, there's the rub. And it also brings up indirectly another question
- whether or not you can have multiple line doc strings. I.e., can we
do something like:
(defun foo ()
"Author: John Doe
Functionality: This function always returns T."
t)
It's possible to get by without it but that means the output will need
to be formatted at another level to avoide having one long string
appear onscreen.
As for chapter layout, my idea works something like the following:
define a local variable in each function/variable/etc. called topic or
chapter or something, and assign it a value like integration,
simplification, general, etc - something that makes sense. Then when
we go to generate the texi stuff, we check for each function what it's
chapter variable is, and assign it to the proper place according to
that variable. It's drawback is that it is somewhat inflexible if we
want to reorganize things, but since if we wanted to do that we'd have
to re-evaluate everything anyway I suspect it's about as good as we
will get. Hopefully if we are careful with our initial organization we
will only need to do it once, and new stuff will either fit into an
established category or work in it's own.
Does that sound workable or am I up too late again? :-)
> > 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."
Boy, I wish more of this was that straightforward! Awesome stuff
Jesper!
CY
__________________________________________________
Do you Yahoo!?
Yahoo! Mail Plus - Powerful. Affordable. Sign up now.
http://mailplus.yahoo.com