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
>
> - 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
>
>
Additional style proposal:
- in the case @defun foo(bar)
use @var{bar} for bar in text. This is in accordance with the texinfo
conventions and renders bar in italics just like it is rendered by @defun.
The only a bit strange thing is that in info bar will
be emphasized by uppercasing - BAR. But to me it is OK.
Making @code{} and @var{} differ is more important IMHO.
> - 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
>
>
--
Vadim V. Zhytnikov
<vvzhy@mail.ru>
<vvzhy@netorn.ru>