On 6/8/2005 10:36 AM, [EMAIL PROTECTED] wrote:
On Wed, 8 Jun 2005, Duncan Murdoch wrote:
Torsten Hothorn wrote:
> On Tue, 7 Jun 2005, Duncan Murdoch wrote:
>
> [...]
>
>
>>My proposal (modified following the suggestions I've heard so far) is as
>>follows:
>>
>> - to check that a couple of help topic aliases exist (<pkg>.package
>>and <pkg>)
>> - to recommend that <pkg>.package contain general information about
>>the package, and that <pkg> be an alias for it, if it isn't used for
>>some other purpose.
>> - to write promptPackage() to help create an initial version of
>><pkg>.package.Rd. It can get some information from the DESCRIPTION
>>file; perhaps it could go looking for a vignette, or the INDEX, or
>> - to modify the other help system tools to make use of this (e.g. the
>>package:<pkg> heading on a page would become a link to the <pkg>.package
>>alias, etc.)
>>
>
>
> as a package author who already provides help pages for general package
> descriptions (`?multcomp' and `?coin' work and, if I remember correctly,
> Martin suggested to include the advertisement this way) I must
> admit that I never say `?foo' when I'm interested in a global overview
> about a new package `foo'.
I do occasionally, but usually it's a waste of time. This proposal is
intended to address that.
> Instead, `library(help = foo)' gives what I want to see, namely the title
> and description of a package and all documented topics. One may argue that
> asking `library' for help is not the most obvious thing to do. But people
> able to recall that fitting an ANOVA model requires `aov' and comparing
> two models needs `anova' should be able to have `library' in mind for
> general package information.
As I pointed out, this is okay for people who know R already, but not so
good for beginners. The answer to the question "how do I get help on
foo?" is too complex.
> So, for me having infrastructure for _automatically_ generated overviews
> is very nice, but _forcing_ package authors to provide additional
> meta-information would be less welcome.
What do you think of Henrik's suggestion to generate a help topic giving
information equivalent to library(help=<pkg>)? I think this would
happen at install time (not build time as he said; no need to put this
in the source tarballs). If the <pkg>.package alias wasn't defined, the
installer would automatically create one.
If we had this in place, I'd strengthen the advice in R-Exts not to
bother with a manually created INDEX file: that information should go
into a manually created <pkg>.package topic instead.
yes, this sounds reasonable - as long as ?<pkg>.package is a "link" to
library(help = <pkg>)
(or help(package = <pkg> as I learned only recently) when no
<pkg>.package.Rd file exists in <pkg>, this would be fine, of course.
No, that wouldn't work. We have no reliable way for an HTML file to
tell R to do anything, and one way to get to this topic should be
through a URL to the HTML version of the help file. What I was planning
was to generate a <pkg>.package.Rd file at install time, with
information equivalent to the result of library(help = <pkg>).
This will tend to be ugly, because there is no way to know whether the
user has edited the INDEX file; since it already has ascii formatting
built in, it won't look like very good HTML. The part that
library(help = <pkg>) gets from the DESCRIPTION file could have better
formatting because that information is available in structured form.
I haven't looked at the vignette information yet.
It would probably be desirable in the long run to change the behaviour
of library(help = <pkg>) to just call help(), but that loses the return
result, so I wouldn't suggest doing it right away.
Duncan Murdoch
______________________________________________
R-devel@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
