From Kurt.Hornik@ci.tuwien.ac.at  Wed Mar 31 08:11:07 1999
From: Kurt.Hornik@ci.tuwien.ac.at (Kurt Hornik)
Date: Wed, 31 Mar 1999 09:11:07 +0200 (CEST)
Subject: Documenting data sets
In-Reply-To: <Pine.GSO.4.05.9903310651470.27074-100000@auk.stats>
References: <6r677iczb1.fsf@verdi.stat.wisc.edu>
 <Pine.GSO.4.05.9903310651470.27074-100000@auk.stats>
Message-ID: <14081.51851.302864.493919@pc87.maho.magnaeu.com>

>>>>> Prof Brian D Ripley writes:

> On 30 Mar 1999, Douglas Bates wrote:
>> Has a format for the documentation of data sets been established?  The
>> prompt function applied to a data set produces a brief outline.  I
>> notice that the data documentation in the MASS library, for example,
>> is more complete.

> That was translated from Sd. On S-PLUS there are two formats for data
> given by prompt.data.frame and prompt.default (for all
> non-functions). Over the years we have expanded the dataset
> documentation: for example I tried about a year ago to give references
> wherever possible.

prompt.data.frame() sounds like a nice idea.

In general, I think the format should be something like

	\name{}
	\alias{}
	\title{}
	\usage{data(...)}
	\description{}
	\format{}
	\details{}
	\source{}
	\examples{}
	\keyword{datasets}

but we should perhaps standardize the `format' slot a bit more.

> It would be helpful to have more for this sort of thing in R. One
> thing I find problematic is the use of \item: I find quite often that
> the use of items (.AG or .RC) in .Sd format translates to invalid
> .Rd. There are restrictions on the use of \item (as we saw for nlm.Rd)
> that could do with being lifted. I need to give more thought to
> exactly what, though.

Give Fritz a chance to look into Doug's Perl5 module a bit more.  This,
as I have been told, will also get \enumerate{} and description lists to
work.

-k
-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-devel mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-devel-request@stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._


Documenting data sets
Kurt Hornik