Robert Dodier writes:
>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
>
>
>
OK.
> - if a function has several variations, @defunx all variations,
> explicitly state variations in text (replace "You can also")
>
>
Yes! I was about to ask how to implement such things with multiple function
definitions in texinfo. I hope @defunx is compatible with describe?
I also wonder what to do with description for first, second ... tenth in
Lists.texi. Now we have just one item
@defun first (list) second (list) .. tenth (list)
Probably we have to make 10 @defun's for each function.
> - write @code{foo} for FOO in text
>
> - split long text blocks into short paragraphs
>
>
>
OK.
> - rerun examples with linel: 65
> (verifies examples, fixes alignment, and makes lowercase)
>
>
Very important since many examples are cropped from the right side
in printed material. There is yet another possibility to fix the
problem - maybe left indentation for @example smaller globally by
some TeX magic?
> - 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)
>
>
>
I agree. Notation with square braces [bar] for default value
is intrinsically confusing since [bar] is Maxima list.
> - 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
>
>
Agreed on all points.
>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
>
>
>
>
I'd like to attract attention to yet another documentation problem.
At present many functions and features which are available
as share packages and require some load("foo"); for operation
are mixed with other built-in Maxima function.
This is OK as soon as this required load("foo"); is clearly indicated.
It seems that it is not the case. Maybe it is good idea to create
special package index. Finally, is it possible to create something
like @defpackage for packages description?
--
Vadim V. Zhytnikov
<vvzhy@mail.ru>
<vvzhy@netorn.ru>