documentation categories, was: conventions for .texi files

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.

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

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

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

I look forward to your comments. 

Regards, Robert Dodier


		
__________________________________ 
Do you Yahoo!? 
The all-new My Yahoo! - Get yours free! 
http://my.yahoo.com