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