R-alpha: S-help (and S-help-to-R-help)

[Martin Maechler]

>>>>> "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
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-