The issue recently raised by Duncan and discussed in some detail by him
and Brian was also raised by Robert a few weeks ago (I think in an email
that only I received). Here are some more comments and thoughts.
Unfortunately, much of the way the on-line documentation (help or HTML)
systems currently work is not the result of careful design decisions. I
think we now understand the limitations of what we currently have, but I
am not sure we already know what we will do in the future. (The XHTML
versus XML issue comes to mind.) As Brian pointed out, as we shall move
away from Rd format eventually, we should be careful about adding more
bells and whistles to it.
The entry points for packages documentation are
library(help = PKG)
or
help(package = PKG)
where PKG should really be a character string naming the package. Also,
only the former one seems to be documented explicitly, so this is the
one we should use. I would recommend against using
?PKG
for this purpose, as this has the obvious name space issues, and the
former two are meant for documenting packages only.
The next question is what these entry points should do. Currently, they
simply show the package INDEX file, irrespective of whether help.start()
was given or not. I think this is a bug. On the other hand, the INDEX
only exists as flat file and is not necessarily what would be obtained
by running R CMD Rdindex on the package. Hence, we cannot automatically
create a HTML version from the Rd sources. (In fact, the HTML system
does have entry points for each package, but these simply contain HTML
versions of the flat-file help/AnIndex data base.)
I am also not sure about recommending to add plain text to file `INDEX'
(as e.g. happens for the base package). I am quite hesitant to suggest
any changes to this file, because a redesigned documentation system will
need a real index system but then perhaps we'd not be using `INDEX' per
se anymore.
I think the best thing we can currently do is to follow up on Fritz's
idea of using some or all info from the `DESCRIPTION' data base (Robert
also suggested that) in addition to listing or documenting the topics a
package provides docs for. In the simplest case, we could have
library(help = PKG)
do a file.show() on the result of combining PKG's DESCRIPTION and INDEX
files. That is something we can easily do for 1.2.1, and I would make
the change if no one protests.
For the HTML help system, we have two alternatives: do *exactly* the
same or combine DESCRIPTION with the HTML package index. Not so fast:
we also need to decide whether library(help = PKG) should use the
browser after help.start(). In any case, I think we should have the
build-help script add a simple HTML version of the package DESCRIPTION
to the top of 00Index.html.
For the LaTeX package documentation, the idea was to add a beautified
version of the package DESCRIPTION to the top of the file, e.g. as some
kind of abstract. We need to be careful about this, though, because
there may be plain text interpreted by LaTeX as special markup.
(E.g., relation operators in Depends can easily be caught; on the other
hand, they might also appear in other fields, such as Description ...).
I am not sure how easy it is to convert the contents of DESCRIPTION into
HTML or LaTeX. But for the plain text help system, I think the best we
can currently do is to add the contents of DESCRIPTION to what is shown
following library(help = PKG). In particular, I think the Description
field of the DESCRIPTION data base can be used as a package ``intro''.
-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
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._