documentation categories, was: conventions for .texi files

Vadim V. Zhytnikov writes:

Some correction to this proposal. 

>>
>>
> I venture to propose for consideration the following
> scheme:
>
> 1.  Let's define some limited number (N) of categories
> (something like in Macsyma's manual).
>
> 2.  Next, we don't use texinfo's built-in @defun and @defvar
> and standard indices fn and vr but define.   Instead we
> define our own separate @def and index for each category.
> @defCATEGORY foo should automatically add foo to indexCATEGORY.
>
First, thinking about texinfo as some TeX
incarnation with all TeX flexibility I forgot
about info, html and other derivative documentation
formats.  Thus, defining special @defCAT for
each category may not work as expected for info and describe. 
But this is not a big deal.  We can use @deffn CAT.
Actually the only purpose of defining special @defCAT foo
is automatic insertion of foo into corresponding index.
If we can't find way to define @defCAT understandable by
info then we still can make index{foo} explicitly.

> 3.  The case when foo belongs to several categories
> could be handled by manual index entry.  For example,
> let's foo belongs to two categories CAT1 and CAT2.
> I presume that one of this categories, say CAT1,
> is more important.  Then we can do something like this
>
> @defCAT1 foo
>
> Description of foo as CAT1 object.
>
> Description of foo as CAT2 object @CATindex foo
>
> @end CAT1
>
This example is stupid.  Forget it.  Certainly
there is no trouble to have multiple @def entries
for one object foo.

-- 
     Vadim V. Zhytnikov

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