[Rd] relist.Rd patch

[Dan Davison]

There are a few typos in the documentation for relist(). I've also
made a few other changes to the file which I believe are
improvements. I've attached a patch against the version under the
'trunk' branch on the svn server checked out today. It was produced by

diff -u /usr/local/src/R/R-svn-trunk/src/library/utils/man/relist.Rd ~/relist-new.Rd

I'd also suggest identical() rather than "==" in the equalities at the
bottom of the documentation, but that may be overly pedantic.

Dan

-- 
www.stats.ox.ac.uk/~davison
-------------- next part --------------
--- /usr/local/src/R/R-svn-trunk/src/library/utils/man/relist.Rd	2008-08-16 13:41:50.000000000 +0100
+++ /home/dan/relist-new.Rd	2008-08-16 17:15:54.000000000 +0100
@@ -13,7 +13,7 @@
 \alias{is.relistable}
 \alias{unlist.relistable}
 %
-\title{Allow Re-Listing an unlisted() Object}
+\title{Allow Re-Listing an unlisted Object}
 \description{
   \code{relist()} is an S3 generic function with a few methods in order
   to allow easy inversion of \code{\link{unlist}(obj)} when that is used
@@ -33,8 +33,9 @@
 }
 
 \arguments{
-  \item{flesh}{ .....}
-  \item{skeleton}{ .........}
+  \item{flesh}{a vector to be relisted}
+  \item{skeleton}{a list, the structure of which determines the structure
+  of the result}
   \item{x}{an \R object, typically a list (or vector).}
   \item{recursive}{logical.  Should unlisting be applied to list
     components of \code{x}?}
@@ -42,13 +43,13 @@
 }
 \details{
   Some functions need many parameters, which are most easily represented in
-  complex structures.  Unfortunately, many mathematical functions in \R,
+  nested list structures.  Unfortunately, many mathematical functions in \R,
   including \code{\link{optim}} and \code{\link{nlm}} can only operate on
   functions whose domain is
-  a vector.  \R has \code{\link{unlist}()} to convert complex objects into a
-  vector representation.  \code{relist()}, it's methods and the
+  a vector.  \R has \code{\link{unlist}()} to convert nested list objects into a
+  vector representation.  \code{relist()}, its methods, and the
   functionality mentioned here provide the inverse operation to convert
-  vectors back to the convenient structural representation.
+  vectors back to the convenient structured representation.
   This allows structured functions (such as \code{optim()}) to have simple
   mathematical interfaces.
 
@@ -60,7 +61,9 @@
       list(mean=c(0, 1), vcov=cbind(c(1, 1), c(1, 0))).
   }
   However, \code{\link{optim}} cannot operate on functions that take lists as input; it
-  only likes numeric vectors.  The solution is conversion:
+  only likes numeric vectors.  The solution is conversion. Given a
+  function mvdnorm(x, mean, vcov, log=FALSE) which computes the required
+  probability density, then
   \preformatted{
  	ipar <- list(mean=c(0, 1), vcov=cbind(c(1, 1), c(1, 0)))
  	initial.param <- as.relistable(ipar)
@@ -68,9 +71,8 @@
  	ll <- function(param.vector)
  	{
 	   param <- relist(param.vector)
-	   -sum(dnorm(x, mean = param$mean, vcov = param$vcov,
+	   -sum(mvdnorm(x, mean = param$mean, vcov = param$vcov,
 		      log = TRUE))
-	   ## NB: dnorm() has no vcov... you should get the point
  	}
 
  	optim(unlist(initial.param), ll)
@@ -83,14 +85,14 @@
   }
   will put the content of flesh on the skeleton.  You don't need to specify
   skeleton explicitly if the skeleton is stored as an attribute inside flesh.
-  In particular, flesh was created from some object obj with
+  In particular, if flesh was created from some object obj with
   \code{unlist(as.relistable(obj))}
   then the skeleton attribute is automatically set.
 
   As long as \code{skeleton} has the right shape, it should be a precise inverse
   of \code{\link{unlist}}.  These equalities hold:
   \preformatted{
-   relist(unlist(x), skeleton) == x
+   relist(unlist(x), x) == x
    unlist(relist(y, skeleton)) == y
 
    x <- as.relistable(x)