From ggrothendieck at gmail.com  Tue Jun  7 19:39:22 2005
From: ggrothendieck at gmail.com (Gabor Grothendieck)
Date: Tue Jun  7 19:39:32 2005
Subject: [Rd] Suggestion: help(<package name>)
In-Reply-To: <20050607190025.55a68766.Achim.Zeileis@wu-wien.ac.at>
References: <42A57F5D.7080505@maths.lth.se>
	<17061.32946.976628.961120@beren.wu-wien.ac.at>
	<42A58EDF.80701@stats.uwo.ca>
	<1f269abbabca01e19ee3cdbabc9d14f6@soc.soton.ac.uk>
	<42A5B96B.9030701@fhcrc.org> <42A5BB9D.3000301@stats.uwo.ca>
	<42A5C465.3090505@fhcrc.org> <42A5C789.3060101@stats.uwo.ca>
	<17061.52921.689940.969317@stat.math.ethz.ch>
	<20050607190025.55a68766.Achim.Zeileis@wu-wien.ac.at>
Message-ID: <971536df05060710393fdd9c28@mail.gmail.com>

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@wu-wien.ac.at> wrote:
> On Tue, 7 Jun 2005 18:43:37 +0200 Martin Maechler wrote:
> 
> > >>>>> "Duncan" == Duncan Murdoch <murdoch@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@stat.math.ethz.ch mailing list
> > https://stat.ethz.ch/mailman/listinfo/r-devel
> >
> 
> ______________________________________________
> R-devel@stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>


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