RE: [Rd] Suggestion: help(<package name>)

From: Liaw, Andy <>
Date: Wed 08 Jun 2005 - 03:56:58 GMT

Let me add to the pot:

I think Robert and Brian are against imposing additional _requirement_ on packages to provide an overview in .Rd, and I tend to agree with that sentiment.

However, if such a facility is made optional (like vignettes) for package author/maintainer, then I have no problem with it. Perhaps it can work like the CITATION file: The package author/maintainer can choose to (or not to) use it. If one is not provided in the package source, then something halfway sensible is auto-generated from various files (or perhaps just runs help(package="<pkg>").

Or perhaps yet another function can be added to the `utils' package, like packageOverview(), which can either:

- open an overview vignette if one is provided
- open the overview .Rd in whatever format the default help is in
- run help(package="<pkg>") if neither is available

Just my $0.02...


> From: Duncan Murdoch
> Prof Brian Ripley wrote:
> > I share Robert's `pretty strenuous' objections.
> >
> > Adding compulsory things for package writers seems to me to
> need very
> > compelling arguments. Checking that a package does what it
> says (e.g. the
> > code in vignettes can be run) is one thing, but checking it
> does things it
> > does not say it wants to do is quite another.
> I don't understand your complaint. Could you explain what you
> meant by
> "checking it does things it does not say it wants to do"?
> 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.)
> None of these things are very much work, and I'd be happy to
> do them and
> document them. The thing that will be more work is to write the
> <pkg>.package.Rd files for every package. (I'd do it for the base
> packages; they'd be short.) It won't be a huge amount of
> work for any
> one package (many of them already have the basic content in various
> places, so for those it's mostly a matter of reformatting),
> but in total
> it will be a lot.
> I think the benefit of this will be that the help for a package will
> show up in a standard location, using the standard method for looking
> for it. This is not a huge benefit for any users who already
> know all
> about the current ways help can be given, but I think it
> would be a real
> benefit for users who aren't so familiar with things. It
> would help to
> unify the help system: everyone knows about ?topic, so providing a
> standard way for that to lead into all the rest of the documentation
> seems obviously beneficial to me.
> Making this optional would weaken it quite a bit. Packages couldn't
> give links to the main page in other packages if they weren't
> guaranteed
> to exist; producing the HTML would be more difficult if
> links worked
> sometimes and didn't work other times, etc.
> Robert Gentleman wrote:
> > Let's see, some of us (three years ago) developed a tool
> to solve this
> > problem.
> Do you mean vignettes? I think they solved a different
> problem. They
> provided a way to give good general documentation for a package, but
> they didn't provide a way to get to it through the help system. They
> aren't used for general introductory help for any of the standard
> packages except grid and Matrix, and they use different naming
> conventions in those two.
> > We made it available to others to use as they saw fit. I feel
> > no less strong than you do, but I certainly did not impose what I
> > thought on you and I ask for the same respect.
> R imposes lots of things on me. I have to document every
> function, and
> I have to get the usage section right. These take work, but
> they make
> packages more useful. I think imposing one more help topic on the
> package is in the same character. I'm really surprised that
> you find it
> so objectionable. It's really not much work!
> > We have already solved
> > this problem in our own way. You now seem to think that it
> is zero cost
> > to impose on us a second (and in my view inferior solution).
> I have no idea where you got the impression that I think this is zero
> cost. I think it's low cost per package, but obviously not zero.
> > I am asking
> > that you not do that. Please, feel free to develop what you
> want and to
> > encourage others to use it, but don't try to make people do
> things just
> > because you want them that way.
> > We have lots of packages in BioC the costs of
> reengineering so we can
> > meet your newly imposed standards are not zero.
> I'd put the cost of the proposal to the package writer at
> about the cost
> of documenting one function. I wouldn't call it
> "reengineering". It's
> an addition, not a major change.
> > I think we have an
> > expectation that such capricious behaviour will not be
> entered in to,
> > and if we don't then perhaps it is time to branch the project.
> To tell you the truth, I wouldn't consider branching over this issue.
> I'd prefer some rational discussion about the proposal. I
> really don't
> understand why you think it's such a disastrous one that you couldn't
> possibly live with it and would want to do all your work on a
> different
> branch.
> Here are the kinds of question I'd like to discuss:
> 1. Could you tell me what you think would be involved in
> "reengineering"? Maybe you have misunderstood the proposal, or I've
> missed something. How much time do you think this would take?
> 2. What is the current algorithm people should use to look
> for help on
> foo? Couldn't we make it simpler? I'd like it if the algorithm was
> "type ?foo, and read what you get", regardless of what foo is. The
> proposal above doesn't achieve that, but it gets closer.
> Duncan Murdoch
> ______________________________________________
> mailing list
> mailing list Received on Wed Jun 08 14:07:13 2005

This archive was generated by hypermail 2.1.8 : Mon 20 Feb 2006 - 03:21:08 GMT