On 13-02-05 7:43 PM, ivo welch wrote:
Dear R experts---
after many years, I am planning to give in and write my first R
package. I want to combine my collection of collected useful utility
routines.
as my guide, I am planning to use Friedrich Leisch's "Creating R
Packages: A Tutorial" from Sep 2009. Is there a newer or better
tutorial? this one is 4 years old.
I also plan on one change---given that the package.skeleton() function
writes all the individual man[ual] functions, I am thinking it would
be a good idea to put the doc and the R code together in the same
file, one for each function. Interestingly enough, the code is by
default in the \examples{} section, so I am thinking of writing a perl
program that takes every .Rd file and writes the function into the R/
directory, overwriting anything else that is already there. this way,
I maintain only one file for each function, and the docs and code are
together. sort of like knuth's literate programming and the
numerical-recipees approach to keeping each function in its own file
with equal name.
I have heard of people using noweb to do this, but I can't point to any
examples. I'd actually recommend against it. Good documentation files
don't make good source files.
If you really want close connections between your source and the user
documentation, I think that's the job of your IDE. (I don't find this
to be a problem, so I don't use an IDE that attempts this, but I believe
they exist: I'd look at ESS, RStudio, RKWard if I was in the market for
that.)
Other people have recommended Roxygen, but honestly I haven't seen a
package documented with Roxygen where the documentation was adequate.
It looks as though it's great to get initial documentation created, but
does not appear to encourage followup.
I believe my "try-out and debug cycle" will then be
$ cd iaw ## the package name and top directory is iaw
$ perl weaveall.pl ## extract all man/*.Rd files code examples
and place them in R/
$ R CMD INSTALL iaw
$ R CMD check iaw
I wouldn't put the last step in this cycle. Have a separate check
cycle, which includes a build step, and checks the built tarball.
good idea? bad idea? common? uncommon?
I do not understand the namespace mechanism yet. I understand the
NAMESPACE file, and I think this lists the routines that become
visible when a later program of mine contains 'library(iaw)'. I think
I want to explicitly declare what packages are actually imported.
?importIntoEnv tells me that it is not intended to be used. how can
another program declare exactly what functions it wants to import?
(frankly, I would love to turn all default autovivification off in my
program, but that's not possible.)
I am not sure I know what you mean by "program", but the NAMESPACE file
allows you to declare which functions you want to import from other
packages. I think it is not as strict as you want: if you don't
declare it, you might still find it, but if you do declare it, you'll
find that version before any user-created or other-package-created one.
It might be a good idea for R to allow a package to request the strict
declaration model, where you need to declare *every* import. I don't
know how difficult a change that would be.
Duncan Murdoch
/iaw
----
Ivo Welch (ivo.we...@gmail.com)
______________________________________________
R-help@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.
______________________________________________
R-help@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.
