From hb at maths.lth.se  Tue Jun  7 13:29:32 2005
From: hb at maths.lth.se (Henrik Bengtsson)
Date: Tue Jun  7 13:29:37 2005
Subject: [Rd] Suggestion: help(<package name>)
In-Reply-To: <17061.32946.976628.961120@beren.wu-wien.ac.at>
References: <42A57F5D.7080505@maths.lth.se>
	<17061.32946.976628.961120@beren.wu-wien.ac.at>
Message-ID: <42A5851C.3080102@maths.lth.se>

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


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