another version of documentation category stuff

Robert Dodier writes:
> On 11/18/07, Vadim V. Zhytnikov <vvzhy at mail.ru> wrote:
> 
>>> at present html files are generated and then bundled in the
>>> maxima-5.xx.yy.tar.gz distribution blob, so it is not necessary for
>>> Windows builds to generate the documentation.
>> In any case at present Windows package cam be built from distribution
>> tarball due to problems with perl 5.8 on mingw.
> 
> Do I understand correctly, then, that it is OK if the category
> stuff cannot be generated on Windows?

If category stuff is pre-packaged in distribution tarball
it is OK.  This is purely Perl-related question.
Anything which requires Perl 5.6 can be done on Windows.
On the other hand Perl 5.8 is a real problem for mingw
(at leas at present).

>> IMHO html only categories would be enough for time being.
> 
> OK. I will put in the @ifinfo and @iftex in the category macro
> definitions to suppress category output in info and tex.
> 
>> I have some questions regarding contents of sample maxima_89.html
>> What is that difference between "Global flags" and "Global variables"?
> 
> Well, the distinction is that flags have true/false or enumerated
> values, and variables are everything else.
>

I know this difference but don't think that difference between
variable which can take values false/true and variable which
take values false/true/all is worth separating them
in different classes?   I think the difference isn't so important
and details can be obtained from description of the variable.
To much efforts to maintain this classification with too little
result IMHO.  Take into account that we abolished classification
of function-like object which is present in Macsyma manual into
functions and special operators (function with special evaluation
rules for some arguments).  It seems to me that distinction between
flags and general global variables is very similar.

I feel some need for short Maxima glossary which
explains all these notions: atoms, symbols, functions, flags,
switches, functions, option or system variables etc.

>> Almost all global variables (with few exceptions) in current Maxima
>> manual are subdivide into two classes "Option variable" and "System
>> variables".
> 
> I didn't try to capture the existing @deffn or @defvr classes
> with the category stuff. I think the category stuff is more useful
> to the extent that it's orthogonal to existing indexing stuff, and
> also I find the labels "Option variable" and "System variable"
> somewhat confusing.

I think the difference is clear and is more important than
difference between flag/switch and more general option variable.
Roughly "Option variables" are IN global variables
and "System variables" are OUT ones.
Let's write glossary to explain all these terms.

> 
>> The categories system for global variables in maxima_89.html
>> is not quite clear to me: Global flags, Global variables, Display
>> variables, Translation flags, Translation variables.
>> Why these very classes?
> 
> Well, there are two things going on here. (1) There really needs to
> be a hierarchy of categories. Display variables should be a
> subcategory of global variables, likewise translation variables,
> and global variables itself should contain only the individual items
> which don't fall into a subcategory. (2) I tried to identify some
> sets of influential variables which might be sought by users.
> Aside from display and translation variables, I think another
> such set is simplification flags.
> 

I see.  Hierarchical system is appealing. Maybe "translation variables"
and similar sub-classes should be listed as an items in "global 
variables" sectin implementing in this way some sort of hierarchy?


-- 
      Vadim V. Zhytnikov

       <vvzhy at mail.ru>
      <vvzhy at netorn.ru>