[Rd] ordering in R CMD build & R CMD Rdindex

Kurt Hornik Kurt.Hornik@ci.tuwien.ac.at
Sun, 18 Jun 2000 12:28:39 +0200

>>>>> Paul Gilbert writes:

> This is a synopsis for the r-devel archives of my solution to the problem that
> R CMD Rdindex zzz/man/* >INDEX
> and
> R CMD build zzz

> do not always result in the same order, which causes make problems outlined
> further below. The source of the problem was suggested by Brian Ripley:

BDR> The shell expands the * before Rdindex ever gets hold of it. And what it
BDR> does re locales is an installation default (assuming it is a Solaris shell
BDR> not bash or tcsh, for both of which NLS support is optional).

> The need to build INDEX separately from using the one generated by
> build is so that R INSTALL zzz does not require R CMD build zzz
> first. This means that code changes can be tested separately from
> documentation changes and vice versa, thus remakes are faster.

> INDEX needs to be generated in the same order as produced by R CMD
> build or build's diff comparison suggests that the index is out of
> date and suggests using --force. Using --force rewrites INDEX which
> causes make to think the install is out of date, so the next make
> always starts at the beginning again.

> The * expansion (in Solaris sh) does not seem to recognize LC (locale)
> settings. Sort does, but some of the output of R CMD Rdindex is on two
> lines, so sorting the output does not work. It is possible to ls -1
> man/* | sort and get the locale sort order, but it does not seem
> possible to feed this into "R CMD Rdindex". ( LC_COLLATE is not
> adequate for sort, LC_ALL is needed.)

> The fix is to generate INDEX in the C order imposed by the Solaris sh
>  expansion of *, then set LC_ALL=C for R CMD build.

Maybe I miss something here, but ...

What R CMD build currently does to list the Rd files in a package is

	find man -name "*.[Rr]d" -print | sort

When building the indices this list is fed to R CMD Rdindex.

On the other hand, R CMD Rdindex itself simply loops through the list of
Rd files it was given as arguments, without any reordering (which I
think is what it should do).

Now note that R CMD Rdindex dates back to a time where we did not have R
CMD build.  Now that we have it, I am inclined to say that when you
start with a package, you simply use R CMD build to bundle it up, and
this will automatically build the index for you (without having to worry
about the ordering), i.e., I would consider Rdindex as something more

But in any case, I recommend we do the following:

* Extend Rdindex so that if one of its arguments is a directory, it
obtains the list of Rd files as done by R CMD build.

* In both cases, ensure e.g. the C order for consistency.  I.e., R CMD
build and Rdindex should both do LC_ALL=C.

Note that currently we are not very smart building indices, because the
name/alias scheme of Rd is not powerful enough.  1.2 may have something
like an \index entry allowing to specify the information that should go
into the INDEX (and searchable indices etc.).

r-devel 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-devel-request@stat.math.ethz.ch