[Rd] glitch in terms documentation (PR#4146)

[Prof Brian Ripley]

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
> Surv(t)~b+c). 
> 
> 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
> formula. 

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