drop.terms clarification (from PR#17169), markup

git-svn-id: https://svn.r-project.org/R/trunk@87420 00db46b3-68df-0310-9c12-caf00c1e9a41

Author: smeyer

src/library/stats/man/delete.response.Rd

@@ -1,6 +1,6 @@
 % File src/library/stats/man/delete.response.Rd
 % Part of the R package, https://www.R-project.org
-% Copyright 1995-2022 R Core Team
+% Copyright 1995-2024 R Core Team
 % Distributed under GPL 2 or later
 
 \name{delete.response}
@@ -17,25 +17,28 @@ drop.terms(termobj, dropx = NULL, keep.response = FALSE)
 \alias{delete.response}
 \alias{[.terms}
 \arguments{
-  \item{termobj}{A \code{terms} object}
+  \item{termobj}{a \code{\link[=terms.object]{terms}} object.}
   \item{termlabels}{character vector giving the right-hand side of a
     model formula.  Cannot be zero-length.}
-  \item{response}{character string, symbol or call giving the left-hand
+  \item{response}{a character string, symbol or call giving the left-hand
     side of a model formula, or \code{NULL}.}
   \item{intercept}{logical: should the formula have an intercept?}
   \item{env}{the \code{\link{environment}} of the \code{\link{formula}}
     returned.}
-  \item{dropx}{vector of positions of variables to drop from the
-    right-hand side of the model.}
+  \item{dropx}{a numeric vector indexing \code{labels(termobj)}
+    (that is, the \code{"term.labels"} attribute of \code{termobj}),
+    indicating terms to be dropped from the right-hand side of the
+    model, or \code{NULL} (default) to keep all terms.}
   \item{keep.response}{Keep the response in the resulting object?}
 }
 \description{
   \code{delete.response} returns a \code{terms} object for the same
   model but with no response variable.
 
-  \code{drop.terms} removes variables from the right-hand side of the
-  model. There is also a \code{"[.terms"} method to perform the same
-  function (with \code{keep.response = TRUE}).
+  \code{drop.terms} removes terms from the right-hand side of the
+  model, optionally keeping the response.  There is also a
+  \code{[.terms} method performing a complementary operation: it
+  extracts terms, always keeping the response.
 
   \code{reformulate} creates a formula from a character vector.  If
   \code{length(termlabels) > 1}, its elements are concatenated with \code{+}.

src/library/stats/man/terms.Rd

@@ -4,40 +4,40 @@
 % Distributed under GPL 2 or later
 
 \name{terms}
-\title{Model Terms}
-\usage{
-terms(x, \dots)
-}
 \alias{terms}
 %\alias{terms.terms}
 %\alias{terms.aovlist}
 %\alias{terms.default}
 %\alias{print.terms}
 \alias{labels.terms}
+\title{Model Terms}
 \description{
   The function \code{terms} is a generic function
   which can be used to extract \emph{terms} objects
   from various kinds of \R data objects.
 }
+\usage{
+terms(x, ...)
+}
 \arguments{
   \item{x}{object used to select a method to dispatch.}
   \item{\dots}{further arguments passed to or from other methods.}
 }
 \details{
-  There are methods for classes \code{"aovlist"}, and \code{"terms"}
+  There are methods for classes \code{"aovlist"}, \code{"terms"}, and
   \code{"formula"} (see \code{\link{terms.formula}}):
   the default method just extracts the \code{terms} component of the
   object, or failing that a \code{"terms"} attribute (as used by
   \code{\link{model.frame}}).
 
   There are \code{\link{print}} and \code{\link{labels}} methods for
-  class \code{"terms"}: the latter prints the term labels (see
-  \code{\link{terms.object}}).
+  class \code{"terms"}: the latter extracts the term labels (see
+  \code{?\link{terms.object}}).
 }
 \value{
   An object of class \code{c("terms", "formula")} which contains the
   \emph{terms} representation of a symbolic model.  See
-  \code{\link{terms.object}} for its structure.
+  \code{?\link{terms.object}} for its structure.
 }
 \references{
   Chambers, J. M. and Hastie, T. J. (1992)

src/library/stats/man/terms.formula.Rd

@@ -5,11 +5,11 @@
 
 \name{terms.formula}
 \alias{terms.formula}
-\title{Construct a terms Object from a Formula}
+\title{Construct a \code{terms} Object from a Formula}
 \description{
   This function takes a formula and some optional arguments and
-  constructs a terms object. The terms object can then be used to
-  construct a \code{\link{model.matrix}}.
+  constructs a \code{\link[=terms.object]{terms}} object, which
+  can then be used to construct a \code{\link{model.matrix}}.
 }
 \usage{
 \method{terms}{formula}(x, specials = NULL, abb = NULL, data = NULL, neg.out = TRUE,
@@ -37,10 +37,10 @@
     remaining variables contained in \code{data}.  Exceptionally,
     \code{.} can be treated as a name for non-standard uses of formulae.}
 }
-\details{
-  Not all of the options work in the same way that they do in S and not
-  all are implemented.
-}
+%% \note{
+%%   Not all of the options work in the same way that they did in S and not
+%%   all are implemented.
+%% }
 \value{
   A \code{terms} object is returned.  It is the re-ordered formula (unless
   \code{keep.order = TRUE}) with several \code{\link{attributes}}, see