RE: Re: Yet another Mathematica docs whopper
- To: mathgroup at smc.vnet.net
- Subject: [mg47140] RE: [mg47123] Re: Yet another Mathematica docs whopper
- From: JonasB at iui.se
- Date: Sat, 27 Mar 2004 01:34:43 -0500 (EST)
- Sender: owner-wri-mathgroup at wolfram.com
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. In[1]:= \!\(x = 1\[IndentingNewLine] x\&_\) Out[1]= 1 Out[2]= \!\(1\&_\) 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. Jonas > -----Original Message----- > From: Paul Abbott [mailto:paul at physics.uwa.edu.au] To: mathgroup at smc.vnet.net > Sent: den 26 mars 2004 09:56 > To: mathgroup at smc.vnet.net > Subject: [mg47140] [mg47123] Re: Yet another Mathematica docs whopper > > > In article <c3udt9$9pd$1 at smc.vnet.net>, > J Krugman <jkrugman at yahbitoo.com> 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 physics.uwa.edu.au > AUSTRALIA http://physics.uwa.edu.au/~paul >