thanks for the responses. this is what I have learned so far: primarily, I need to learn roxygen2 and devtools, because they do what I was planning to reinvent.
roxygen2 allows R users to write R code that embeds its documentation. the .R user source file has a family semblance with POD (perl's plain old documentation), although pod looks cleaner because it does not need the '#' comments. all roxygen2 documentation commands are interspersed as comments, and presumably devtools creates the .Rd files from such .R files in devtool's package build stage. it is not clear to me whether every function must or should get its own .R file now (just like each R function has its own .Rd file). in "Getting Started with RStudio", there is a brief 1-pager on roxygen2, which gave me a flavor of what it is. there is also a stackoverflow with links at http://stackoverflow.com/questions/4523513/good-reference-for-roxygen , but this is for oxygen not oxygen2, I think. then there is the standard roxygen2 standard documentation, but this is just the function man set and not a "how to get started" description. I don't think roxygen2 has a vignette, either. right now, I am wondering whether there is a skeleton creator for an existing function for roxygen2, which generates all the required .Rd fields as appropriate '#@' directives in the comments, just like the vanilla package skeleton creator in R creates them in the .Rd files. devtools is a package that can take roxygen2 .R files, compile the embedded comments into .Rd files into the man/ directory, and then rebuilds and reloads the package on the fly. (possibly also repackages them.) roughly speaking, I think it translates the more convenient new doc format into the old standard basic way to package packages, and also obviates the need to restart R. again, this is what I gleamed from the rstudio guide. so, the combination of devtools and oxygen2 seem to be exactly what I wanted, but I did not find the starter docs. what I would love to see is someone pointing me to a 1-page example of how a new user should take two real simple functions, say # my old sum remark sum1 <- function(x,y) (x+y) # my old difference remark difference1 <- function(x,y) (x-y) stopifnot( sum1(5,5) == 10 ) ## should become a testthat and make a (silly) package out of it. this intro should describe how the user should start by creating the package skeleton (say, package sumdiff), how one gets the roxygen2 skeletons for the two functions, how one builds and loads it (for testing), then how one would change it, e.g., by changing both functions to square the inputs, rebuild and reload. someone has probably already written this up, but it is difficult to find. I read some other package introductions, too, but they end up overbuilding the example and/or are better references than "get started guides." for example, the Leisch packaging introduction spends more than half of its space and the user's attention span (and in my case, brain cells) on peripheral aspects. yes, S3 and S4 functions, extending lm() etc., is all nice and useful, but teaching the basic logic of the R packaging system may be better done with functions that do almost nothing. contemplating the core logic of lm() extensions is distracting at the first baby steps. similarly, rstudio is a really nice IDE, but I don't think that roxygen2 and devtools need rstudio. could someone point me to a simpler "starting" document for roxygen2 and devtools, if such exists? regards, /iaw ---- Ivo Welch (ivo.we...@gmail.com) http://www.ivo-welch.info/ J. Fred Weston Professor of Finance Anderson School at UCLA, C519 Director, UCLA Anderson Fink Center for Finance and Investments Free Finance Textbook, http://book.ivo-welch.info/ Editor, Critical Finance Review, http://www.critical-finance-review.org/ On Tue, Feb 5, 2013 at 4:43 PM, ivo welch <ivo.we...@anderson.ucla.edu> 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 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 > > 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.) > > /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.