This sounds good. I would suggest another category or two.
I am not sure where they would fit in a 'linear' version of
the manual.
a. Discussion of mis-features. In other words,
"According to some critics, this command should do
the following:... instead of what it does".
For example, change all trig forms to algebraics if
possible....
b. Discussion of mis-use. "Some users expect this command
to do ..."
For example, factoring does not find all linear factors;
just irreducible over the rationals or a given algebraic
field. For finding approximations to factors of a univariate
polynomial, try "allroots".
Or... finding an approximate integral can be done, not by
INTEGRATE, but by ...."
Or other commands that resemble this one or are related.
[important for people who forget the exact name of a command
but might know the name of a related one].
c. Discussion of potential extensions. e.g.
"Solve does not automatically try to solve combinatorial
problems, but if we could recognize these in some uniform
way, here is a solution technique:.
d. Applications using these commands (cross reference)
e. references to the literature
f. similar commands in other systems (Mathematica, Maple,
maybe others .. Reduce, Mupad,?)
g. Also, I don't know if there is a section in the manual
that really tries to describe (and defend) the behavior
of the evaluator (especially oddities like sum and product)
or the simplifier.
h. It might also be appropriate to list, for reference sake,
items that are only in commercial macsyma. These could be
considered targets for extension.
RJF
Vadim V. Zhytnikov wrote:
> 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>
>
>