documentation categories, was: conventions for .texi files

--- "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.

> > 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?

Thanks a lot for your comments on this topic.

Robert Dodier


		
__________________________________ 
Do you Yahoo!? 
All your favorites on one personal page – Try My Yahoo!
http://my.yahoo.com