[Rd] Suggesting changes to HELP files?

[Spencer Graves]

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