[Rd] Request: Documentation of formulae

[Martin Maechler]

>>>>> "MP" == Mike Prager <mike.prager at noaa.gov>
>>>>>     on Mon, 02 Jun 2008 16:29:16 -0400 writes:

    MP> Mike Prager <mike.prager at noaa.gov> wrote:
    >> I was at a loss to understand the use of "/" until I looked in
    >> "An Introduction [!] to R," where I found the explanation. 
    >> 
    >> My request is that more complete material on model formulae be
    >> lifted from "Introduction to R" (or elsewhere) and put into the
    >> main online help files. 

    MP> I also request the R Core consider remaining "An Introduction to
    MP> R" to something like "R User's Guide." It spans 100 pages and
    MP> treats many topics far beyond the introductory level. I was
    MP> surprised at the wealth of information it contains, and I expect
    MP> that I would have checked it first, not last, among available
    MP> resources had it been more accurately named.

Hi Mike, you make very worthy suggestions; but I assume the word
"request" is really putting off almost all of us "R corers".
You *have* heard that R is a volunteer project, that much of its
development has happened in unpaid time of core team mates.
Why are you not using "Suggestion" instead?

Also, since it's a volunteer project, and you are a capable R
user, you could even consider sending patches, e.g. to the 
formula.Rd  help page.

At last, to the renaming suggestion: I see your point, but

1) in "an Intro" one is allowed to be non-comprehensive
   where as a "user's guide" is supposedly touching almost
   everything relevant.  This is not the case, since R has much
   evolved since the "An Intro .." had been compiled, and most
   new features are not mentioned in the intro.

2) I don't know your background, but in the math sciences, there
   exist quite a few comprehensive textbooks called "An
   Introduction to ...".
   One example from my bookshelf is
   @BOOK{AndT84,
     author = 	{T. W. Anderson},
     title = 	{An Introduction to Multivariate Statistical Analysis},
     publisher = Wiley,
     address =	NY,
     year = 	1984
   }


3) "An Introduction to R" is mentioned in many many pieces of
   documentation about R; from instructions to students, to
   online guides, to books, etc.

   For this reason, a new title should reall still contain the
   term.

   Maybe simply
	"An Introduction to R --- User's guide"
?
   
Best regards,
Martin Maechler, ETH Zurich