[Rd] Suggestion: help(<package name>)
Gabor Grothendieck
ggrothendieck at gmail.com
Tue Jun 7 19:39:22 CEST 2005
Currently methods?e will look for the alias e-methods so perhaps package?e
could look for alias e-package.
On 6/7/05, Achim Zeileis <Achim.Zeileis at wu-wien.ac.at> wrote:
> 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
> >
>
> ______________________________________________
> 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