R help - Feb 2013 - Question: write an R script with help information available to the user

Dear All,

I would like to ask a question on how to incorporate into an R script help
information for the user. I vaguely recall that I saw some instructions on an R
manual, but am not able to figure them out. Hereunder is the basic setting:

1.  I finished writing an R script, my_script.r, that is a function (the
function is named "my_func") for a statistical procedure. This means
that the user only needs to:
source("directory_of_script\my_script.r"), then run, my_func(arg1,
arg2, ..), to execute the procedure.

2. I would like to add some lines into "my_script.r", so that a user
can get information on this file and function by using "?my_func"

Any help or suggestion is appreciated.
Best regards,
Chee
	[[alternative HTML version deleted]]

The normal expectations of an R user is that useful functions you want to share
are in packages, which include help files. There is no way to both avoid the
package development process and offer help to the user within R. Read the
Writing R Extensions document for the most up-to-date information about this
process. RStudio has some nice enhancements for making this process a little
quicker, but not so much that you can escape reading the documentation I just
mentioned. I happen to like using roxygen2 for building help files, but this
just means reading even more documentation.

If you are determined to use the source function instead of building a package,
then you cannot take advantage of the users' familiarity with the help
system. However, you could just put your instructions in comments in your R file
and hope they will look there.
---------------------------------------------------------------------------
Jeff Newmiller                        The     .....       .....  Go Live...
DCN:<jdnewmil at dcn.davis.ca.us>        Basics: ##.#.       ##.#.  Live
Go...
                                      Live:   OO#.. Dead: OO#..  Playing
Research Engineer (Solar/Batteries            O.O#.       #.O#.  with
/Software/Embedded Controllers)               .OO#.       .OO#.  rocks...1k
--------------------------------------------------------------------------- 
Sent from my phone. Please excuse my brevity.

Chee Chen <chen418 at purdue.edu> wrote:
>Dear All,
>
>I would like to ask a question on how to incorporate into an R script
>help information for the user. I vaguely recall that I saw some
>instructions on an R manual, but am not able to figure them out.
>Hereunder is the basic setting:
>
>1.  I finished writing an R script, my_script.r, that is a function
>(the function is named "my_func") for a statistical procedure.
This
>means that the user only needs to:
>source("directory_of_script\my_script.r"), then run, my_func(arg1,
>arg2, ..), to execute the procedure.
>
>2. I would like to add some lines into "my_script.r", so that a
user
>can get information on this file and function by using "?my_func"
>
>Any help or suggestion is appreciated.
>Best regards,
>Chee
>	[[alternative HTML version deleted]]
>
>______________________________________________
>R-help at r-project.org mailing list
>https://stat.ethz.ch/mailman/listinfo/r-help
>PLEASE do read the posting guide
>http://www.R-project.org/posting-guide.html
>and provide commented, minimal, self-contained, reproducible code.

On Sat, Feb 2, 2013 at 6:31 PM, Chee Chen <chen418 at purdue.edu>
wrote:
> Dear All,
>
> I would like to ask a question on how to incorporate into an R script help
information for the user. I vaguely recall that I saw some instructions on an R
manual, but am not able to figure them out. Hereunder is the basic setting:
>
> 1.  I finished writing an R script, my_script.r, that is a function (the
function is named "my_func") for a statistical procedure. This means
that the user only needs to:
source("directory_of_script\my_script.r"), then run, my_func(arg1,
arg2, ..), to execute the procedure.
>
> 2. I would like to add some lines into "my_script.r", so that a
user can get information on this file and function by using "?my_func"
>

You may wish to create a package from your script; however, if you
would prefer not then a workaround would be to redefine the ? function
in your script to provide some help.  For example if you had this line
in your script:

`?` <- function(...) if (match.call()[[2]] == "mytopic")
cat("whatever\n") else help(...)

then this would work:
> ?mytopic
whatever
> ?dim
where the last line launches normal help.  If you wish to display a
file rather than cat strings to the console then use: file.show


--
Statistics & Software Consulting
GKX Group, GKX Associates Inc.
tel: 1-877-GKX-GROUP
email: ggrothendieck at gmail.com