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

From: Duncan Murdoch <>
Date: Wed 08 Jun 2005 - 03:39:38 GMT

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:

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 Received on Wed Jun 08 13:44:45 2005

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