I'm not sure how the organization of a manual is related to
the object types.
It is an important point, I think that sin(x) and first(list)
are conceptually different, and that the word "function"
is overloaded.
If the manual is divided into topics like
Math:
algebra
calculus
special functions
....
Programming:
Data structures
Conditional statements
procedures
....
It may help new users to separate these.
There is, unfortunately, a tendency, even
a requirement, to merge the
two. Is f(x) a procedure function or is f a mathematical
function with (say) simplification rules?
A separate cut through all the "names" for purposes
of indexing, is fine.
My feeling, maybe not shared by everyone, is that
the organization and even the typography of the
Mathematica documentation printed and on-line, is
pretty good. Probably more money has been spent on
that than programming.
RJF
Vadim V. Zhytnikov wrote:
> Robert Dodier writes:
>
>> Hi Vadim,
>>
>> Thanks for taking the time to work out this proposal.
>> I'm in agreement on the whole & I just have a few quibbles.
>>
>> About the object types --
>>
>>
>>> 1. Functions - functions (sin, cos, bessel...)
>>> 2. Special forms - similar to functions but handle arguments in some
>>> special nonstandard way (e.g. declare)
>>> 3. Symbols - %e, %i, %pi, inf ...
>>> 4. Option variables - variables whose value control Maxima behavior
>>> (e.g. logexpand).
>>> 5. System variables - usually read only variables which contain
>>> information
>>> about current Maxima state (e.g. functions).
>>> 6. Properties - named attributes of symbols.
>>> 7. Keywords - optional argument to function or special form which
>>> modifies its behavior.
>>> 8. Keyword forms - like keyword but more complicated in structure
>>> than
>>> 9. Operators - operators. Can be further subdivided into prefix,
>>> infix and postfix operators.
>>> 10. Packages - packages in share.
>>>
>>
>> I'm inclined to lump together 1 & 2 -- I guess I don't see a
>> strong reason to consider declare, ev, etc as something other
>> than functions.
>>
> I almost agree. But just some thoughts. The difference between
> 1 and 2 as described above has little value to reader. Wording Special
> form - just indicates that there is
> something special about function-like construction. But it tells
> nothing what is it. But all these special features
> must be clearly described in the article. So we could
> call 1 and 2 "Functions" without much loss.
> On the other hand just consider some "function" types:
>
> 1. sin(x) - function, mathematical function
> 2. first(list) - function, but has nothing to do with math
> 3. declare, describe - also functions if we agree to merge 1 and 2.
> But we are not interested in their value. We need their side
> effects.
>
>> Maybe 3 can be called "constants"?
>
>
> I Agree. I feel that Macsyma wording - symbols, special forms etc is
> too Lisp-centric.
>
>> I think
>> "keyword" will be interpreted as "reserved word" (while, for,
>> then, etc) so maybe 7 should be called "special arguments" or
>> something.
>
> In Macsyma manual they call "while, for, inf" - special forms. Maybe
> due to existence of functional equivalents (as Richard pointed out).
>
>> Or maybe each such symbol should just be discussed
>> in the context of the functions it applies to, since functions
>> can treat a symbol in different ways, so 7 could be omitted.
>> Same with 8. There aren't many operators, so I wouldn't split
>> them into prefix, etc. A list of share packages is a great idea.
>>
>> So here is the list as I've revised it -- functions, constants,
>> option variables, system variables, properties, operators, packages.
>>
>>
> As far as I understand at present there is no any article which describes
> "special argument" or "property" and I doubt that we want to introduce
> some (do we want to see these objects in describe?).
> All properties and special arguments are described in articles
> devoted to relevant functions. So maybe we could drop "properties"
> from this classification as well. But we can manually insert index
> entries @findex{foo (property)} or @findex{bar (special argument)}
> in appropriate places.
>
>>> Dealing with 10 types of objects it is good idea to have
>>> a little more informative master index. Something like
>>>
>>> - abc (function) ........... 133
>>> - abcd (special form) ....... 90
>>> - abcd (keyword) ........... 200
>>>
>>> where each entry has type specifier in parentheses.
>>>
>>
>> That makes sense to me. I don't see a problem with modifying
>> texinfo.tex to make an index like that.
>>
>>
> OK.
>
>