[Rd] NEWS vs. inst/NEWS

[William Dunlap]

'Writing R Extensions', section 1.1.5, in the part about a package's 'inst'
directory, says that if NEW is in both the top level and in the inst
directory, the in inst will be installed:

Note that with the exceptions of INDEX, LICENSE/LICENCE and NEWS,
information files at the top level of the package will *not* be installed
and so not be known to users of Windows and macOS compiled packages (and
not seen by those who use R CMD INSTALL or install.packages on the
tarball). So any information files you wish an end user to see should be
included in inst. Note that if the named exceptions also occur in inst, the
version in inst will be that seen in the installed package.

However, if I have a package with a NEWS file in both the top-level and in
the inst directory, the top-level one appears in the installed file, not
the one in inst.

Try the following script that makes and installs a package in tempdir():
pkgName <- "junk"
dir.create(tdir <- tempfile())
dir.create(srcPkg <- file.path(tdir, pkgName))
cat(file=file.path(srcPkg, "DESCRIPTION"), sep="\n",
   paste("Package:", pkgName),
   paste("Title: NEWS vs. inst/NEWS"),
   paste("Description: Which is installed, NEWS or inst/NEWS?"),
   paste("Version: 0.1"))
file.create(file.path(srcPkg, "NAMESPACE"))
dir.create(inst <- file.path(srcPkg, "inst"))

instFiles <- c("NEWS", "CITATION") # these both at top-level and in inst
directory
for(instFile in instFiles) {
   cat(file=file.path(srcPkg, instFile), sep="\n",
       paste0("The original top-level ", instFile, " file"))
   cat(file=file.path(inst, instFile), sep="\n",
       paste0("inst/", instFile, " - the ", instFile, " file from the
source package's inst directory"))
}

dir.create(lib <- file.path(tdir, "lib"))
install.packages(lib=lib, srcPkg, repos=NULL, type="source")
sapply(instFiles, function(instFile) readLines(system.file(package=pkgName,
lib.loc=lib, mustWork=TRUE, instFile)))
# unlink(recursive=TRUE, tdir) # to clean up

The final sapply() gives me
> sapply(instFiles, function(instFile)
readLines(system.file(package=pkgName, lib.loc=lib, mustWork=TRUE,
instFile)))
                                                                        NEWS
                                          "The original top-level NEWS file"
                                                                    CITATION
"inst/CITATION - the CITATION file from the source package's inst directory"

Several CRAN packages have both NEWS and inst/NEWS (gdata, genetics,
gplots, mcgibbsit, modeltools, nimble, RRF, session, SII).  In most the two
files are identical but in RRF and nimble they differ.

Is the manual wrong is the code wrong?


Bill Dunlap
TIBCO Software
wdunlap tibco.com

	[[alternative HTML version deleted]]