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. Best, Torsten > > Duncan Murdoch > ______________________________________________ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
