documentation categories, was: conventions for .texi files

Robert Dodier writes:

>--- "Vadim V. Zhytnikov" <vvzhy@mail.ru> wrote:
>[...]
>
>>Nothing is wrong with this example.  The point is that if we have
>>somefoo which belongs to two categories CAT1 and CAT2 (say
>>Function and Package) we can describe it using two different ways.
>>
>>First, asymmetric way.  It is presumed that foo as CAT1 is more
>>important and foo as CAT2 is something  just worth mentioning.
>>Thus we have only one @def entry:
>>
>[...]
>
>>Second, perfectly symmetric way:
>>
>[...]
>
>>The only problem is that probably this two descriptions
>>must be in different sections.  Otherwise describe
>>may be confused (maybe not, I have to check).
>>
>
>Yes, describe is confused -- it doesn't see the second 
>foo description. But maybe it wouldn't be hard to fix it.
>
>In reading this, I realized that we've been talking about
>categories in two different senses. I think you mean to
>use categories to disambiguate different items that have
>the same name (e.g., a function and a variable with the
>same name). I mean to use categories to organize the same
>item under different headings, e.g., putting "save"
>under functions, system functions, and i/o functions.
>
>
Not quite.  The main reason for categories is to make
Maxima manual more precise and clear.  At present in the
manual there are only two categories of objects - Functions and
Variables.  They are represented by corresponding commands @defun
and @defvar.  Certainly somewhere in the Manual other objects are
described but only verbally without any special construction. 
In particular Trigonometric.texi has an entry
about package atrig1 but it is presented like function with
@defun - quite bad.  I feel that more granular system are
required.  Probably we need something like this:

1. Functions
2. Several kinds of variables (Option variable, System variables ...)
3. Packages
4. Keywords
5. Special forms
6. Operators

This is very approximate list.  The object of each category must
be described in the manual by corresponding construction

@deffn {Package} foo

@deffn {Option Variable} bar

etc

Such system is implemented in Macsyma manual.  Take a look on
it and you'll see that I mean 
(http://www.cs.berkeley.edu/~fateman/macsyma/docs/)

The case when foo belongs to several categories is quite rare and
actually present little trouble.  Just make two or three entries
(provided describe understand this).



-- 
     Vadim V. Zhytnikov

      <vvzhy@mail.ru> 
     <vvzhy@netorn.ru>