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

[Duncan Murdoch]

Liaw, Andy wrote:
> 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

We don't have a standard name for an overview vignette, and I don't like 
the idea of creating a new help function (packageOverview) that someone 
who doesn't know much about R will have to find before they can use, but 
I like the idea of the help system doing its best to help.

So I'd like this better if it were modified so that ?foo tries the following

  - to open help alias foo
  - if that fails, and foo is a package name:
    - tries to open a vignette with some standard name (proposals?)
    - if that fails, then does help(package="foo")

This has the disadvantage over the original proposal that help pages 
can't link to a standard help topic for the package, so I like the 
original better, but this would be better than the status quo.

Duncan Murdoch

> 
> 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
>>
>>
>>
> 
> 
> 
> 
> ------------------------------------------------------------------------------
> Notice:  This e-mail message, together with any attachment...{{dropped}}