From Achim.Zeileis at wu-wien.ac.at  Tue Jun  7 19:00:25 2005
From: Achim.Zeileis at wu-wien.ac.at (Achim Zeileis)
Date: Tue Jun  7 19:02:09 2005
Subject: [Rd] Suggestion: help(<package name>)
In-Reply-To: <17061.52921.689940.969317@stat.math.ethz.ch>
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>
Message-ID: <20050607190025.55a68766.Achim.Zeileis@wu-wien.ac.at>

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
>


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