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

[Martin Maechler]

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

    >> * 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 . . .
    >> 
    >> Thanks,
    >> 
    >> Dave Kane
    >> 
    >> > R.version
    >> _                   
    >> platform sparc-sun-solaris2.6
    >> arch     sparc               
    >> os       solaris2.6          
    >> system   sparc, solaris2.6   
    >> status                       
    >> major    1                   
    >> minor    6.1                 
    >> year     2002                
    >> month    11                  
    >> day      01                  
    >> language R                   
    >> > 
    >> 
    >> -- 
    >> David Kane
    >> Geode Capital Management
    >> 617-563-0122
    >> david.d.kane at fmr.com
    >> Please avoid sending me Word or PowerPoint attachments.
    >> See http://www.fsf.org/philosophy/no-word-attachments.html