[Rd] Suggesting changes to HELP files?

[Duncan Murdoch]

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