[R] First R Package --- Advice?

[Duncan Murdoch]

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