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

[Ross Boylan]

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.

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."

So the manual includes cross-references that do not appear in any of
the page titles or in the index.

Perhaps this is a general rule for the documentation.  As I said, I
found it confusing.

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).

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. 

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
should yield the response variable (or, more accurately, term).

The last bit below was mostly wishful thinking on my part.  You should 
probably ignore it:
> 
> >   It would be useful to
> > indicate if all.vars returns the same ordering as the variables
> > attribute (at least, I'm wondering it now, though this might be a sign
> > I've gone astray).
> 
> What has all.vars to do with terms?  All.vars applies to an expression or 
> call, and terms() applies to a formula or a model object.
>
The connection was mostly in my head, as I sought a more useable (to
me) form of the variables or terms.
f <- a~b+c
t <- terms(f)
v <- all.vars(f)
and then trying to play with t and v simultaneously.