1% File src/library/utils/man/promptPackage.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2017 R Core Team
4% Distributed under GPL 2 or later
5
6\name{promptPackage}
7\alias{promptPackage}
8\title{Generate a Shell for Documentation of a Package}
9\description{
10  Generates a shell of documentation for an installed or source package.
11}
12\usage{
13promptPackage(package, lib.loc = NULL, filename = NULL,
14              name = NULL, final = FALSE)
15}
16\arguments{
17  \item{package}{a \code{\link{character}} string with the name of an
18    \emph{installed} or \emph{source} package to be documented.}
19  \item{lib.loc}{a character vector describing the location of \R
20    library trees to search through, or \code{NULL}.  The default value
21    of \code{NULL} corresponds to all libraries currently known.  For a
22    source package this should specify the parent directory of the
23    package's sources.}
24  \item{filename}{usually, a \link{connection} or a character string giving the
25    name of the file to which the documentation shell should be written.
26    The default corresponds to a file whose name is \code{name} followed
27    by \code{".Rd"}.  Can also be \code{NA} (see below).}
28  \item{name}{a character string specifying the name of the help topic,
29    typically of the form \samp{<pkg>-package}.}
30  \item{final}{a logical value indicating whether to attempt to
31    create a usable version of the help topic, rather than just a shell.}
32}
33\value{
34  If \code{filename} is \code{NA}, a list-style representation of the
35  documentation shell.  Otherwise, the name of the file written to is
36  returned invisibly.
37}
38\details{
39  Unless \code{filename} is \code{NA}, a documentation shell for
40  \code{package} is written to the file specified by \code{filename}, and
41  a message about this is given.
42
43  If \code{filename} is \code{NA}, a list-style representation of the
44  documentation shell is created and returned.  Writing the shell to a
45  file amounts to \code{cat(unlist(x), file = filename, sep = "\\n")},
46  where \code{x} is the list-style representation.
47
48  If \code{final} is \code{TRUE}, the generated documentation will not
49  include the place-holder slots for manual editing, it will be usable
50  as-is.  In most cases a manually edited file is preferable (but
51  \code{final = TRUE} is certainly less work).
52}
53\seealso{\code{\link{prompt}}, \code{\link{package.skeleton}}
54}
55\examples{\donttest{
56filename <- tempfile()
57promptPackage("utils", filename = filename)
58file.show(filename)
59unlink(filename)
60}}
61\keyword{documentation}
62