Finished documentation changes to xtableFtable and xtableList. Package should be...

[xtable.git] / pkg / man / xtableList.Rd

diff --git a/pkg/man/xtableList.Rd b/pkg/man/xtableList.Rd
index ce66636d8326434c77dcaa09c0f9d3dc7f656a13..1682689cc2cb5dca13e606f35169980507b732c0 100644 (file)
--- a/pkg/man/xtableList.Rd
+++ b/pkg/man/xtableList.Rd
@@ -60,8 +60,13 @@ xtableList(x, caption = NULL, label = NULL,
   ...)\r
 }\r
 \arguments{\r
-  \item{x}{For \code{xtableList}, a list of \R objects all of the same\r
-    class, being a class found among \code{methods(xtable)}.\r
+  \item{x}{\r
+    For \code{xtableList}, a list of \R objects all of the same class,\r
+    being a class found among \code{methods(xtable)}. The list may also\r
+    have attributes \code{"subheadings"} and \code{"message"}. The\r
+    attribute \code{"subheadings"} should be a character vector of the\r
+    same length as the list \code{x}. The attribute \code{"message"}\r
+    should be a character vector of any length.\r
     For \code{print.xtableList}, an object of class \code{xtableList}\r
     produced by a call to \code{xtableList}.}\r
   \item{caption}{Character vector of length 1 or 2 containing the\r
@@ -247,14 +252,54 @@ xtableList(x, caption = NULL, label = NULL,
   \item{\dots}{Additional arguments.  (Currently ignored.)}\r
 }\r
 \details{\r
-%%  ~~ If necessary, more details than the description above ~~\r
+  \code{xtableList} produces an object suitable for printing using\r
+  \code{print.xtableList}.\r
+\r
+  The elements of the list \code{x} supplied to \code{xtableList} must\r
+  all have the same structure. When these list items are submitted to\r
+  \code{xtable} the resulting table must have the same number of columns\r
+  with the same column names and type of data.\r
+\r
+  The values supplied to arguments \code{digits} and \code{display},\r
+  must be composed of elements as specified in those same arguments for\r
+  the function \code{\link{xtable}}. See the help for\r
+  \code{\link{xtable}} for details.\r
+\r
+  \code{print.xtableList} produces tables in two different formats\r
+  depending on the value of \code{col.names.format}. If\r
+  \code{col.names.format = "single"}, the resulting table has only a\r
+  single heading row. If \code{col.names.format = "multiple"} there is a\r
+  heading row for each of the subtables making up the complete table.\r
+\r
+  By default if \code{col.names.format = "single"}, there are horizontal\r
+  lines above and below the heading row, and at the end of each\r
+  subtable. If \code{col.names.format = "multiple"}, there are\r
+  horizontal lines above and below each appearance of the heading row,\r
+  and at the end of each subtable.\r
+\r
+  If \code{"subheadings"} is not \code{NULL}, the individual elements of\r
+  this vector (which can include newlines \verb{\\n}) produce a heading\r
+  line or lines for the subtables. When \code{col.names.format =\r
+    "multiple"} these subheadings appear \emph{above} the heading rows.\r
+\r
+  If \code{"message"} is not \code{NULL} the vector produces a line or\r
+  lines at the end of the table.\r
+\r
+  Consult the vignette \sQuote{The \code{xtableList} Gallery} to see\r
+  the behaviour of these functions.\r
+\r
+  Note that at present there is no code for \code{type = "html"}.\r
 }\r
 \value{\r
-%%  ~Describe the value returned\r
-%%  If it is a LIST, use\r
-%%  \item{comp1 }{Description of 'comp1'}\r
-%%  \item{comp2 }{Description of 'comp2'}\r
-%% ...\r
+  \code{xtableList} produces an object of class\r
+  \code{"xtableList"}. An object of this class is a list of\r
+  \code{"xtable"} objects with some additional attributes. Each element\r
+  of the list can have a \code{"subheading"} attribute. The list can\r
+  also have a \code{"message"} attribute.\r
+\r
+  \code{print.xtableList} produces a character string containing LaTeX\r
+  markup which produces a nicely formatted table comprised of subtables,\r
+  when included in a LaTeX document.\r
 }\r
 \author{\r
   David Scott \email{d.scott@auckland.ac.nz}.\r
@@ -269,8 +314,18 @@ xtableList(x, caption = NULL, label = NULL,
 \seealso{\r
   \code{\link{xtable}}, \code{\link{caption}}, \code{\link{label}},\r
   \code{\link{align}}, \code{\link{digits}}, \code{\link{display}},\r
-  \code{\link{formatC}}\r
+  \code{\link{formatC}}, \code{\link{print.xtable}}.\r
 }\r
 \examples{\r
+data(mtcars)\r
+mtcars <- mtcars[, 1:6]\r
+mtcarsList <- split(mtcars, f = mtcars$cyl)\r
+attr(mtcarsList, "subheadings") <- paste0("Number of cylinders = ",\r
+                                          names(mtcarsList))\r
+attr(mtcarsList, "message") <- c("Line 1 of Message",\r
+                                 "Line 2 of Message")\r
+xList <- xtableList(mtcarsList)\r
+print.xtableList(xList)\r
+print.xtableList(xList, colnames.format = "multiple")\r
 }\r
 \keyword{ print }\r