R devel - Jun 2005 - Suggestion: help(<package name>)

Hi,

I would like to suggest a standard where all packages provide an Rd page 
with the same name (or aliased) as the name of package so that 
help(<package name>) or ?<package name> is always here. This
especially
of interest to large packages with a large package index. This page 
could explain the package in general and gives some hints on how to 
start - not like extensive vignettes, but just to get started, e.g. list 
the "most important" functions.  This page could typically contain 
information that is in the DESCRIPTION file (which contains valuable 
information hardly every accessed by a general user), such as who is the 
maintainer, how to report bugs and so on.

If you think the above is a good idea, then, would it even be useful to 
enforce the existance of such a Rd page in R CMD check?

Henrik Bengtsson

>>>>> Henrik Bengtsson writes:
> Hi,
> I would like to suggest a standard where all packages provide an Rd page 
> with the same name (or aliased) as the name of package so that 
> help(<package name>) or ?<package name> is always here. This
especially
> of interest to large packages with a large package index. This page 
> could explain the package in general and gives some hints on how to 
> start - not like extensive vignettes, but just to get started, e.g. list 
> the "most important" functions.  This page could typically
contain
> information that is in the DESCRIPTION file (which contains valuable 
> information hardly every accessed by a general user), such as who is the 
> maintainer, how to report bugs and so on.
How would this be different from the results of

	help(package = <package name>)

?

-k
> If you think the above is a good idea, then, would it even be useful to 
> enforce the existance of such a Rd page in R CMD check?
> Henrik Bengtsson
> ______________________________________________
> R-devel@stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel

Kurt Hornik wrote:
>>>>>>Henrik Bengtsson writes:
> 
> 
>>Hi,
>>I would like to suggest a standard where all packages provide an Rd page
>>with the same name (or aliased) as the name of package so that 
>>help(<package name>) or ?<package name> is always here. This
especially
>>of interest to large packages with a large package index. This page 
>>could explain the package in general and gives some hints on how to 
>>start - not like extensive vignettes, but just to get started, e.g. list
>>the "most important" functions.  This page could typically
contain
>>information that is in the DESCRIPTION file (which contains valuable 
>>information hardly every accessed by a general user), such as who is the
>>maintainer, how to report bugs and so on.
> 
> 
> How would this be different from the results of
> 
> 	help(package = <package name>)
> 
> ?
Thanks for that. I was not aware of this one; I like how DESCRIPTION is 
included and how the index is divided in functions and dataset, e.g. 
help(package=MASS). May I also suggest that the CITATION file is 
included here, e.g. help(package=foreign).

My suggestion differ in the sense that 1) additional information may be 
included such as which functions are "main" functions and which are of
less interest, and 2) that it would show up in the HTML index page too.

An automated solution such as help(package=<name>) is of course easier 
to maintain. Part of Rd files can be generated this way too, but I did 
not want to get too complicated in my suggestions.

/Henrik
> -k
> 
> 
>>If you think the above is a good idea, then, would it even be useful to 
>>enforce the existance of such a Rd page in R CMD check?
> 
> 
>>Henrik Bengtsson
> 
> 
>>______________________________________________
>>R-devel@stat.math.ethz.ch mailing list
>>https://stat.ethz.ch/mailman/listinfo/r-devel
> 
> 
>

On 6/7/05, Henrik Bengtsson <hb@maths.lth.se>
wrote:
> Hi,
> 
> I would like to suggest a standard where all packages provide an Rd page
> with the same name (or aliased) as the name of package so that
> help(<package name>) or ?<package name> is always here. This
especially
> of interest to large packages with a large package index. This page
> could explain the package in general and gives some hints on how to
> start - not like extensive vignettes, but just to get started, e.g. list
> the "most important" functions.  This page could typically
contain
> information that is in the DESCRIPTION file (which contains valuable
> information hardly every accessed by a general user), such as who is the
> maintainer, how to report bugs and so on.
> 
> If you think the above is a good idea, then, would it even be useful to
> enforce the existance of such a Rd page in R CMD check?
The basic idea of having a short overview seems good but
the particular suggestion of using ?packagename would
seem to collide with already existing .Rd files as
many packages are named after their constructor, e.g. the zoo
package.

On Tue, 7 Jun 2005, Henrik Bengtsson wrote:
> Kurt Hornik wrote:
>> 
>> How would this be different from the results of
>> 
>> 	help(package = <package name>)
>> 
>> ?
>
> Thanks for that. I was not aware of this one; I like how DESCRIPTION is 
> included and how the index is divided in functions and dataset, e.g. 
> help(package=MASS). May I also suggest that the CITATION file is included 
> here, e.g. help(package=foreign).
>
> My suggestion differ in the sense that 1) additional information may be 
> included such as which functions are "main" functions and which
are of less
> interest, and 2) that it would show up in the HTML index page too.
>
For point (1) you can write your own INDEX file, in which case it can have 
more information than the auto-generated one.  A simple example is the 
survey package.  My description of the INDEX file in courses has been that 
it contains a line for every "sufficiently interesting" function.
Writing
R Extensions says that "normally this file is missing" but I think
this is
descriptive rather than prescriptive.

2) seems sensible.  The INDEX file is included in the CRAN page and I find 
it useful there.


 	-thomas

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
> 
> 
>