More trouble with Mathematica documentation
- To: mathgroup at smc.vnet.net
- Subject: [mg38005] More trouble with Mathematica documentation
- From: dgolber at aol.com (DGolber)
- Date: Mon, 25 Nov 2002 01:57:26 -0500 (EST)
- Sender: owner-wri-mathgroup at wolfram.com
I hope Mathematica staff is reading this.
My version 4.0.1.0
Documentation of Graphics in the Appendix:
"Graphics[primatives,options] represents ..."
Consider the following examples:
===============
In[1]:=
l1 = Line[{{1, 2}, {3, 4}}];
In[2]:=
l2 = Line[{{0, 0}, {1, 3}}];
In[3]:=
Show[
Graphics[{l1, l2}, Axes -> True, Frame -> True]
]
<Output is desired graph>
In[4]:=
Show[
Graphics[l1, l2, Axes -> True, Frame -> True]
]
<Output is error message>
In[5]:=
Show[
Graphics[{l1, l2}, {Axes -> True, Frame -> True}]
]
<produces the same graph as In[3]>
===================================
What this example shows is that the description
"Graphics[primatives,options] represents ..."
is inconsistent. The first written argument "primatives" must be an actual
single argument. If you want to submit several graphics primatives, you must
combine them into a List.
On the other hand, the second written argument may be multiple actual
arguments, or may be a List.
The documentation is inconsistent.
I see no explanation of this any part of the Appendix. And it's particularly
disappointing because systems were able to document these sorts of things
decades ago.
Sorting this kind of thing out takes hours. Every time I do something slightly
new with Mathematica, I find I spend a lot of time because of sloppy
documentation.
I'd really like to hear Mathematica personnel report on (1) Do they agree there
is an error here, and (2) When do they expect to have corrections available.
And by the way: another thing that needs to be corrected in the documentation
of Graphics is how graphics directives get used . The header line is:
Graphics[primatives,options]
Unfortunately, a graphics directive is neither a primative or an option. And
sure enough, when we read a little farther on, we see "The following graphics
primatives can be used" This is vague. Used how? Remember that the appendix
is the "Definitive summary" which gives "all details". (From the beginning of
the Appendix.)
(The fact that the body can say nothing better than the vague statement that
directives "can be used" is of course a result of the fact that the form
Graphics[primatives,options] does not allow directives.)
Dave Golber