[R] Warnings with no INDEX file in a package.

[ripley@stats.ox.ac.uk]

Another comment: this is going to change a lot soon!

The handling of indices in R-devel (1.7.0-to-be, probably) is very
different (thanks to Kurt Hornik), and INDEX files will no longer be
required.  The relevant NEWS entry is

    o	Index generation now happens when installing source packages
	using R code in package tools.	An existing 'INDEX' file is used
	as is; otherwise, it is automatically generated from the \name
	and \title entries in the Rd files.  Data, demo and vignette
	indices are computed from all available files of the respective
	kind, and the corresponding index information (in the Rd files,
	the 'demo/00Index' file, and the \VignetteIndexEntry{} entries,
	respectively).	These index files, as well as the package Rd
	contents data base, are serialized as R objects, allowing for
	faster and more reliable index-based computations (e.g., in
	help.search()).

The new code does drop \keyword{internal} help topics from the indices.

I suspect CRAN already runs its checks under the new regime.


On Fri, 10 Jan 2003, Martin Maechler wrote:

> >>>>> "HenrikB" == Henrik Bengtsson <hb at maths.lth.se>
> >>>>>     on Fri, 10 Jan 2003 11:27:09 +1100 writes:
>
>     >> -----Original Message-----
>     >> From: r-help-admin at stat.math.ethz.ch
>     >> [mailto:r-help-admin at stat.math.ethz.ch] On Behalf Of David
>     >> Kane <David Kane
>     >> Sent: den 10 januari 2003 08:01
>     >> To: r-help at stat.math.ethz.ch
>     >> Subject: [R] Warnings with no INDEX file in a package.
>     >>
>     >>
>     >> In previous versions of R (at least in 1.5.1, I think), my
>     >> practice was not to include an INDEX file in the package. R
>     >> CMD check did not complain and an INDEX was created for me
>     >> when I use R CMD build.
>     >>
>     >> At least, this is how I remember it. I thought that this was
>     >> a good way to behave since it ensured that my INDEX was
>     >> automatically kept up to date by R, without me having to
>     >> worry about what functions I had added to the package. I can
>     >> understand why other people might want to maintain an INDEX
>     >> themselves (mainly because it allows one to avoid listing
>     >> functions that aren't that interesting and/or are meant for
>     >> internal use by the package only).
>
>     HenrikB> Just a comment: To make a function "private/hidden"
>     HenrikB> in the table of contents pages, but still existing,
>     HenrikB> add "\keyword{internal}" to the Rd file. From
>     HenrikB> Writing R Extensions:
>
>     HenrikB> "The special keyword internal marks a page of
>     HenrikB> internal objects that are not part of the packages'
>     HenrikB> API. If the help page for object foo has keyword
>     HenrikB> internal, then help(foo) gives this help page, but
>     HenrikB> foo is excluded from several object indices, like
>     HenrikB> the alphabetical list of objects in the HTML help
>     HenrikB> system."
>
>     HenrikB> Using this is much better than doing something like
>     HenrikB> \title{Internal function}.
>
> Indeed.  Thanks a lot, Henrik!
>
>     HenrikB> Note that "\keyword{internal}" functions will still show up
>     HenrikB> in the INDEX file,
> if this is still true, I think it's conceptually a bug.  Kurt?
>
>     HenrikB> but most people tend to look at the HTML ToC
> 		 ^^^^^^^^^^^
> well, not the ESS users AFAIK, most of the time, and also many
> Windows users would rather just use ?funcname with the popup
> window...  but it might be interesting to collect statistics
> here (but *please* not via sending e-mail to R-help now!!).
>
>     HenrikB> (00Index.html) by running help.start() and there it
>     HenrikB> will be excluded.
>
>     >> In 1.6.1, however, runing R CMD check on a package with no
>     >> INDEX gives me:
>     >>
>     >> * checking index files ... WARNING
>     >> The following index files are missing or have zero length:
>     >> INDEX
>     >> See the information on INDEX files and package subdirectories
>     >> in section 'Creating R packages' of the 'Writing R Extensions' manual.
>
> (as indicated by Jeff Gentry, you must use "R CMD build" once at least
>  and later "R CMD build --force" if you want to update INDEX everytime).
>
> One could argue that R CMD check should just build it if there's
> none instead of complaining... but (I think) the concept is
> rather that  ``check'' should not change anything in your
> package source...

My concept is that you should R CMD build, then check the distribution tar
file.

>     >> * checking R files for syntax errors ... OK
>     >>
>     >> I have read the suggested sections of the manual. It would
>     >> seem to me that I should be able to continue to follow my
>     >> prior practice by turning off the warning for missing INDEX.
>     >> Certainly, the fact that R CMD build creates an INDEX for you
>     >> if one is not present would suggest that this is an
>     >> acceptable practice.
>     >>
>     >> Or am I missing something? I just hate to ignore a warning
>     >> each time I build a package . . .

-- 
Brian D. Ripley,                  ripley at stats.ox.ac.uk
Professor of Applied Statistics,  http://www.stats.ox.ac.uk/~ripley/
University of Oxford,             Tel:  +44 1865 272861 (self)
1 South Parks Road,                     +44 1865 272866 (PA)
Oxford OX1 3TG, UK                Fax:  +44 1865 272595