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

[Liaw, Andy]

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