Construct Documentation for Function or Data

DESCRIPTION:

By default, produces a file in SGML format that can be edited to provide documentation (a helpfile) for a function or dataset.

USAGE:

prompt(object, filename=<<see below>>, oldDoc=F, format="sgml")

REQUIRED ARGUMENTS:

object
name or character string giving the name of a function or data object.

OPTIONAL ARGUMENTS:

filename
filename for resulting documentation; the default is name.sgml, where name is the character string resulting from deparsing the object name.
oldDoc
logical flag; if TRUE, the file is in the S version 3 format, with a .d rather than a .sgml extension. This can be converted to an sgml file using the d_to_S utility. This format is deprecated and its use is discouraged.
format
a character string giving the format for the help file. Possible values are: "sgml" (the default), "Rd" and "d". The "Rd" format is the help file format used by R and it is used in S-PLUS packages. Setting format="d" creates files in the deprecated S version 3 format and is equivalent to setting oldDoc=T.

SIDE EFFECTS:

A file is written, containing an outline for documenting the function or object. A message is printed to the screen giving the name of the created file. The file is eventually used by the help function to display documentation for the object. As produced by prompt, the file for a function contains the call to the function and individual sections for each of the arguments. The file for a data frame or bdFrame contains the name of the data frame or bdFrame, its dimensions, and individual sections for each of the variables in the data frame or bdFrame.

DETAILS:

This is a generic function; there is a method for data frames and bdFrames and a default method.

You need to fill in the actual information about the arguments, a description of the value returned by the function, examples, and whatever other information is appropriate. Instructions in the file in the form of SGML comments, such as

         <!--function-to-do???-->

should be replaced with appropriate information. Arguments that must be specified in the name=value form should have an equal sign (=) added after name in the tag.

To add a section such as "WARNING" use the form and put the information on subsequent lines.

The correct order of sections for help files for a function is as follows: Title, Description, Usage, Required Arguments, Optional Arguments, Value, Side Effects, Warning, Details, Background, References, See Also, Examples, Keywords. The "Note" section, if it appears, may be anywhere between Side Effects and References.

The correct order of sections for help files created for a data frame is as follows: Title, Summary, Data Description, Source, Note, Warning, See Also, Examples.

Be sure to properly close all your SGML tags.

For a full description of the formatting macros available in help files, see the section Creating Help Files in the S-PLUS Programmer's Guide.

Documentation for functions and data resides (as ordinary text files) in a subdirectory called __Shelp under the directory containing the S-PLUS objects themselves. For example, if you are documenting a function myfun in the directory /usr/me/.Data, the completed documentation file is moved into the __Shelp directory with the command Splus HINSTALL .Data myfun.sgml To include your files in the JavaHelp index, run the Splus make install.help, as described in the section User-Defined Help in the S-PLUS 6.1 for UNIX Supplement. To see more about how documentation files are organized, look at some examples. Documentation files for functions are in the directories $SHOME/library/splus/.Data/__Shelp, $SHOME/library/stat/.Data/__Shelp and $SHOME/library/main/.Data/__Shelp where $SHOME is the S-PLUS home directory. Type getenv("SHOME") from inside S-PLUS to see where this is on your machine.

Keywords define the categories in the help window. The keywords and their titles are:
sysdata -- All Datasets
aplot -- Add to Existing Plot
design -- ANOVA Models
bigdata -- Big Data Library
bootstrap -- Bootstrap Methods
category -- Categorical Data
character -- Character Data Operations
cluster -- Clustering
complex -- Complex Numbers
dplot -- Computations Related to Plotting
attribute -- Data Attributes
data -- Data Directories
manip -- Data Manipulation
classes -- Data Types
deprecated -- Deprecated Functions
documentation -- Documentation
dynamic -- Dynamic Graphics
error -- Error Handling
device -- Graphical Devices
hplot -- High-Level Plots
file -- Input/Output--Files
iplot -- Interacting with Plots
interface -- Interfaces to Other Languages
jackknife -- Jackknife Methods
algebra -- Linear Algebra
list -- Lists
loess -- Loess Objects
logic -- Logical Operators
iteration -- Looping and Iteration
math -- Mathematical Operations
array -- Matrices and Arrays
methods -- Methods and Generic Functions
misc -- Miscellaneous
missing -- Missing Values
mixed -- Mixed Effects Models
multivariate -- Multivariate Techniques
nonlinear -- Nonlinear Regression
nonparametric -- Nonparametric Statistics
optimize -- Optimization
ode -- Ordinary Differential Equations
print -- Printing
distribution -- Probability Distributions and Random Numbers
programming -- Programming
qc -- Quality Control
regression -- Regression
tree -- Regression and Classification Trees
resample -- Resampling (Bootstrap, Jackknife, and Permutations)
robust -- Robust/Resistant Techniques
smooth -- Smoothing Operations
environment -- S-PLUS Session Environment
htest -- Statistical Inference
models -- Statistical Models
survival4 -- Survival Analysis
ts -- Time Series
trellis -- Trellis Graphics
utilities -- Utilities

SEE ALSO:

, , .

EXAMPLES:

prompt(mygrep, filename="/homes/lenk/mygrep.sgml")
!vi mygrep.sgml  # fix up the documentation 
!Splus make install.help  # install the help