Construct Documentation for Function or Data
DESCRIPTION:
Produces a file that can be edited and then nroffed or troffed to give documentation (a helpfile) for a function or dataset.
USAGE: 
prompt(object, filename=<<see below>>)
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.d, where name is the character string resulting from deparsing the object name.
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 will eventually be used by the help function to produce documentation for the object. As produced by prompt, the file for a function will contain the call to the function and individual sections for each of the arguments. The file for a data frame will contain the name of the data frame, its dimensions, and individual sections for each of the variables in the data frame.
DETAILS:
This is a generic function; there is a method for data frames and a default method.

You will 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. Lines in the file that contain "~" should be replaced with appropriate information. Arguments that must be specified in the name=value form should have an equal sign (=) added after name on the .AG name line.

To add a section such as "WARNING" make a line beginning with ".SH" (for example, ".SH WARNING") and put the information on subsequent lines. A line consisting of ".ul" italicizes the next line.

The correct order of sections for help files created with prompt.default is as follows: Title, Description, Usage, Required Arguments, Optional Arguments, ".GR" (graphics parameters), 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 with prompt.data.frame is as follows: Title, Summary, Data Description, Source, Note, Warning, See Also, Examples.

Be sure to leave the line .WR at the end of file; this wraps things up neatly. If you see the message trap botch, it is probably from a help file without a .WR.

For a full description of the formatting macros available in help files, see the section Documenting Your Module in the chapter Developing New Modules in the S-PLUS Programmer's Manual.

Documentation for functions and data resides (as ordinary text files) in a subdirectory called .Help 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 should be moved into the .Help directory with the command mv myfun.d /usr/me/.Data/.Help/myfun To see more about how documentation files are organized, look at some examples. Documentation files for functions are in the directories $SHOME/s/.Functions/.Help, $SHOME/stat/.Functions/.Help and $SHOME/splus/.Functions/.Help where $SHOME is the S-PLUS home directory. Type !echo $SHOME/s/.Functions/.Help from inside S-PLUS to see where this is on your machine.

Keywords define the categories in the help window and in the index by category in the S-PLUS Reference Manual. The keywords and their titles are: sysdata - All Datasets aplot - Add to Existing Plot 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 design - Designed Experiments 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 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 multivariate - Multivariate Techniques nonlinear - Non-linear Regression nonparametric - Nonparametric Statistics optimize - Optimization print - Printing distribution - Probability Distributions and Random Numbers programming - Programming regression - Regression tree - Regression and Classification Trees robust - Robust/Resistant Techniques smooth - Smoothing Operations environment - S-PLUS Session Environment htest - Statistical Inference models - Statistical Models survival - Survival Analysis ts - Time Series utilities - Utilities

You can find more information in the chapter Enhancing S-PLUS of the S-PLUS Installation and Maintenance Manual in the sections entitled Adding Help Files for New Functions and Modifying S-PLUS Keywords.

SEE ALSO:
The section "Documenting Your Module" in the chapter "Developing New Modules" of the S-PLUS Programmer s Manual.

help, help.start, Question.mark.

EXAMPLES: 
prompt("mygrep")        # construct mygrep.d file
!vi mygrep.d  # fix up the documentation
!mkdir .Data/.Help      # if necessary, construct subdirectory
!mv mygrep.d .Data/.Help/mygrep # install