On 5/21/2006 11:45 AM, Spencer Graves wrote: > Is there a procedure for suggesting changes to HELP files of the core > R distribution? If yes, what is it? If it would be considered a > friendly gesture, I could find the relevant *.Rd file and submit a > suggested modification to it someplace. Alternatively, I could just > send suggestions someplace if they would receive appropriate > consideration.
I don't think there's a formal procedure. Generally the idea is to find an R Core member (i.e. someone who can commit changes) who thinks your changes are a good idea, and then they'll commit them. How you do that convincing depends on who you're talking to. For your examples below: > On many occasions, I think of modifications, e.g., additional > examples, that could be added to 'help' pages that I believe would make > it easier for people to understand how to use some R feature. Instead, > I often provide the same answer multiple times to different posts. > > I can think of two changes off the top of my head that I'd like to > see: First, many if not all of the helps page in the nlme and lme4 > packages should, I believe, include a reference Pinheiro and Bates. > This is not the place for modesty on the part of Pinheiro, Bates, and > co-workers. I believe that many requests for help might be eliminated > if such references were added. Failing that, it would be easier for > people like me to suggest someone read that book, because I wouldn't > feel such a need to spell out the entire citation every time. nlme and lme4 are both contributed packages, so you want to talk to the maintainers about changes to them. nlme is distributed with binary builds, but isn't strictly speaking part of the "core R distribution". Only packages labelled as "Priority: base" in the DESCRIPTION file are part of the core distribution. > Second, I think the description of 'vignette' could be enhanced to > include some version of my 'p.s.' to > 'http://finzi.psych.upenn.edu/R/Rhelp02a/archive/73494.html' and other > similar posts. In particular, I see that the 'edit' method is described > there, but I didn't understand what it said until I already knew how to > use it. For something like this, it's probably best to draft some text, and post it to R-devel. You could also look at the Subversion history of the appropriate file (src/library/utils/man/vignette.Rd) to see who has been active with changes to it recently; they might be more interested in making changes to it than others. In this case, the log is Revision: 33828 Author: leisch Date: 2:37:14 AM, Tuesday, April 05, 2005 Message: example where the vignette name is not the package name Revision: 32054 Author: leisch Date: 9:52:24 AM, Friday, November 26, 2004 Message: new print and edit methods for vignette objects Revision: 27442 Author: ripley Date: 2:24:25 AM, Tuesday, December 09, 2003 Message: split from base so Fritz Leisch might be interested, but the last change is more than a year ago, so it might not be at the top of his mind. The latter observation is the main reason suggested changes might not make it into the source: you need to get someone's attention, and they'll need to devote some time to dealing with your suggestion. It needs to be clear that the change is an improvement. Things like minor typos are easy, but something like the suggestion above would need to be evaluated by someone familiar with what vignette() does, and what it is intended to do. So you need to make it as easy as possible to evaluate and incorporate your change, and sometimes it still won't get in, because the only people to do it are working on other things. You should also be prepared to hear criticism of your suggestion, and be able to defend it or change it. Don't be offended if someone rewrites your change, or if they ask you to rewrite it. > Also, 'edit' doesn't work for me under ESS / Emacs. For that, > I use Stangle (as Sundar Dorai-Raj taught me). That sounds like an ESS or Emacs bug, and should be reported to the maintainers of one of those. Duncan Murdoch ______________________________________________ R-devel@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
