documentation categories, was: conventions for .texi files

Robert Dodier writes:

>Hi Vadim,
>
>Thanks for your comments. You wrote in part:
>
>
>>We can use @deffn Package <package-name> for packages entry. 
>>
>
>>1.  Adding third entry type "Package" to .info
>>may require some modification to describe.
>>As far as I remember describe uses keywords "Function"
>>and "Variable" to find end of the current entry text.
>>
>
>Hmm, experimenting shows that texinfo is happy with nested
>tags like this:
>
>  @deffn package foo
>  @defun bar (x, y)
>  @end defun
>  @defvar baz
>  @end defvar
>  @end deffn
>
>And indeed describe ("foo") yields an appropriately nested
>group of articles! However describe is confused about where each
>article ends -- describe ("bar") yields all the text from 
>@defun bar til the end of the file. Given that texinfo is happy,
>I'm inclined to consider this a describe bug. I'd rather try
>to fix describe rather than work within its limitations.
>
>
I observe exactly the same effect if I build .info with
non-English locale (Russian).  In this case describe
can't properly find end of the item and scans till the end
of section.  But the only actual difference I see in .info
files is that instead
  - Function: foo
  - Variable: bar
we now have
  - Funkciya: foo
  - Peremannaya: bar
namely English words "Function"/"Variable" are replaced
by Russian equivalents (the body of the text is still in English).

>>Not a big deal but remember that GCL uses it's  own
>>built-in describe.  
>>
>
>Well, unless GCL supports packages or whatever features in the
>manner we want, I'm inclined to make GCL Maxima use the same 
>describe code. Comments in the source code (src/macdes.lisp) 
>say that built-in GCL describe is used because it's faster, so
>there isn't a pressing reason to preserve it.
>
>
Yes, I'm getting inclined to drop GCL's describe completely in favor
of cl-info.lisp to make things simpler.  The latter is slower but it
is still reasonably fast.  On the other hand it is possible to fix
GCL's describe.

>>BTW, Macsyma distinguish even
>>more entry types: Function, Spacial Symbol, Option Variable,
>>System Variable, Special Form (maybe more).
>>
>
>OK, I'd like to push for a system of categories that allows
>an item to belong to two or more categories. For example, "save"
>is built-in, a function, file i/o, and specifically output.
>
>I don't see that such a scheme would take much to implement.
>Each article contains a tag for each category it belongs to.
>Command-line describe prints the category names -- html or
>info output uses them to establish links.
>
>A category system might obviate the need for special package
>tags (since each package can be a category). However, making
>"@deffn package" work will doubtless be much simpler, so we 
>should certainly do that sooner.
>
>
Well, this might be a bit too complicated.

>>2.  Now @defun @defvar and @deffn automatically adds
>>into one fn index.  This is more or less OK with
>>functions and variables but we probably want to see
>>packages in separate index.  On the other hand Macsyma
>>collects all multiple types of entries in one index
>>but entry's type is clearly indicated:
>>  sin (Function) ................ 97
>>Nice solution but I don't know how to implement
>>something like this in texinfo.
>>
>
>I would claim a category system addresses this -- there is
>one index per category, with the global category containing
>everything under the sun, and specialized categories
>containing just a few items.
>
>

Do you mean that if we have N categories then manual
will contain N+1 indices - one per category and
one cumulative index?

>I look forward to your comments. 
>
>Regards, Robert Dodier
>
>
>
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.

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




-- 
     Vadim V. Zhytnikov

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