On 6/10/2005 8:00 AM, Gabor Grothendieck wrote: > On 6/10/05, Duncan Murdoch <[EMAIL PROTECTED]> wrote: >> Kurt Hornik wrote: >> >>>>>>Duncan Murdoch writes: >> > >> > >> >>>>>On Tue, 7 Jun 2005, Duncan Murdoch wrote: >> >>>>> >> >>>>>[...] >> >>>>> >> >>>>> >> >>>>> >> >>>>>>My proposal (modified following the suggestions I've heard so far) is >> >>>>>>as >> >>>>>>follows: >> >>>>>> >> >>>>>> - to check that a couple of help topic aliases exist (<pkg>.package >> >>>>>>and <pkg>) >> >>>>>> - to recommend that <pkg>.package contain general information about >> >>>>>>the package, and that <pkg> be an alias for it, if it isn't used for >> >>>>>>some other purpose. >> >>>>>> - to write promptPackage() to help create an initial version of >> >>>>>><pkg>.package.Rd. It can get some information from the DESCRIPTION >> >>>>>>file; perhaps it could go looking for a vignette, or the INDEX, or >> >>>>>> - to modify the other help system tools to make use of this (e.g. the >> >>>>>>package:<pkg> heading on a page would become a link to the >> >>>>>><pkg>.package >> >>>>>>alias, etc.) >> > >> > >> >>I've now committed some of this to R-devel, and I invite comments. I've >> >>abandoned the idea of the check, which seems too controversial. I've >> >>done the second and third items, but not the 4th. >> > >> > >> >>I wrote about a dozen of these files this afternoon as I was refining >> >>promptPackage. It is very quick to generate a basic man page using >> >>promptPackage with an option saying you want a final version. Manually >> >>editing this file, running it through checks, etc. took me around 10-20 >> >>minutes per package. >> > >> > >> >>I only did the base packages, and they probably have less in their >> >>overview than most contributors would want, so someone starting from >> >>nothing would probably take longer --- but many packages already have >> >>the text written somewhere, and they just need to add an alias to an Rd >> >>file, or perhaps reformat an INDEX file. >> > >> > >> > Duncan, >> > >> > I am not sure why you went ahead on this. >> >> It seemed to me that most of the discussion focussed on one point >> (forcing extra work on people); this seems to be the only way to get >> discussion on any other aspect of the proposal. >> >> > My understanding was that >> > there was considerable opposition to introducing a convention for >> > package documentation intermediate between providing package meta data >> > in the DESCRIPTION file and providing vignettes, given in particular >> > that we already have such an additional mechanism (INDEX files) for >> > historic reasons. >> >> The reason I went ahead was that I think this implementation is an >> improvement on INDEX files, though it is backwards compatible. In >> several of the overviews I wrote I refer to the automatically generated >> INDEX file. In cases where the INDEX was manually edited I recommend >> putting the content into the overview topic instead (but do not force >> this). I did it for the boot package (and I'll send the work to Brian if >> he's interested in incorporating it, since boot isn't a base package, >> and he's the maintainer); it wasn't that hard, but I think it was an >> improvement, in that the function names can be links to the function man >> pages, not just names to be copied and pasted. >> >> In at least one case (the stats4 package) I think the INDEX file is >> almost completely useless, so I wrote the overview completely from >> scratch. I'm not sure I got it right, comments or corrections to the >> content would of course be welcome too. >> >> However, I'd really like to hear a clear explanation of why you think >> the current system is superior. So far all that I've heard are messages >> like "this forces too much work on package writers", "we did this three >> years ago, why do it again?" I've explained why I think this solution >> is better, and I've modified it to allow it to be anywhere from "zero >> cost" (ignore it) to "very low cost" (use the automatically generated >> overview), on up as far as a package writer wants to take it. >> >> > I also object particularly to the naming convention. Rd documentation >> > objects are identified by their NAME (as indicated in their \name meta >> > data), not the name of the file used for their serialization into Rd >> > format. IF we want to have such a mechanism, then at least let it work >> > on a topic-style alias of the form PACKAGE-package, which would be >> > consistent with what we do for S4 classes and methods. >> >> The problem with that style is that it doesn't parse to a name, so it >> needs quotes to work with the help system. For example, >> >> ?boot-PACKAGE > > It would be invoked like this: > > package?boot > > with the effect of giving help on boot-package.
Okay, I get it. That's a good change. I'll put it in unless I hear objections very soon. (I'm going to be away from tomorrow through Thursday, so I might appear to be ignoring objections if I don't see them in time.) > > By the way, note that this already works in R since foo?bar works generally > to give help on bar-foo thus the main issue is just whether packages actually > make use of it, whether R CMD CHECK regards it as mandatory or not and > support tools such as promptPackage and links. > > The best situation would be that if one did: > > ?mypkg > > that it would find all occurrences of > > whatever?mypkg > > for each whatever and let the user pick the one desired. Or even find multiple occurences of the same alias with the same whatever; I agree, but that's a bigger change to the help system than I feel like making now. > By the way, its sometimes hard to know all the places to look for information > on a package. It would be nice if library(help = mypkg) gave as > comprehensive > a list as possible of the sources of information: > > - the description file > - list the vignette(s) > - list the demo(s) > - have a set of files that it looks for: README, NEWS, ChangeLog, > WISHLIST, THANKS, CITATION and gives pointers to any that exist > - package?mypkg (or whatever is decided on here) > - the CRAN task views it belongs to > - the bundle it belongs to > - whether it fully passed, passed with warnings or failed R CMD CHECK > > Also it would be nice if one could get this information from the net all in > one place without installing the package since one often wants to investigate > first. Some, but not all, of this information is available at, e.g. > > http://cran.r-project.org/src/contrib/Descriptions/boot.html I think that's a good suggestion, but I'll leave its implementation to someone else. Duncan Murdoch ______________________________________________ [EMAIL PROTECTED] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
