[Rd] graphics documentation omission (PR#9149)

[Prof Brian Ripley]

Please DO try not to file multiple reports on a single subject: this has 
been filed under PR#9148 and PR#9149 already, both started by RMH.

It is important to be aware of the difference between `argument' and 
`parameter'.  'asp' is an argument, whereas ?par describes parameters (see 
its title).

This report seems to stem from missing that distinction, which is crucial 
(e.g. 'bg' is a graphical parameter, but also an argument name for 
some functions with a different meaning).  (This is described under ?par.)

plot.Rd should say that '...' can contain arguments to be passed to 
methods, many of which accept graphical parameters.  I've altered it to do 
so, and added an alias to 'asp' in plot.window, so ?asp and 
help.search("asp") both get to plot.window.

On Tue, 15 Aug 2006, mschwartz at mn.rr.com wrote:

> On Tue, 2006-08-15 at 22:13 +0200, rmh at temple.edu wrote:
> > Thanks, Marc
> 
> Happy to help Rich.
> 
> > Neither plot.window or plot.default are natural places for me to look for
> > argument names.  par and plot are, for me, the natural places.  I realize
> > that asp is not a par argument.  Nonetheless, par is still the first place
> > to look for arguments that I would use in the ... position of any plot function.
> > It would be easy to make a case that asp is the same type of argument as mar
> > or fin, thus it would make sense for it to be added to par.

It is an argument, not a parameter, as in

> par(asp=1)
Warning message:
"asp" is not a graphical parameter

Unlike 'mar' and 'fin' it is not a property of the plot but of the 
coordinate system (like 'usr', which causes inconsistencies if set 
directly).  Note that 'type' and 'main' are also not parameters.

> Over the years, more from "behavioral modification" than from instinct,
> I look at ?plot.default when I forget defacto plot() arguments. Of
> course, plot.default() is in the See Also in ?plot.

Yes, and plot() is a generic so one needs to be aware that different 
methods will be called, some of which support 'asp' and some of which do 
not.

> It is rare for me to look at ?plot.window, given the rarity in which I
> call it directly.
> 
> > There are NO (that is, zero) live links in the Rgui help system.

There is no such thing.  R itself provides several forms of help

text
CHM
HTML
latex
PDF (the reference manual)

and three of those five have active links.  Which of the first three you 
get by default for help() in Rgui is a preference (latex comes from 
offline=TRUE).

> Yeah. I enabled options(htmlhelp = TRUE) in my .Rprofile for the times
> when I use R from the GNOME console, otherwise I am usually in ESS using
> emacs 22 from CVS with the XFT patches.
> 
> I am not sure that I ever used the .CHM help when I used to run on
> Windows, but presume that there is a hyperlink in that format to
> parallel the live link in the HTML file.
> 
> > help.search("asp") doesn't find anything related to graphics.
> 
> Could be added as a \concept presumably in the .Rd files for
> plot.default and plot.window. For example:
> 
>   \concept{asp aspect ratio}
> 
> > ESS is much better for help than Rgui since ESS Rd mode can go to the help
> > page for any word that the cursor sits on.  ESS for R help doesn't have the
> > links themselves.
> 
> Indeed.

-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595