doc update for r88066, terms.formula( specials )

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

Author: maechler

doc/NEWS.Rd

@@ -15,6 +15,9 @@
   \subsection{NEW FEATURES}{
     \itemize{
       \item \code{str()} now shows more via \code{format()} for external pointers.
+
+      \item \code{terms(<formula>, specials = *)} now treats non-syntactic
+      specials more gracefully, thanks to \I{Mikael Jagan}'s \PR{18568}.
     }
   }
 
@@ -302,9 +305,6 @@
       \item \code{selectMethod(f, ..)} now keeps the function name if the
       function belongs to a group generic and the method is for the
       generic.
-
-      \item \code{terms(<formula>, specials = *)} now treats non-syntactic
-      specials more gracefully, thanks to \I{Mikael Jagan}'s \PR{18568}.
     }
   }
 

src/library/stats/man/formula.Rd

@@ -94,11 +94,17 @@ as.formula(object, env = parent.frame())
   formulae, although there is no guarantee that all code using formulae
   will accept such non-syntactic names.
 
-  Most model-fitting functions accept formulae with right-hand-side
-  including the function \code{\link{offset}} to indicate terms with a
-  fixed coefficient of one.  Some functions accept other
-  \sQuote{specials} such as \code{strata} or \code{cluster} (see the
-  \code{specials} argument of \code{\link{terms.formula}}).
+  Most model-fitting functions accept formulae with right-hand side
+  containing calls to function \code{\link{offset}}.  These calls
+  indicate terms with coefficient fixed to one.  Some model-fitting
+  functions recognize other \dQuote{specials} like \code{strata} and
+  \code{cluster} (typically by setting the \code{specials} argument of
+  \code{\link{terms.formula}}).  Because specials are nothing more than
+  syntax, disambiguation using \code{\link{::}} or similar is nonsense
+  (even if packages happen to define so-named functions) and the result
+  is often a model that the user does not intend.  For example, the
+  formula \code{y ~ stats::offset(w) + x} does \emph{not} specify a
+  model in which the coefficient of \code{w} is fixed to one.
 
   There are two special interpretations of \code{.} in a formula.  The
   usual one is in the context of a \code{data} argument of model

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

@@ -18,8 +18,9 @@
 }
 \arguments{
   \item{x}{a \code{\link{formula}}.}
-  \item{specials}{which functions in the formula should be marked as
-    special in the \code{terms} object?  A character vector or \code{NULL}.}
+  \item{specials}{an optional character vector listing names of
+    functions.  Calls to these functions in the formula are marked as
+    special in the \code{terms} object.}
   \item{abb}{Not implemented in \R; deprecated.}
   \item{data}{a data frame from which the meaning of the special symbol
     \code{.} can be inferred.  It is used only if there is a \code{.} in
@@ -37,6 +38,13 @@
     remaining variables contained in \code{data}.  Exceptionally,
     \code{.} can be treated as a name for non-standard uses of formulae.}
 }
+\details{
+  Non-syntactic \code{specials} are supported since \R{} 4.6.0.
+  \code{specials="\var{pkg}::\var{name}"} marks as special calls
+  \code{`\var{pkg}::\var{name}`(\dots)} (note backticks) and \emph{not}
+  calls \code{\var{pkg}::\var{name}(\dots)}.  The reverse was true prior
+  to \R{} 4.6.0, but that was undocumented and accidental.
+}
 %% \note{
 %%   Not all of the options work in the same way that they did in S and not
 %%   all are implemented.

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

@@ -82,6 +82,13 @@ rownames(attr(tf, "factors"))[attr(tf, "specials")$s]
 
 ## we can keep the order by
 terms(y ~ x + x:z + s(x), specials = "s", keep.order = TRUE)
+
+## use of '::' in terms to be marked as special is *wrong*
+ff <- list(y ~        offset(w) + x1 +       s(x2),
+           y ~ stats::offset(w) + x1 + mgcv::s(x2))
+tt <- lapply(ff, terms, specials = c("s", "mgcv::s"))
+lapply(tt, attr, "offset")
+lapply(tt, attr, "specials")
 }
 %%--- MM: I would really like instructive examples here...
 \keyword{models}