1% File src/library/utils/man/prompt.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2014 R Core Team
4% Distributed under GPL 2 or later
5
6\name{prompt}
7\title{Produce Prototype of an R Documentation File}
8\alias{prompt}
9\alias{prompt.default}
10\alias{prompt.data.frame}
11\alias{promptImport}
12\description{
13  Facilitate the constructing of files documenting \R objects.
14}
15\usage{
16prompt(object, filename = NULL, name = NULL, \dots)
17
18\method{prompt}{default}(object, filename = NULL, name = NULL,
19       force.function = FALSE, \dots)
20
21\method{prompt}{data.frame}(object, filename = NULL, name = NULL, \dots)
22
23promptImport(object, filename = NULL, name = NULL,
24	importedFrom = NULL, importPage = name, ...)
25}
26\arguments{
27  \item{object}{an \R object, typically a function for the default
28    method.  Can be \code{\link{missing}} when \code{name} is specified.}
29  \item{filename}{usually, a \link{connection} or a character string giving the
30    name of the file to which the documentation shell should be written.
31    The default corresponds to a file whose name is \code{name} followed
32    by \code{".Rd"}.  Can also be \code{NA} (see below).}
33  \item{name}{a character string specifying the name of the object.}
34  \item{force.function}{a logical.  If \code{TRUE}, treat \code{object}
35    as function in any case.}
36  \item{\dots}{further arguments passed to or from other methods.}
37  \item{importedFrom}{a character string naming the package from
38    which \code{object} was imported.  Defaults to the environment
39    of \code{object} if \code{object} is a function.}
40  \item{importPage}{a character string naming the help page
41    in the package from which \code{object} was imported.}
42}
43\value{
44  If \code{filename} is \code{NA}, a list-style representation of the
45  documentation shell.  Otherwise, the name of the file written to is
46  returned invisibly.
47}
48\details{
49  Unless \code{filename} is \code{NA}, a documentation shell for
50  \code{object} is written to the file specified by \code{filename}, and
51  a message about this is given.  For function objects, this shell
52  contains the proper function and argument names.  R documentation
53  files thus created still need to be edited and moved into the
54  \file{man} subdirectory of the package containing the object to be
55  documented.
56
57  If \code{filename} is \code{NA}, a list-style representation of the
58  documentation shell is created and returned.  Writing the shell to a
59  file amounts to \code{cat(unlist(x), file = filename, sep = "\\n")},
60  where \code{x} is the list-style representation.
61
62  When \code{prompt} is used in \code{\link{for}} loops or scripts, the
63  explicit \code{name} specification will be useful.
64
65  The \code{importPage} argument for \code{promptImport} needs to give
66  the base of the name of the
67  help file of the original help page.  For example,
68  the \code{\link{approx}} function is documented in \file{approxfun.Rd}
69  in the \pkg{stats} package, so if it were imported and re-exported
70  it should have \code{importPage = "approxfun"}.
71  Objects that are imported from other packages are not
72  normally documented unless re-exported.
73}
74\note{
75  The documentation file produced by \code{prompt.data.frame} does not
76  have the same format as many of the data frame documentation files in
77  the \pkg{base} package.  We are trying to settle on a preferred
78  format for the documentation.
79}
80\section{Warning}{
81  The default filename may not be a valid filename under limited file
82  systems (e.g., those on Windows).
83
84  Currently, calling \code{prompt} on a non-function object assumes that
85  the object is in fact a data set and hence documents it as such.  This
86  may change in future versions of \R.  Use \code{\link{promptData}} to
87  create documentation skeletons for data sets.
88}
89\seealso{
90  \code{\link{promptData}}, \code{\link{help}} and the chapter on
91  \sQuote{Writing R documentation} in \sQuote{Writing R Extensions}
92  (see the \file{doc/manual} subdirectory of the \R source tree).
93
94  For creation of many help pages (for a package),
95  see \code{\link{package.skeleton}}.
96
97  To prompt the user for input, see \code{\link{readline}}.
98}
99\author{Douglas Bates for \code{prompt.data.frame}}
100\references{
101  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
102  \emph{The New S Language}.
103  Wadsworth & Brooks/Cole.
104}
105\examples{
106require(graphics)
107\dontshow{oldwd <- setwd(tempdir())}
108prompt(plot.default)
109prompt(interactive, force.function = TRUE)
110unlink("plot.default.Rd")
111unlink("interactive.Rd")
112
113prompt(women) # data.frame
114unlink("women.Rd")
115
116prompt(sunspots) # non-data.frame data
117unlink("sunspots.Rd")
118
119\dontshow{setwd(oldwd)}
120\dontrun{
121## Create a help file for each function in the .GlobalEnv:
122for(f in ls()) if(is.function(get(f))) prompt(name = f)
123}
124
125}
126\keyword{documentation}
127