Hello,
I've been making a number of changes to the doc/info/*.texi
files over the last several weeks. Let me briefly summarize.
I hope that this won't be controversial but if so it's better
to find out sooner rather than later.
- make descriptions conform to observed behavior
- adopt neutral tone & talk about user in 3rd person
- for functions, state return type, & distinguish returning
something from printing something
- change @defwhatever FOO to @defwhatever foo
- if a function has several variations, @defunx all variations,
explicitly state variations in text (replace "You can also")
- write @code{foo} for FOO in text
- split long text blocks into short paragraphs
- rerun examples with linel: 65
(verifies examples, fixes alignment, and makes lowercase)
- write "Default value: foo" instead of "Default: [FOO]" for variables
- write @code{foo} for FOO[BAR] (notation for default value;
omit default value everywhere but in description of foo)
- write "See also @code{foo}" for "Do DESCRIBE(FOO)$"
- strike out descriptions of undefined functions and
unused variables (no changes to Lisp source code)
- strike out obsolete @c @node and @c @unnumberedsec comments
- strike out references to obsolete hardware & software,
change Macsyma, MACSYMA, etc to Maxima
I've tried to make the documentation more precise, more extensive,
more accurate, and, in general, less aggressively wierd.
You'll let me know if I have fallen short of the goal. There is
still a lot of work to do.
regards,
Robert Dodier
__________________________________
Do you Yahoo!?
The all-new My Yahoo! - Get yours free!
http://my.yahoo.com