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