[Rd] 00Index of data

[Kurt Hornik]

>>>>> Prof Brian Ripley writes:

>> Date: Mon, 10 Apr 2000 10:25:41 -0400
>> From: Paul Gilbert <pgilbert@bank-banque-canada.ca>
>> To: Prof Brian Ripley <ripley@stats.ox.ac.uk>
>> CC: r-devel@stat.math.ethz.ch
>> Subject: Re: [Rd] 00Index of data
>> 
>> >the help page for the data.
>> 
>> Now that's something I didn't know about but is probably documented
>> somewhere that I missed. (No wonder I found the index rather
>> restrictive.) I now see it is reported as missing documentation by R CMD
>> build. (It is buried by all the other warnings.) I guess it should just

> When you solve all the others it will emerge more clearly :)

:-)

>> be an Rd file like the function help. 

> Yes, and `Writing R Extensions' tells you about making help files for
> data.  And the base system has them. (So does S-PLUS!)

>> Does a link get automatically
>> built from the 00Index of the data to the help for data or do I need to
>> point readers to the help?

> Readers are supposed to know to look for help on R *objects* (not just
> functions).  Even the help.start intro says `Functions & Datasets'

>> Or will the 00Index of the data get built
>> automatically from the titles in the data help files in the same way
>> that the function index is built? (And if so, how does it know the
>> documentation is for data?)

> It does not get built, and help for data goes in INDEX. (That is one
> reason why some of us prefer hand-crafted INDEX files.)  We are moving
> towards a way to distinguish the object type in a help file, but are
> not there yet.

Correction: R CMD build will try to build/update the documentation index
(`INDEX') as well as the data index (`data/00Index').  The latter, as I
think Paul expected, happens by taking the names of all Rd files that
contain the keyword `datasets' (which again shows how important it is to
eliminate all warnings about Rd files without keywords etc).

The problem is that package developers might register more (or less)
information in their INDEX than obtained via this procedure.  E.g., if
an Rd file documents more than one object, the alias mechanism ensures
that documentation for all objects is found, but it is not smart enough
to ensure that all objects documented get a corresponding index entry.

The solution would be to introduce something like

	\index{NAME}{DESCRIPTION}

lines in the Rd files, and in fact have the index built from these lines
exclusively rather than the names.  But first we must know what `NAME'
exactly should be here, e.g. whether we only want to list *OBJECTS* in
the index or *ALL* topics being documented.

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