Thanks, the reference to the wiki and ways to submit patches is a help. -----Original Message----- From: Kingsford Jones [mailto:[EMAIL PROTECTED] Sent: Thursday, April 24, 2008 10:56 PM To: Duncan Murdoch Cc: Martin Maechler; r-help@r-project.org; Beck, Kenneth (STP); Bert Gunter Subject: Re: [R] Documentation General Comments
I just read through this thread and I didn't see the R Language Definition mentioned. As with An Introduction to R it can be accessed -- at least in my Windows GUI -- via the menu bar: Help -> Manuals (in PDF). If An Introduction to R is too basic, then the Language Definition should be a good place to look for more details on R objects (Ch 2). However An Introduction to R does include authoritative introductions to the "data types" mentioned by the original poster: factors (Ch4), arrays and matrices (Ch 5), and lists and data frames (Ch 6). That said, I agree that learning efficiency could be improved by augmenting the manuals with tables similar to the table 2.1 that was referenced earlier in the thread (aside: are functions, or even lists, really "Data Objects"?). Of course, as pointed out by Duncan, we are collaborators not consumers, so if I think there should be more tables in the documents then the onus is on me to try to get my ideas incorporated (see http://wiki.r-project.org/rwiki/doku.php?id=misc:rpatch ). Kingsford Jones On Thu, Apr 24, 2008 at 9:37 AM, Duncan Murdoch <[EMAIL PROTECTED]> wrote: > On 4/24/2008 12:08 PM, Martin Maechler wrote: > > Hmm, > > > >>>>>> "KeBe" == Beck, Kenneth (STP) <[EMAIL PROTECTED]> > >>>>>> 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 ??? > > That's not correct. Kenneth started the thread (on Monday) saying: > > > "The basic tutorial "Introduction to R" is so basic, it hardly helps > at all, then digging through documentation is really an exercise in > frustration." > > Duncan Murdoch > > > > > > > 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 > https://svn.r-project.org/R/trunk/doc/manual/R-intro.texi > > > > (and yes, the source does look a bit less user-friendly, > than > its PDF output, e.g. > > http://cran.r-project.org/doc/manuals/R-intro.pdf > > or its >> daily updated << HTML output at > > http://stat.ethz.ch/R-manual/R-devel/doc/manual/R-intro.html > > ) > > > > Regards, > > Martin > > > > 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 help.search("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> [mailto:[EMAIL PROTECTED] Sent: Thursday, April > > KeBe> 24, 2008 9:51 AM To: Beck, Kenneth (STP) Cc: Bert > > KeBe> Gunter; r-help@r-project.org 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 > > >> > > >> (http://www.medepi.net/epir/epir_chap02.pdf). > > >> > > >> 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: > > >> [EMAIL PROTECTED] > > >> [mailto:[EMAIL PROTECTED] On Behalf Of Bert > > >> Gunter Sent: Tuesday, April 22, 2008 10:29 AM To: > > >> r-help@r-project.org 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: > > >> [EMAIL PROTECTED] > > >> [mailto:[EMAIL PROTECTED] On Behalf Of Greg > > >> Snow Sent: Tuesday, April 22, 2008 8:16 AM To: Beck, > > >> Kenneth (STP); r-help@r-project.org 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 [EMAIL PROTECTED] (801) > > >> 408-8111 > > >> > > >> > > >> > > >>> -----Original Message----- From: > > >>> [EMAIL PROTECTED] > > >>> [mailto:[EMAIL PROTECTED] On Behalf Of Beck, > > >>> Kenneth (STP) Sent: Monday, April 21, 2008 3:56 PM To: > > >>> r-help@r-project.org 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. > > >>> > > > > ______________________________________________ > > R-help@r-project.org mailing list > > https://stat.ethz.ch/mailman/listinfo/r-help > > PLEASE do read the posting guide > http://www.R-project.org/posting-guide.html > > and provide commented, minimal, self-contained, reproducible code. > > ______________________________________________ > R-help@r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-help > PLEASE do read the posting guide > http://www.R-project.org/posting-guide.html > and provide commented, minimal, self-contained, reproducible code. > ______________________________________________ R-help@r-project.org mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
