documentation categories, was: conventions for .texi files

Robert Dodier writes:

>--- "Vadim V. Zhytnikov" <vvzhy@mail.ru> wrote:
>
>  
>
>>>1.  Let's define some limited number (N) of categories
>>>(something like in Macsyma's manual).
>>>      
>>>
>
>Well, there will only be a few categories such as functions,
>variables, etc. But I'd like to see a category established for
>each share package. Incidentally this suggests creating a new
>category does not require special magic.
>
>  
>
Yes, I see you idea but I honestly don't understand what for
we need each package in separate category.  To me
something like

@deffn Package foo
....

@deffn Package bar
....

with special Packages index sounds as a good solution.

>>>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.
>>    
>>
>
>OK, I'm not following here. I'm not good enough at texinfo to
>understand what's wrong with the example and how you want to
>correct it. Maybe you can post some texinfo commands which 
>create categories, and also show how those commands are used?
>
>  
>
Nothing is wrong with this example.  The point is that if we have some
foo 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:
========================================

@deffn CAT1 foo

Description of foo as CAT1 object.

Description of foo as CAT2 object @CATindex foo

@end CAT1

========================================

Second, perfectly symmetric way:
========================================

@deffn CAT1 foo

Description of foo as CAT1 object.

@end CAT1


@deffn CAT2 foo

Description of foo as CAT2 object.

@end CAT2

========================================
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).

As for examples.  I'll try to bake some but after some  more
careful reading of texinfo manual ;-)

>Thanks a lot for your comments on this topic.
>
>Robert Dodier
>
>  
>
Best wishes

-- 
     Vadim V. Zhytnikov

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