Hi, Duncan: Thanks very much. This helps. Best Wishes, Spencer Graves Duncan Murdoch wrote: > 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
