MathGroup Archive 2004

[Date Index] [Thread Index] [Author Index]

Search the Archive

RE: Re: Yet another Mathematica docs whopper

  • To: mathgroup at
  • Subject: [mg47140] RE: [mg47123] Re: Yet another Mathematica docs whopper
  • From: JonasB at
  • Date: Sat, 27 Mar 2004 01:34:43 -0500 (EST)
  • Sender: owner-wri-mathgroup at

Documentation can be bad for different reasons. In this case it seems like
there is a conceptual fuzziness. Functions can either "have options" or
"transmit options to objects". This is not clear in the documentation or the
error messages. 

The functions Options[] and SetOptions[] display or change the default
values of options that the function "has". A function like Show only
"transmits" options. Show is an overloaded function, taking and generating
various types of objects: Graphics, Graphics3D, SurfaceGraphics,
ContourGraphics, DensityGraphics and GraphicsArray. The "transmitted"
options are applied to all the arguments of Show. As the various types of
Graphics objects allow different options, the options that Show transmits
depend on the argument. Show[x, Boxed -> True] is correct if x is a
SurfaceGraphics object, but not if it is a Graphics object. 

Another fuzziness in the documentation is in the concept of a "Symbol". The
first thing usually specified in programming languages is what constitutes a
variable, ie what is a valid name. Mathematica is extremely sloppy in this
respect. According to appendix A.1.2 

"The name of a symbol must be a sequence of letters, letter like forms and
digits, not starting with a digit."

The problem is that "letter like forms" is not defined. In addition, in the
relevant section in the main text, section 3.10.2, both \[Infinity] and
OverBar[x] are listed as symbols. The latter is not a symbol however. 

\!\(x = 1\[IndentingNewLine]



None of the objects in the table "Creating objects with annotated names."
are symbols. The fact that the package Utilities`Notation` can make them
symbols does not make the text less erroneous. 


> -----Original Message-----
> From: Paul Abbott [mailto:paul at] 
To: mathgroup at
> Sent: den 26 mars 2004 09:56
> To: mathgroup at
> Subject: [mg47140] [mg47123] Re: Yet another Mathematica docs whopper
> In article <c3udt9$9pd$1 at>,
>  J Krugman <jkrugman at> wrote:
> > I've posted about the poor quality of Mathematica's documentation 
> > before, and received several e-mails challenging my claim that this 
> > documentation is awash in errors and woefully incomplete.  
> Well, for 
> > those who doubt, here's the latest example I just bumped into:
> > 
> >   In[1]:= ??AspectRatio
> >   AspectRatio is an option for Show and related functions 
> which specifies the
> >               ^^^^^^^^^^^^^^^^^^^^^
> >      ratio of height to width for a plot.
> > 
> >   Attributes[AspectRatio] = {Protected}
> > 
> >   In[2]:= SetOptions[Show, AspectRatio->Automatic];
> > 
> >   SetOptions::optnf: AspectRatio is not a known option for Show.
> >                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> > 
> > Faced with this sort of nonsense, what is a user to do?
> Interesting example -- and a little subtle because, in fact, both 
> statements are true! If you enter
>    Options[Show]
> you will see that it has no built-in options. However,
>    Show[Plot[Sin[x], {x, 0, 2 Pi}], AspectRatio -> Automatic]
> does work. (Since Show has no options, I assume that the 
> option must be 
> getting passed to the object produced by the Plot command, 
> which in this 
> case is a -Graphics- object).
> To set AspectRatio->Automatic for all Plots, one can do
>    SetOptions[Plot, AspectRatio -> Automatic]
>    Plot[Sin[x], {x, 0, 2 Pi}]
> Similarly, to set it for Graphics (and to add a frame)
>    SetOptions[Graphics, AspectRatio -> Automatic, Frame -> True]
>    Show[Graphics[Point /@ Table[Random[], {100}, {2}]]]
> > I am furious, because I spend an unreasonable amount of 
> time resolving 
> > inadequacies like this one in the Mathematica documentation. 
> > Considering the exorbitant sum we paid for Mathematica, I expect 
> > something much better documented than this.
> Agreed -- but the documentation of Mathematica is already 
> overwhelmingly 
> large ...
> Cheers,
> Paul
> -- 
> Paul Abbott                                   Phone: +61 8 9380 2734
> School of Physics, M013                         Fax: +61 8 9380 1014
> The University of Western Australia      (CRICOS Provider No 
> 00126G)         
> 35 Stirling Highway
> Crawley WA 6009                      mailto:paul at 
> AUSTRALIA                  

  • Prev by Date: Re: Infrequent Mathematica User
  • Next by Date: Dashed space curve
  • Previous by thread: Re: Yet another Mathematica docs whopper
  • Next by thread: RE: Re: Yet another Mathematica docs whopper