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

An embedded and charset-unspecified text was scrubbed...
Name: not available
URL: <https://stat.ethz.ch/pipermail/r-help/attachments/20130202/f6411f03/attachment.pl>
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.

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.
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
A  related approach which, if memory serves, was originally in S eons
ago, is to define a "doc" attribute of any function (or object, for
that matter)  that you wish to document that contains text for
documentation and a doc() function of the form:

doc <- function(obj) cat(attr(obj,"doc"))

used as:
f- function(x) NULL
attr(f,"doc") <- "Some text\n\n"
doc(f)
doc(f)
Some text

This is pretty primitive, but I suppose you could instead have the
attribute point to something like an HTML file and the doc() function
open it in a web browser, which is basically what R's built-in package
document system does anyway. Except you wouldn't have to build a
package and don't have to learn or follow R's procedures. Which means
you don't get  R's standardization and organization and no one but a
private bunch of users will be able to use your function. But maybe
that's sufficient for your needs.

-- Bert

On Sat, Feb 2, 2013 at 10:01 PM, Gabor Grothendieck
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

______________________________________________
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.

Bert Gunter
Genentech Nonclinical Biostatistics

Internal Contact Info:
Phone: 467-7374
Website:
http://pharmadevelopment.roche.com/index/pdb/pdb-functional-groups/pdb-biostatistics/pdb-ncb-home.htm
A  related approach which, if memory serves, was originally in S eons
ago, is to define a "doc" attribute of any function (or object, for
that matter)  that you wish to document that contains text for
documentation and a doc() function of the form:

doc <- function(obj) cat(attr(obj,"doc"))

used as:

f- function(x) NULL
attr(f,"doc") <- "Some text\n\n"
doc(f)
doc(f)
Some text

This is pretty primitive, but I suppose you could instead have the
attribute point to something like an HTML file and the doc() function
open it in a web browser, which is basically what R's built-in package
document system does anyway. Except you wouldn't have to build a
package and don't have to learn or follow R's procedures. Which means
you don't get  R's standardization and organization and no one but a
private bunch of users will be able to use your function. But maybe
that's sufficient for your needs.

To further build on this try the above idea using the comment function:
f <- function() NULL
comment(f) <- "Help goes here"

comment(f)
[1] "Help goes here"

or combine it with the redefinition of ? like like this:

`?` <- function(...) if (!is.null(doc <-
comment(get(match.call()[[2]])))) cat(doc, "\n") else help(...)
?f    #  displays:  Help goes here
?dim   # normal help

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