[R] ?plot: Add an example on how to plot functions to the help of `plot`.

[Martin Maechler]

>>>>> "PM" == Paul Menzel <paulepanter at users.sourceforge.net>
>>>>>     on Wed, 27 Jul 2011 23:53:51 +0200 writes:

    PM> Am Mittwoch, den 27.07.2011, 17:21 -0400 schrieb David Winsemius:
    >> On Jul 27, 2011, at 4:53 PM, Paul Menzel wrote:

    >> > Am Mittwoch, den 27.07.2011, 13:26 -0700 schrieb Bert Gunter:
    >> >> Paul:
    >> >> No such change is needed.
    >> >
    >> > Well the fact is, that I as a beginner was looking for who I could  
    >> > plot normal functions, so one more example would have helped me.
    >> >
    >> >> You do not understand S3 methods.
    >> >
    >> > That is probably true.
    >> >
    >> >> See ?plot.default and read about S3 methods (e.g. in the tutorial
    >> >> Introduction to R or the Language manual).
    >> >
    >> > Searching for »s3 m« in [1] did not give me a good explanation. I have
    >> > not yet read the language manual.
    >> >
    >> > By trial and error I still suggest to add the following.
    >> >
    >> >        # Plot the graph of a function f(x) = x^3 with the points  
    >> > connected by lines.
    >> >        # If you want to plot the graph as a curve please look into  
    >> > `curve()`.
    >> >        y <- seq(1:5)
    >> >        plot(y, y**3, type="l")
    >> >
    >> > This would have helped me as a beginner.
    >> 
    >> I think that what Bert might have been trying to get you to do was to  
    >> type:
    >> 
    >> ?plot.function  # which is what you might once you do get a better  
    >> understanding S3 methods.

    PM> Thank you. So S3 methods seem to be a wrapper for another method. Well I
    PM> have to read up about that.

no, generic functions are (``something like a wrapper''),
and plot() is a generic function.

    PM> So my newest suggestion is to add a comment to

    PM> plot(sin, -pi, 2*pi)

    PM> in `?plot`. Like

    PM> plot(sin, -pi, 2*pi) # Cf. ?plot.function

    PM> as `plot.function` is not explicitly mentioned in `?plot`.

Yes, I'll do that  {using 'see' instead of 'Cf.'}.

Would it have helped you as beginner if instead of current

>  Generic X-Y Plotting
> 
>  Description:
> 
>       Generic function for plotting of R objects.  For more details
>       about the graphical parameter arguments, see ‘par’.
> 
>  Usage:
> 
>       plot(x, y, ...)
> 
>  ....................
>  ....................
> 
>  Details:
> 
>       For simple scatter plots, ‘plot.default’ will be used.  However,
>       there are ‘plot’ methods for many R objects, including
>       ‘function’s, ‘data.frame’s, ‘density’ objects, etc.  Use
>       ‘methods(plot)’ and the documentation for these.
> 
>       The two step types differ in their x-y preference: Going from
>       ........................

We would have moved the first paragraph from 'Details' to
'Description',  so that the help page would start with

>  Generic X-Y Plotting
> 
>  Description:
> 
>       Generic function for plotting of R objects.  For more details
>       about the graphical parameter arguments, see ‘par’.
> 
>       For simple scatter plots, ‘plot.default’ will be used.  However,
>       there are ‘plot’ methods for many R objects, including
>       ‘function’s, ‘data.frame’s, ‘density’ objects, etc.  Use
>       ‘methods(plot)’ and the documentation for these.
> 
>  Usage:
> 
>       plot(x, y, ...)
> 
>  ............

I.e.  would you have read the help page for plot.default 
earlier, and realized that the ?plot page is by far not the only
one to read,  if the paragraph above had come earlier ?

Martin Maechler, ETH Zurich (and R Core Team).