\HeaderA{prompt}{Produce Prototype of an R Documentation File}{prompt}
\methaliasA{prompt.data.frame}{prompt}{prompt.data.frame}
\methaliasA{prompt.default}{prompt}{prompt.default}
\keyword{documentation}{prompt}
\begin{Description}\relax
Facilitate the constructing of files documenting \R{} objects.
\end{Description}
\begin{Usage}
\begin{verbatim}
prompt(object, filename = NULL, name = NULL, ...)

## Default S3 method:
prompt(object, filename = NULL, name = NULL,
       force.function = FALSE, ...)

## S3 method for class 'data.frame':
prompt(object, filename = NULL, name = NULL, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] an \R{} object, typically a function for the default
method.
\item[\code{filename}] usually, a connection or a character string giving the
name of the file to which the documentation shell should be written.
The default corresponds to a file whose name is \code{name} followed
by \code{".Rd"}.  Can also be \code{NA} (see below).
\item[\code{name}] a character string specifying the name of the object.
\item[\code{force.function}] a logical.  If \code{TRUE}, treat \code{object}
as function in any case.
\item[\code{...}] further arguments passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Unless \code{filename} is \code{NA}, a documentation shell for
\code{object} is written to the file specified by \code{filename}, and
a message about this is given.  For function objects, this shell
contains the proper function and argument names.  R documentation
files thus created still need to be edited and moved into the
\file{man} subdirectory of the package containing the object to be
documented.

If \code{filename} is \code{NA}, a list-style representation of the
documentation shell is created and returned.  Writing the shell to a
file amounts to \code{cat(unlist(x), file = filename, sep = "\bsl{}n")},
where \code{x} is the list-style representation.

When \code{prompt} is used in \code{\LinkA{for}{for}} loops or scripts, the
explicit \code{name} specification will be useful.
\end{Details}
\begin{Value}
If \code{filename} is \code{NA}, a list-style representation of the
documentation shell.  Otherwise, the name of the file written to is
returned invisibly.
\end{Value}
\begin{Section}{Warning}
The default filename may not be a valid filename under limited file
systems (e.g. those on Windows).

Currently, calling \code{prompt} on a non-function object assumes that
the object is in fact a data set and hence documents it as such.  This
may change in future versions of \R.  Use \code{\LinkA{promptData}{promptData}} to
create documentation skeletons for data sets.
\end{Section}
\begin{Note}\relax
The documentation file produced by \code{prompt.data.frame} does not
have the same format as many of the data frame documentation files in
the \pkg{base} package.  We are trying to settle on a preferred
format for the documentation.
\end{Note}
\begin{Author}\relax
Douglas Bates for \code{prompt.data.frame}
\end{Author}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{promptData}{promptData}}, \code{\LinkA{help}{help}} and the chapter on
\dQuote{Writing \R{} documentation} in \dQuote{Writing \R{} Extensions}
(see the \file{doc/manual} subdirectory of the \R{} source tree).

To prompt the user for input, see \code{\LinkA{readline}{readline}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(graphics)
prompt(plot.default)
prompt(interactive, force.function = TRUE)
unlink("plot.default.Rd")
unlink("interactive.Rd")

prompt(women) # data.frame
unlink("women.Rd")

prompt(sunspots) # non-data.frame data
unlink("sunspots.Rd")
\end{ExampleCode}
\end{Examples}