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