Hi!
I'm going to propose some modification to Maxima
reference manual which is inspired by commercial
Macsyma documentation (Macsyma ref. manual ver.13
and 16).
Disclaimer: I'm not going to discuss nice
TeX-formatted examples but only simple plain text
reference manual. IMHO The time for nicely
formatted manual will come when Maxima will acquire
standard graphical frontend. At present plain text
info together with describe on line search capabilities
have some indispensable advantages.
Now to the proposal. At present Maxima reference
manual is a collection of articles. Each article
describe one Maxima object. There are only two
types of articles and at the texinfo level they
look as follows:
@defun foo (exp)
Description of the function foo ...
...
...
@end defun
@defvar bar
Description of the variable bar ...
...
...
@end defvar
Built-in texinfo commands @defun and @defvar
automatically format articles according to
some standard style
*foo* /(expr) / Function
*bar* Variable
for HTML or printed documentation (TeX) or
- Function: foo (exp)
- Variable: bar
in info.
In addition @defvar and @defun take care about index automatically
inserting foo and bar to predefined texinfo indices fn (function index)
and vr (variables index). Maxima manual merges these two indices
into one. Resulting fn index contains reference to all objects.
This scheme works perfectly well. The only trouble is that having
just two categories of objects - Functions and Variables is not adequate.
There are at least 10 object types:
1. Functions - functions (sin, cos, bessel...)
2. Special forms - similar to functions but handle arguments in some
special nonstandard way (e.g. declare)
3. Symbols - %e, %i, %pi, inf ...
4. Option variables - variables whose value control Maxima behavior
(e.g. logexpand).
5. System variables - usually read only variables which contain information
about current Maxima state (e.g. functions).
6. Properties - named attributes of symbols.
7. Keywords - optional argument to function or special form which
modifies its behavior.
8. Keyword forms - like keyword but more complicated in structure than
9. Operators - operators. Can be further subdivided into prefix,
infix and postfix operators.
10. Packages - packages in share.
This diversified classification of Maxima objects
can be implemented by very simple way and virtually
require no special efforts.
The point is that commands @defun and @defvar are specialized
forms of more general commands @deffn and @defvr (@defun foo ()
is equivalent to @deffn {Function} foo () ).
So the only thing we have to do is to replace all @defun
and @defvar by
@deffn {Function} ...
@deffn {Special Form} ...
@deffn {Keyword Form} ...
@defvr {Symbol} ...
@defvr {Option Variable} ...
@defvr {System Variable} ...
@defvr {Property} ...
@defvr {Keyword} ...
@defvr {Operator} ...
@defvr {Package} ...
I verified that describe is still happy with all these commands.
Dealing with 10 types of objects it is good idea to have
a little more informative master index. Something like
- abc (function) ........... 133
- abcd (special form) ....... 90
- abcd (keyword) ........... 200
where each entry has type specifier in parentheses.
Unfortunately standard @deffn and @defvr commends
create index in plain form
- abc ...................... 133
- abcd ...................... 90
- abcd ..................... 200
But this behavior can be changed by editing texinfo.tex
which is probably not so hard to do (Maxima keeps private
copy of texinfo/tex).
Any comments are greatly appreciated,
Vadim
--
Vadim V. Zhytnikov
<vvzhy@mail.ru>
<vvzhy@netorn.ru>