--- Stavros Macrakis <stavros.macrakis@verizon.net> wrote:
> I get the impression that at least six different kinds of
> documentation are being talked about here, each of which has
different
> requirements:
I should point out that a lot of the discussion here is just my
assumptions for what would be good to have/do. Those are obviously
open to challenge.
> 1) Systematic documentation for users. There might be a chapter on
> the various ways to pull apart Maxima expressions (part, inpart,
> pickapart, etc.) and how to use them. The existing texi files have a
> bit of this kind of material, though most of it is just reference
> material in alphabetical order, which is really type 2:
I think this type is pretty much what we've started to do in the user
manual, although it has a long way to go. (Incidently, if someone who
thoroughly understands the part stuff could write up a dummies guide
for that, I'd be grateful. The texi files do (IMHO) a less than
stellar job of explaining it.)
> 2) User reference documentation on individual functions. For
> example, how do you use the Part function, what are its arguments,
and
> are there any global variables that it depends on or sets? This
> should cross-reference the systematic documentation.
>
> 3) Systematic documentation for implementors of Maxima. This would
> have a chapter on internal representations, conventions for using
> them, utilities, and the relationship between the internal format and
> the usual input and output formats. Other chapters might cover how
> simplification works and how to write your own SIMP routines, how to
> use ASKSIGN and company, etc. Some of this material (incongruously)
> exists in the texi files.
I think two and three are two parts of what I've been thinking of as
the System Reference Manual, as opposed to the User Manual. Both parts
are critical.
> 4) Reference documentation for implementors of other parts of the
> system who might want to use a function. In the case of Part, it
> would probably say "Part should almost never be used by Lisp
programs;
> instead, they should analyze expressions themselves; see Chapter 3 of
> the Maxima implementors' manual." This is the usual role of
> docstrings. In my opinion, only a relatively small number of
> generally-useful functions (e.g. Alike1, Mul, Coeff, etc.) cry out
for
> this kind of documentation. Type (3) documentation is far more
> important than adding a docstring to every function in Maxima.
This would constitute part of a "Programmers Manual" I think. The line
between this and writing SIMP routines blurrs a bit.
Type three documentation is very important, I agree. Unfortunately, is
beyond my skill to write. We need someone who is very familiar with
Maxima at a low level and has time to write such documentation.
> 5) Documentation for maintainers of that particular function or
> module. This is usually done with inline documentation (semicolon
> comments), not docstrings. This is where information on the weird
and
> wonderful uses of Special variables and so on belongs (except when
> external users need to know about it).
That should work, but we have to be conservative on what we decide to
leave buried in the semicolon comments.
> 6) Cross-references, who calls what, who uses what global variable,
> etc. Very useful for people maintaining that code, and writing type
> (5) documentation. This really needs to be a dynamic tool, not a
> static listing. In the absence of the better things being proposed,
I
> use tags-search and tags-occur pretty heavily.
I guess now that I think about it the cross referencing would belong in
the Programmer Manual rather than System Reference. I have hopes that
the new CMUCL xref will be a big help in this task, and even though it
apparently can't parse all our files the CMU xref may also prove
useful.
The trick is figuring out some way to do the same thing for the .mac
files as well as the .lisp.
> In addition to documentation, it would be nice to have some
> systematic way of including test cases at the function and module
> level. Currently, we only have system-level tests (the Test
> directory). Tests can be useful not only for actual testing, but
also
> for reminding maintainers of difficult cases.
Hmm. Yes, that would be good, but I'm not sure how we could impliment
it.
I guess I'll sum up what I was imagining as a long term goal for how to
structure documentation, using the listed types above.
Three major works - User Manual, System Reference Manual, and
Programmer's Manual.
User Manual: Type 1 documentation. How to use the system and an
overview of it's abilities. Started in what we're calling the Maxima
Book.
System Reference Manual: 2 and 3. 2 might be generated at least
partially and maybe fully automatically by use of docstrings. The goal
for this book would be for any ordinary non-programming user who wants
to go beyond what is described in the User Manual to be able to find
the detail they need on a particular function here.
Programmer's Manual: 4 and 6, along with discussion of various concerns
with lisp versions, desirable coding style, things not to do, how to
write a share package, etc. This is for people who want to do
significant work with the intent of contributing to the Maxima project,
rather than simply telling people how to write SIMP routines. (A
balance will need to be found on where to put system programming vs.
advanced user programming, and how to define one as opposed to the
other. Not totally sure about that.)
In all cases it probably will make sense to add documentation about
share packages as an appended section, which each share package
defining its own documentation at each of the three levels. That will
hopefully eventually become the mark of a share package worth including
in the main distribution. (Beyond the obvious need for mathematical
merits.)
I do believe it is a worthwhile goal (if perhaps not an entirely
practical one) to have at least some kind of explanation for all the
functions in Maxima, but that is definitely less useful than
intelligent descriptions of how the system work. The latter, while
less boring to write, is also far more difficult.
CY
__________________________________________________
Do you Yahoo!?
Yahoo! Mail Plus - Powerful. Affordable. Sign up now.
http://mailplus.yahoo.com