[Rd] Suggestion: help(<package name>)
Achim Zeileis
Achim.Zeileis at wu-wien.ac.at
Tue Jun 7 19:00:25 CEST 2005
On Tue, 7 Jun 2005 18:43:37 +0200 Martin Maechler wrote:
> >>>>> "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
I would like to second what Gabor said earlier in this thread: we cannot
simply create man/<pkgname>.Rd because this will already exist for many
packages. Examples that come to my mind include: betareg, chron,
ellipse, flexmix, ineq, zoo, and many more. Renaming the package is not
an option, so probably the man page has to be renamed to something like
man/<pkgname>.package.Rd, say. And then doing
help(package = "foo")
and
help("foo.package")
is not that much of a difference, is it? Personally, I find the former
more intuitive.
Z
> -- 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.)
>
> ______________________________________________
> R-devel at stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
More information about the R-devel
mailing list