[R] How to contribute improved documentation {was ".. lm.predict .."}

[Martin Maechler]

>>>>> "Larry" == Larry Howe <larry.howe at comjet.com>
>>>>>     on Sat, 20 May 2006 15:10:09 -0400 writes:

    >> > "An optional data frame in which to look for variables with which to
    >> > predict." means almost nothing to me. Specifically it doesn't translate
    >> > to me, as an engineer and software developer, but not a statistician,
    >> > that the names have to match, and furthermore if they don't match, R
    >> > fails silently.
    >> >
    >> > Larry Howe
    >> 
    >> I have had offline conversations not related to this thread by others
    >> who were also confused by this so I agree it would be worthwhile
    >> to clarify it.

    Larry> Thank you! If there is anything I can do to help get
    Larry> this documented / clarified, please let me know.

BTW, this has now become a topic that belongs a bit more to the
R-devel rather than R-help mailing list,  but I keep it here for
reference and in the hope it will be closed for now.

Maybe because of your question (or completely incidentally?)
yesterday, we had the topic
  "Suggesting changes to HELP files?"
on R-devel, see
   https://stat.ethz.ch/pipermail/r-devel/2006-May/037785.html
and it's follow up postings, notably Duncan Murdoch's
   https://stat.ethz.ch/pipermail/r-devel/2006-May/037787.html
I had written part of the following independently, and I would
recommend to use in conjunction with Duncan's.

Yes, you can help to get this documentation improved.
Ideally, and with highest probability of success, if
you provide a "patch" *) to the current documentation *source*,
which for help pages always means a file named *.Rd from the R
source - which is available online, as a whole, see CRAN -> source,
or - in this case more conveniently - the complete file tree is
at https://svn.R-project.org/R/trunk/ and the file in question
is https://svn.r-project.org/R/trunk/src/library/stats/man/predict.lm.Rd

Since providing a patch *) is "hard" for average R users,
for documentation changes we would also be content to just receive
the new version of the text you changed from the corresponding
*.Rd file.

What we do like much less is an edited version of some
*representation* of the help, e.g., any version you get by using
help() or browsing any forms of the manuals.

Martin Maechler, ETH Zurich

----
*) Providing a patch means:
- edit the file to be changed and keep the original;
- run 'diff -u <oldfile>  <newfile> ' in your shell (which must
  'diff' in its path).
- E-mail (with a mail program that does NOT mangle lines and
  does not send HTML ..) the output of the above 'diff ..' to R-devel as a
  proposal for improving R.