Re: [R] Documentation General Comments

From: Martin Maechler <>
Date: Thu, 24 Apr 2008 18:08:33 +0200


>>>>> "KeBe" == Beck, Kenneth (STP) <> >>>>> on Thu, 24 Apr 2008 10:12:19 -0500 writes:

    KeBe> OK I've spent a lot of time with the core
    KeBe> documentation, and I never found anything as simple as
    KeBe> their table 2.1, which elucidated the difference
    KeBe> between a vector, matrix and array first, then the
    KeBe> higher level structures, frame and list.  Maybe I'm
    KeBe> not a good searcher, but believe me for every initial
    KeBe> posting I submit to this group, I have spent hours
    KeBe> trying to find the answer elsewhere. And, as you
    KeBe> state, maybe I am now deluded by that presentation,
    KeBe> maybe it is not this simple!

Well, I get the impression that you've never read the manual
      "Introduction to R" 
      (or some good book such as Peter Dalgaard's)
but have directly jumped into reading help() pages ???

Maybe a good idea would be to improve the "Introduction to R" rather than thinking of misusing the help() collection {which is the "reference manual", not the "user manual" !!} by making it easy to understand (and consequently less precise) ??

Patches (well reflected ..) to the "Introduction" are quite welcome, indeed.
The (development) source is always available at

(and yes, the source does look a bit less user-friendly,  than its PDF output, e.g.  or its >> daily updated << HTML output at )


    KeBe> Look at the help for data.frame. VERY terse
    KeBe> explanation, with not a good comparison to the other
    KeBe> data types. Then, look at the titles list. Where is a
    KeBe> topic for "data types" Every other programming
    KeBe> language I have used (C++, Pascal, SAS, Java) has a
    KeBe> basic chapter in the documentation that goes over data
    KeBe> types, what arrays are, higher level structures, etc.
    KeBe> When I typed"data type") I get the
    KeBe> following:

    KeBe> Help files with alias or concept or title matching
    KeBe> 'data type' using fuzzy matching:
    KeBe> character-class(methods) Classes Corresponding to
    KeBe> Basic Data Types sqlTypeInfo(RODBC) Request     KeBe> Information about DataTypes in an ODBC Database

    KeBe> Looking for the term "character-class(methods)" yields     KeBe> nothing. I don't think that is what I want!

    KeBe> Given all this complaining, I actually have completed
    KeBe> several nice project using "R", it is an impressive
    KeBe> package. Somehow, though, we need to make the
    KeBe> documentation better.

    KeBe> -----Original Message----- From: Duncan Murdoch
    KeBe> [] Sent: Thursday, April
    KeBe> 24, 2008 9:51 AM To: Beck, Kenneth (STP) Cc: Bert
    KeBe> Gunter; Subject: Re: [R]     KeBe> Documentation General Comments

    KeBe> On 4/24/2008 10:22 AM, Beck, Kenneth (STP) wrote:
>> Agree that terseness is good, but I also agree with other
>> posters that

>> better cross referencing or maybe an index of synonyms
>> would be good.
>> So far, the best suggestion is the pdf at this link
>> (
>> Is there a way to pop at least part of this into the
>> R-base help page?

    KeBe> That's an easy question to answer: no.  There is no
    KeBe> way to just pop it in.  Incorporating it would take a
    KeBe> lot of thought and work.

>> Are there legal or copyright issues?

    KeBe> That's also easy: yes, there are.  The authors of that
    KeBe> chapter presumably have copyright in it (unless
    KeBe> they've transferred it to someone else).  Without
    KeBe> their permission it would be illegal to pop it into R.

    KeBe> If I had known this from the start,
>> it would have been much better. A good analogy is that
>> old cartoon of the blind guys trying to figure out what
>> an elephant is. The guys feeling at the front get a much
>> different impression than the guys poking at the back
>> side. I felt like that using R data structures, had to
>> blindly poke around trying different things, 90% of which
>> did not work, yeilding only error messages, but now
>> knowing the underlying

>> organisation it is going much more smoothly. Ideally this
>> kind of basic info would be in the core R docuemtation,
>> you should not have to

>> search this hard to get it!

    KeBe> All of the (correct) information in that chapter is in
    KeBe> the core documentation.  They make a number of
    KeBe> simplifications, which I think are appropriate for
    KeBe> their audience, but you shouldn't believe everything
    KeBe> you read there.  The core documentation has to aim for
    KeBe> a different target, because it needs to be correct.

    KeBe> Duncan Murdoch

>> -----Original Message----- From:
>> [] On Behalf Of Bert
>> Gunter Sent: Tuesday, April 22, 2008 10:29 AM To:
>> Subject: Re: [R] Documentation
>> General Comments
>> FWIW:
>> I consider the documentation of Core R to be one of its
>> great
    KeBe> strengths:
>> it is terse (read: to the point), detailed, and
>> accurate. I find it eminently useful and helpful. Indeed,
>> it was why I made the decision some years ago to switch
>> from S-Plus to R (I readily acknowledge that S-Plus may
>> have improved its docs since then -- haven't looked at it
>> in years). While I understand that it may not suit
>> everyone -- learning styles differ, after all -- may I at
>> least say that there is one user out here who is
>> appreciative of the hard work and care that has gone into
>> the documentation. Far FAR better than anything I could
    KeBe> do!
>> -- Bert Gunter Genentech
>> -----Original Message----- From:
>> [] On Behalf Of Greg
>> Snow Sent: Tuesday, April 22, 2008 8:16 AM To: Beck,
>> Kenneth (STP); Subject: Re: [R]
>> Documentation General Comments
>> This is a case of you can't please everyone. A while
>> back there was some complaint that "Introduction to R"
>> spent to much time on talking about the different types
>> of variables, just the opposite complaint of

>> yours.
>> There are several other sources of documentation (look
>> under the books

>> link on the R homepage or the contributed documentation
>> link on any CRAN site, also browse through the
>> newsletter). For more in depth information on variable
>> types and object oriented programming in R you

>> may want to invest in a copy of "S Programming" by
>> Venables and
    KeBe> Ripley.
>> If you have specific questions (about data types, or
>> other) then tell us what you have read and what you still
>> do not understand and you are

>> more likely to get a useful answer. (also read the
>> posting guide that

>> is referenced at the bottom of almost all posts to the
>> list).
>> --
>> Gregory (Greg) L. Snow Ph.D. Statistical Data Center
>> Intermountain Healthcare (801)
>> 408-8111

    >>> -----Original Message----- From:
    >>> [] On Behalf Of Beck,
    >>> Kenneth (STP) Sent: Monday, April 21, 2008 3:56 PM To:
    >>> Subject: [R] Documentation General
    >>> Comments
    >>> I realize the R developers are probably overwhelmed and
    >>> have little time for this, but the documentation really
    >>> needs some serious reorganizaton.  A good through
    >>> description of basic variable types would help a lot,
    >>> e.g. the difference between lists, arrays, matrices and
    >>> frames. And, it appears there is some object-orientation
    >>> to R, but it is not complete. I can't, for instance find
    >>> a "metafile" method for a "recordedplot" type, using
    >>> either the variable direclty or the replayPlot()
    >>> method. I am sorry to post this, but I am really having
    >>> trouble sorting out certain methods in "R". The basic
    >>> tutorial "Introduction to R" is so basic, it hardly
    >>> helps at all, then digging

    >>> through documentation is really an exercise in
    >>> frustration. The SimpleR is also so basic it is of
    >>> little help other than to just get started. I
    >>> occasionally find answers in the mailing list. See my
    >>> later


    >>> post on recordPlot for a good example.     >>> mailing list PLEASE do read the posting guide and provide commented, minimal, self-contained, reproducible code. Received on Thu 24 Apr 2008 - 16:18:04 GMT

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.2.0, at Fri 25 Apr 2008 - 18:30:33 GMT.

Mailing list information is available at Please read the posting guide before posting to the list.

list of date sections of archive