another version of documentation category stuff

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?

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

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

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

At this point I think the categories are quite open to revision
so if you'd like to see some different categories, or move some
items around, or establish some different classification policies,
please tell us about it.

The existing category machinery works OK as it stands (although
it is even more idiosyncratic than Maxima in general, sorry)
so at this point I think it's appropriate to spend more time
setting up categories and tagging things. Part of that has to be
a discussion about what categories to establish. I don't suppose
that the existing categories are best. Also, a lot of items are
missing some useful tags, or have no tags at all.

> But in general categories looks very nice.
> Thank you for your work on the subject.

Thanks for your support.

best

Robert