On 6/7/05, Robert Gentleman <[EMAIL PROTECTED]> wrote: > > > Robin Hankin wrote: > > My 0.02: > > > > I use Misc.Rd for the purpose that Duncan suggests. I put things like > > details and rationale for package > > organization, pointers to the most important function(s) in the > > package, and perhaps function descriptors > > for ubiquitous functions that don't warrant their own helppage, but need > > documentation [in > > the case of gsl, this would be strictify() and process.args(), which > > every user needs to know]. > > > > It would be *great* to be required to put in "package.gsl.R" (or should > > that be "gsl.package.Rd"?) > > for this purpose. Then maybe R CMD check could check for its presence > > and throw a wobbly > > if it isn't there. > > > > Hi, > Well, I pretty strenuously object. That is just what vignettes are for > and the last thing I need is more wobbly's from R CMD check. > > Function documentation should document functions. If you want to
'?' or 'help' documents topics, as I under it, not necessarily functions. For example, ?iris ?Startup Further, '?' has a type?topic syntax, as well. Also, what is a wobbly? > document something more substantial then please use the tools already > provided to do that - and if you don't want to, and you want to make use > of the tools for function documentation in some other way please don't > try to impose your version of what should happen on others. > > 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. > >> > >> 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.) > >> > >> Duncan Murdoch > >> > >> ______________________________________________ > >> R-devel@stat.math.ethz.ch mailing list > >> https://stat.ethz.ch/mailman/listinfo/r-devel > >> > >> > > -- > > Robin Hankin > > Uncertainty Analyst > > National Oceanography Centre, Southampton > > European Way, Southampton SO14 3ZH, UK > > tel 023-8059-7743 > > > > ______________________________________________ > > 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