[Rd] glitch in terms documentation (PR#4146)
Prof Brian Ripley
ripley at stats.ox.ac.uk
Mon Sep 15 10:04:18 MEST 2003
On Mon, 15 Sep 2003, Ross Boylan wrote:
> On Sat, Sep 13, 2003 at 08:00:06AM +0100, Prof Brian Ripley wrote:
> > On Fri, 12 Sep 2003 ross at biostat.ucsf.edu wrote:
> > > These are two small items that caught my eye.
> > >
> > > I'm looking at the R 1.7.1 2003-06-16 pdf reference manual. There are
> > > several refences to terms.default (e.g., p. 711, 712) but no definitions
> > > of it. I'm guessing this means terms, but it's a little puzzling.
> > No, it means the default method of the terms generic. Try ?terms.default,
> > which gives you a complete explanation.
> > Page numbers are useless to us, BTW, as they depend on the papersize and
> > I suspect you are not using ISO sizes.
> I think it's US letter size. The references are from the "See Also"
> sections for terms and terms.formula.
Yes, I found them, not on the pages you quoted.
> When I go ?terms.default I get a help page that has a heading of
> "terms". This is the same as I see in the reference manual: there is
> an entry for "terms", but not for "terms.generic."
But terms _is_ the generic and terms.default a method. There is no
`terms.generic', but the help page does describe the default method.
> So the manual includes cross-references that do not appear in any of
> the page titles or in the index.
That has been fixed to refer only to the generic.
> Perhaps this is a general rule for the documentation. As I said, I
> found it confusing.
It is a general rule to only have usage for default methods if that is
different from the generic. I think your confusion is over the whole idea
of generic functions and methods, not specific to this example.
> Now, the other glitch, as originally reported by me, contains a
> generous mix of my confusion and what still seem to me to be actual
> problems with the manual....
> > > Also, the desription of terms.object does not mention that the
> > > "variables" attribute is actually a list of calls--surprising to me,
> > It isn't. It is a single call to list.
> > > since I was expecting text like all.vars.
> > But, it says it is a `list'. Wrong, but not character (if that is what
> > you meant by `text').
> So probably the description of variables should not say it is a list
> (even if it is a call to list).
Again, that has been corrected.
> Another problem is that the things after the call to list are not
> necessarily variables at all, but may be expressions (e.g, for
> I think it would be good if the description of "variables" (or its
> name?) could be reworded to be more correct. Optionally, clarifying
> that it is not helpful for naive use would be nice. My current
> understanding is that it is something like the parse tree for the
It is used widely in the R code, so it is useful.
> Based on subsequent discussion on r-help, it also seems the
> description of "response" needs some work too. To be really
> simple-minded, I have response=1. If I use this to index into
> "variables" I get list(). The current description seems to imply this
Well, that's not how you index into a call, and there are lots of examples
of that in the R code.
> should yield the response variable (or, more accurately, term).
It doesn't. It is your misconception of what indexing a call yields that
leads you to that conclusion. To get the n'th argument of a call you need
the (n+1)st element.
There is a general assumption in the documentation that when descirbing
complex things the simpler concepts are understood correctly. The real
problem is that `variables' was not documented as a call: it now is.
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
More information about the R-devel