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

[Paul Gilbert]

Kurt

>Maybe I miss something here, but ...

I'm not trying to make this into a big deal, but it did take me awhile
to track down so I thought it would be worth recording. Let me explain
the general problem a little more clearly, even though I think you do
understand it,  since someone may see a better overall solution.

I am trying to set up a good structure for package development, which
takes into account the eventuality that documentation testing may become
a more time consuming process. There seem to be two keys: small
independent packages and a reasonably clean separation of code changes
and testing from documentation changes and testing. These allow the
possibility of setting up a fairly efficient makefile.

Running "R CMD check zzz" for all my packages takes several hours on a
Sparc ultra 10 and the complete set of my other tests takes days to run.
I have been splitting things into smaller packages which are as
independent as I can make them, so that I can test pieces separately.
Now I want to set up my makefile so that I can work on documentation and
run the  "R CMD build zzz" tests without changing any file dates that
would indicate my installed code is out of date. If I change code rather
than documentation then I want make to recognize that and do "R INSTALL
zzz" but not "R CMD build zzz", since the build takes some time too.
(This has been a less serious consequence and until recently I was just
rebuilding each time.) Examples in the documentation are a gray area,
but since I have them all working I am thinking of them breaking when
code changes rather than when documentation changes, so I do "R CMD
check zzz" after I change code rather than after I change documentation.
My bundle has dependencies install, build, check for each of the
packages since the above split is not perfect (and I also run my own
tests).

Now the only bug in this whole approach seems to be the file INDEX which
is needed for R INSTALL and is also checked by R CMD build. If I
generate it before an install in the simple quick way using Rdindex,
then this solves my problem as long a "R CMD build" gets the same
result. If it doesn't get the same result (because of a different sort
order) then I get a lot of warning messages which I will start ignoring,
and then miss important warnings. On the other hand, if I use --force,
it changes the INDEX file so that I loose the independence between code
and documentation and end up re-installing almost ever time I run make,
and more importantly, my checks and tests also then appear to be out of
date. If I don't use INDEX as a dependency in my makefile then it
doesn't get re-made when it should be. So it would be nice to be able to
generate the INDEX file in the same format "R CMD build" gets, but
running something simple. As I explained in the previous message, this
depends on the sort order and my Solaris sh does not sort in the same
order as it expands * unless LC_ALL=C, which is the solution I am using.

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

This would also work (and would be better since one could choose the
sort order) but I can't see how to feed this sorted list of files into
"R CMD Rdindex." Probably I am missing something here.

>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 was using this approach until recently and it works fine with small
packages. The time penalty is not too severe now, although it is not
insignificant for some of my packages. When I am actively working on
code development it can be a bottleneck, since I re-make often. In the
longer run I expect "R CMD build" will do more checks and take longer,
so I am mainly trying to set up a good structure for package development
which takes this into account.

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

That would be nice but don't bother if it is a big deal, since I have a
working solution and I doubt that this is an issue for many people.

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

Ensure consistency, but I wouldn't force LC_ALL=C as AaBb... would
probably be a better order for the index and "C" gives AB...ab...

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

Maybe it would be better to work on this rather than put effort into a
temporary fix.

Paul

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