[Rd] Suggestion: help(<package name>)
Prof Brian Ripley
ripley at stats.ox.ac.uk
Tue Jun 7 19:47:20 CEST 2005
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.
On Tue, 7 Jun 2005, Robert Gentleman wrote:
> Duncan Murdoch wrote:
>> On 6/7/2005 11:59 AM, Robert Gentleman wrote:
>>
>>>
>>> Duncan Murdoch wrote:
>>>
>>>> On 6/7/2005 11:12 AM, Robert Gentleman wrote:
>>>>
>>>>>
>>>>> Robin Hankin wrote:
>>>>>
>>>>>> My 0.02:
>>>>>>
>>>>>> I use Misc.Rd for the purpose that Duncan suggests. I put things like
>>>>>> details and rationale for package
>>>>>> organization, pointers to the most important function(s) in the
>>>>>> package, and perhaps function descriptors
>>>>>> for ubiquitous functions that don't warrant their own helppage, but
>>>>>> need documentation [in
>>>>>> the case of gsl, this would be strictify() and process.args(), which
>>>>>> every user needs to know].
>>>>>>
>>>>>> It would be *great* to be required to put in "package.gsl.R" (or
>>>>>> should that be "gsl.package.Rd"?)
>>>>>> for this purpose. Then maybe R CMD check could check for its presence
>>>>>> and throw a wobbly
>>>>>> if it isn't there.
>>>>>>
>>>>>
>>>>> Hi,
>>>>> Well, I pretty strenuously object. That is just what vignettes are for
>>>>> and the last thing I need is more wobbly's from R CMD check.
>>>>>
>>>>> Function documentation should document functions. If you want to
>>>>> document something more substantial then please use the tools already
>>>>> provided to do that - and if you don't want to, and you want to make use
>>>>> of the tools for function documentation in some other way please don't
>>>>> try to impose your version of what should happen on others.
>>>>
>>>>
>>>>
>>>> The current .Rd files don't just document functions, they also document
>>>> data objects and classes.
>>>>
>>>> But the main point here is that it's not good to have multiple
>>>> disconnected sets of documentation for a package. Users should be able
>>>> to say the equivalent of "give me help on foo", and get help on foo,
>>>> whether it's a function, a data object, a package, a method, a class, or
>>>> whatever. It's a bad design to force them to ask for the same sort of
>>>> thing in different ways depending on the type of thing they're asking
>>>> for.
>>>>
>>>
>>> Hi Duncan and others,
>>> I think they are linked. There are tools available both in R and in
>>> Bioconductor and some pop things up and some don't. It doesn't take much
>>> work to add vignettes to the windows menu bar - as we have done in BioC
>>> for some time now - it would be nice if this was part of R, but no one
>>> seems to have been interested in achieving that. Fixing the help system to
>>> deal with more diverse kinds of help would be nice as well - but taking
>>> one part of it and saying, "now everyone must do it this way" is not that
>>> helpful.
>>>
>>> I respectfully disagree about the main point. My main point is, I don't
>>> want more things imposed on me; dealing with R CMD check is enough of a
>>> burden in its current version, without someone deciding that it would be
>>> nice to have a whole bunch more requirements. Folks should feel entirely
>>> free to do what they want - but a little less free to tell me what I
>>> should be doing.
>>
>>
>> And I disagree pretty strenuously about that. One of the strengths of R is
>> that it does impose standards on contributed packages, and these make them
>> easier to use, less likely to conflict with each other, and so on.
>>
>> We shouldn't impose things lightly, but if they do make packages better, we
>> should feel no reason not to tell you what you should be doing.
>>
> Let's see, some of us (three years ago) developed a tool to solve this
> problem. 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. 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 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 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.
>
> Best wishes,
> Robert
>
>> Currently R has 3 types of help: the .Rd files in the man directory (which
>> are converted into plain text, HTML, compiled HTML, LaTex, DVI, PDF, etc),
>> the vignettes, and unstructured files in inst/doc. We currently require
>> .Rd files for every function and data object. Adding a requirement to also
>> document the package that way is not all that much of a burden, and will
>> automatically give all those output formats I listed above. It will help
>> to solve the often-complained about problem of packages that contain no
>> overview at all. (Requiring a vignette and giving a way to display it
>> would also do that, but I think requiring a .Rd file is less of a burden,
>> and for anyone who has gone to the trouble of creating a vignette, gives a
>> natural place for a link to it. Vignettes aren't used as much as they
>> should be, because they are hidden away where users don't see them.)
>>
>> Duncan Murdoch
>>
>>>
>>> Best wishes,
>>> Robert
>>>
>>>
>>>> If we had a way to link vignettes into the help system, then I'd think it
>>>> would be perfectly acceptable for ?package to pop up a vignette for the
>>>> package. However, right now we have too many different types of ways to
>>>> display help, and not all of them are capable of displaying vignettes.
>>>>
>>>> Duncan Murdoch
>>>>
>>>>
>>>>>
>>>>> Best wishes
>>>>> Robert
>>>>>
>>>>>> Some packages have so much material that it's difficult to know where
>>>>>> the "meat" of the functionality lies,
>>>>>> and Duncan's suggestion would help greatly in these circumstances.
>>>>>>
>>>>>> best wishes
>>>>>>
>>>>>> rksh
>>>>>>
>>>>>>
>>>>>> On Jun 7, 2005, at 01:11 pm, Duncan Murdoch wrote:
>>>>>>
>>>>>>> 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.
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> I think this is a good idea. One minor problem is that for some
>>>>>>> packages that topic name is already in use for a function (e.g. boot).
>>>>>>> For that reason, I'd suggest that there *also* be an alias called
>>>>>>> "package.<package name>", and the <package name> topic should link to
>>>>>>> it.
>>>>>>>
>>>>>>>> How would this be different from the results of
>>>>>>>> help(package = <package name>)
>>>>>>>> ?
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> 1. It would work with ?, like other help topics.
>>>>>>>
>>>>>>> 2. It would give an overview. It's possible to do that in
>>>>>>> DESCRIPTION or INDEX, but you don't get the same style as for other
>>>>>>> help files (e.g. no links to other topics, at least in Windows).
>>>>>>>
>>>>>>>
>>>>>>>
>>>>>>> We should work out what the topic headings should be and extend
>>>>>>> package.skeleton() and prompt() to write a bare-bones file that
>>>>>>> suggests the questions that need to be answered in the file. The
>>>>>>> headings I'd suggest are:
>>>>>>>
>>>>>>> \name
>>>>>>> \title
>>>>>>> \alias
>>>>>>> \description (longer than the typical entry in the DESCRIPTION file)
>>>>>>> \details (Should give a short guide to the main functions, should
>>>>>>> point out the existence of external documentation like vignettes,
>>>>>>> etc.)
>>>>>>> \author (could also describe maintainer, if different)
>>>>>>> \references
>>>>>>> \seealso (Should give references to related packages)
>>>>>>> \examples
>>>>>>> \keywords
>>>>>>>
>>>>>>> There is some duplication of material from DESCRIPTION, but usually
>>>>>>> this should be longer and more reader-friendly than that file.
>>>>>>>
>>>>>>> I'd be happy to write the description of this in R Extensions, and
>>>>>>> write the changes to prompt(), if we have agreement that this file
>>>>>>> should be mandatory in 2.2.x or 2.3.x, and you'll write the checks for
>>>>>>> it. (I think the check should just be for existence of aliases
>>>>>>> <package name> and package.<package name>, and could perhaps just give
>>>>>>> a warning in 2.2.x.)
>>>>>>>
>>>>>>> Duncan Murdoch
>>>>>>>
>>>>>>> ______________________________________________
>>>>>>> R-devel at stat.math.ethz.ch mailing list
>>>>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>>>>>
>>>>>>>
>>>>>> --
>>>>>> Robin Hankin
>>>>>> Uncertainty Analyst
>>>>>> National Oceanography Centre, Southampton
>>>>>> European Way, Southampton SO14 3ZH, UK
>>>>>> tel 023-8059-7743
>>>>>>
>>>>>> ______________________________________________
>>>>>> R-devel at stat.math.ethz.ch mailing list
>>>>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>>>>>
>>>>
>>>
>>> ______________________________________________
>>> R-devel at stat.math.ethz.ch mailing list
>>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>>
>> ______________________________________________
>> R-devel at stat.math.ethz.ch mailing list
>> https://stat.ethz.ch/mailman/listinfo/r-devel
>>
>
> ______________________________________________
> R-devel at stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
>
--
Brian D. Ripley, ripley at stats.ox.ac.uk
Professor of Applied Statistics, http://www.stats.ox.ac.uk/~ripley/
University of Oxford, Tel: +44 1865 272861 (self)
1 South Parks Road, +44 1865 272866 (PA)
Oxford OX1 3TG, UK Fax: +44 1865 272595
More information about the R-devel
mailing list