prompt                 package:utils                 R Documentation

Produce Prototype of an R Documentation File

Description:

     Facilitate the constructing of files documenting R objects.

Usage:

     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, ...)

Arguments:

  object: an R object, typically a function for the default method.

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
          'name' followed by '".Rd"'.  Can also be 'NA' (see below).

    name: a character string specifying the name of the object.

force.function: a logical.  If 'TRUE', treat 'object' as function in
          any case.

     ...: further arguments passed to or from other methods.

Details:

     Unless 'filename' is 'NA', a documentation shell for 'object' is
     written to the file specified by '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 'man'
     subdirectory of the package containing the object to be
     documented.

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

     When 'prompt' is used in 'for' loops or scripts, the explicit
     'name' specification will be useful.

Value:

     If 'filename' is 'NA', a list-style representation of the
     documentation shell.  Otherwise, the name of the file written to
     is returned invisibly.

Warning:

     The default filename may not be a valid filename under limited
     file systems (e.g. those on Windows).

     Currently, calling '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 'promptData' to
     create documentation skeletons for data sets.

Note:

     The documentation file produced by 'prompt.data.frame' does not
     have the same format as many of the data frame documentation files
     in the 'base' package.  We are trying to settle on a preferred
     format for the documentation.

Author(s):

     Douglas Bates for 'prompt.data.frame'

References:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

See Also:

     'promptData', 'help' and the chapter on "Writing R documentation"
     in "Writing R Extensions" (see the 'doc/manual' subdirectory of
     the R source tree).

     To prompt the user for input, see 'readline'.

Examples:

     require(graphics)
     prompt(plot.default)
     prompt(interactive, force.function = TRUE)
     unlink("plot.default.Rd")
     unlink("interactive.Rd")

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

     data(sunspots, package="stats") # non-data.frame data
     prompt(sunspots)
     unlink("sunspots.Rd")

