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

[Martin Maechler]

>>>>> "Duncan" == Duncan Murdoch <murdoch at stats.uwo.ca>
>>>>>     on Tue, 07 Jun 2005 12:12:57 -0400 writes:

	  .............

    >>> 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.
    ... On 6/7/2005 11:59 AM, Robert Gentleman wrote:

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

    Duncan> And I disagree pretty strenuously about that.  One
    Duncan> of the strengths of R is that it does impose
    Duncan> standards on contributed packages, and these make
    Duncan> them easier to use, less likely to conflict with
    Duncan> each other, and so on.

    Duncan> We shouldn't impose things lightly, but if they do
    Duncan> make packages better, we should feel no reason not
    Duncan> to tell you what you should be doing.

As Kurt mentioned early in this thread, we currently have
the auto-generated information from
either

    help(package = <pkgname>)    # or (equivalently!)
    library(help = <pkgname>)

which shows  
      DESCRIPTION + 
      (user-written/auto-generated) INDEX +
      mentions vignettes and other contents in inst/doc/

Now if Duncan would write some R code that produces a   man/<pkgname>.Rd
file from the above information -- and as he mentioned also
added some of that functionality to package.skeleton(), 
I think everyone could become "happy", i.e.,
we could improve the system in the future with only a very light
burden on the maintainers of currently existing packages: You'd
have to run the new R function only once for every package you
maintain.

Also, the use of a user-written INDEX file could eventually
completely be abandoned in favor of maintaining
man/<pkgname>.Rd, which is much nicer;  
I'd welcome such a direction quite a bit.

And as much as I do like (and read) the vignettes that are
available, I also do agree that writing one other *.Rd file is
easier for many new package authors than to write a
vignette -- the package author already had to learn *.Rd syntax
anyway -- and it's nice to be able to produce something where
hyperlinks to the other existing reference material (ie. help
pages) just works out of the box.

OTOH, we should still keep in mind that it's worth to try to
get  bi-directional linking between (PDF) vignettes and help
files  (assuming all relevant files are installed by R CMD
INSTALL of course).

Martin

    Duncan> Currently R has 3 types of help: the .Rd files in
    Duncan> the man directory (which are converted into plain
    Duncan> text, HTML, compiled HTML, LaTex, DVI, PDF, etc),
    Duncan> the vignettes, and unstructured files in inst/doc.
    Duncan> We currently require .Rd files for every function
    Duncan> and data object.  Adding a requirement to also
    Duncan> document the package that way is not all that much
    Duncan> of a burden, and will automatically give all those
    Duncan> output formats I listed above.  It will help to
    Duncan> solve the often-complained about problem of packages
    Duncan> that contain no overview at all.  (Requiring a
    Duncan> vignette and giving a way to display it would also
    Duncan> do that, but I think requiring a .Rd file is less of
    Duncan> a burden, and for anyone who has gone to the trouble
    Duncan> of creating a vignette, gives a natural place for a
    Duncan> link to it.  Vignettes aren't used as much as they
    Duncan> should be, because they are hidden away where users
    Duncan> don't see them.)

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

and as mentioned above, an improved package.skeleton() function
could auto-generate both of them anyway.

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