[R] how to create help files

[Prof Brian Ripley]

On Fri, 29 Dec 2000, RINNER Heinrich wrote:

> Dear R users,
> 
> this is a question for R version 1.2.0 under Windows NT 4.0, regarding the
> documentation of ones own functions.
> I have ceated a private library for my functions, which works all very well,
> apart from that I am not able to create appropriate help files.

I think what you have done is faked the installation of a package, not
created a private library (which is a directory containing installed
packages).  Mis-using the notation will make it harder for us to help you
as well as for you to follow the docs.

> For illustration, here is a simple example of where I'm stuck:
> 
> > # first, create a simple function f1:
> > f1 <- function(x) x^2
> > # create directories where a package called "testfunctions" with my own
> functions will live:
> > R.home()
> [1] "D:\\Programme\\R\\rw1020"
> > mypath <- paste(R.home(),"\\library\\testfunctions", sep="")
> > mypath
> [1] "D:\\Programme\\R\\rw1020\\library\\testfunctions"
> > dir.create(mypath)
> > dir.create(paste(mypath, "\\R", sep=""))
> > # dump the function into file "testfunctions"
> > dump("f1", file = paste(mypath, "\\R\\testfunctions", sep=""))
> > # very well, now let's try to add documentation:
> > dir.create(paste(mypath, "\\help", sep=""))
> > prompt(f1, file = paste(mypath, "\\help\\f1", sep=""))
> created file named  D:\Programme\R\rw1020\library\testfunctions\help\f1  in
> the current directory.
>   Edit the file and move it to the appropriate directory,
> D:\Programme\R\rw1020/src/library/<pkg>/man/ 
> > # let's see if it works:
> > rm(f1)
> > library(testfunctions)
> > find(f1)
> [1] "package:testfunctions"
> > f1(3)
> [1] 9
> > # very well so far!
> > # now, what about the documentation:
> > help(f1)
> Error in help(f1) : No documentation for `f1' in specified packages and
> libraries
> 
> And that's where I'm stuck. Not that it comes as a surprise to me that this
> doesn't work. I do have the "Writing R extensions" manual right here in

Yes, you forgot to INSTALL the package.  However, you've done a lot of
guessing about undocumented things to get this far (wherever did you get
that prompt line from), so actually following the documentation cannot be
as difficult?

> front of me, and I have read "readme.packages", but I have to admit that I
> am a bit lost in the documentation. I do have installed "rw1020sp.zip", I
> have downloaded "http://www.stats.ox.ac.uk/pub/Rtools/tools.zip", and I
> guess I have to use  those MAKE, INSTALL, RCMD etc. facilities in an
> appropriate way. But I just can't put the pieces together. (Please note that
> I don't need to build a "professional" package at the moment (with
> description files and all that stuff)).

Oh, but you do need them or the tools won't work.  And you need Perl
installed.

> If someone could point out how to procede in my simple example and how to
> make "help(f1)" work, it would be easier for me to figure out how to do
> these things generally. Maybe something like "Open a WindowsNT command
> window, got to directory xyz, and run the command(s) abc, ..."?
> 

Open a commands window in any convenient directory, e.g.
...\rw1020\src\library.

Make a directory testfunctions and sub-directories R and man.

Put the file f1.Rd in testfunctions/man, and remove
..\rw1020\src\library\testfunctions\help

Put your R code in testfunctions/R (which you had in
D:\Programme\R\rw1020\library\testfunctions\R, I guess) as a file with
extension .R

Create a DESCRIPTION file in testfunctions.

[Optionally run Rcmd build testfunctions  to create indices.]

Run Rcmd INSTALL testfunctions


Alternatively,

Open a commands window in ...\rw1020\src\library.

Make a directory testfunctions and sub-directories R and man.

Put the file f1.Rd in testfunctions/man

change directory to ...\rw1020\src\gnuwin32

Run make help-testfunctions

-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272860 (secr)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595

-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-help 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-help-request at stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._