>>>>> "Kurt" == Kurt Hornik
<Kurt.Hornik@ci.tuwien.ac.at> writes:
Kurt> Does anyone have a description of the S help format? -k
Not really, here is what you get from ?prompt in S-plus
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.
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
--------------------------
Why do you need it?
Thomas Lumley has posted a nice 'S-help-to-Rhelp' script on the
R-testers list
on Tue, 24 Sep 1996 08:53:34 -0700 (PDT).
It contains quite a bit of implicit documentation on the S-help format.
I've been using it a few times more or less successfully.
YES: This should come in the $RHOME/etc/ directory !
- Martin
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
r-devel mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !) To:
r-devel-request@stat.math.ethz.ch
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-