[Rd] Suggesting changes to HELP files?
spencer.graves at pdf.com
Sun May 21 19:26:19 CEST 2006
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
> 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
>> 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
> example where the vignette name is not the package name
> Revision: 32054
> Author: leisch
> Date: 9:52:24 AM, Friday, November 26, 2004
> new print and edit methods for vignette objects
> Revision: 27442
> Author: ripley
> Date: 2:24:25 AM, Tuesday, December 09, 2003
> 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
More information about the R-devel