Would you mind telling me how to get at the documentation source code? Is there a - how to change the documentation document? ( I will make one if you give me some instructions....
I guess I can just edit a copy of the source and diff the original and send the diff ? Cheers, Dan. On Tue, 2 Nov 2004, Tony Plate wrote: >I suspect that part of the reason for having terse documentation is that it >is easier to maintain when changes are made to the code. Now that R is >more stable and mature maybe documentation could get a bit more expansive? > >I also suspect that you will have a better chance of getting improvements >into the documentation if you make specific suggestions about changes to >the source code of the documentation, i.e., including the exact proposed >wording and markup. This will make it easy for someone with the necessary >permissions (a member of R-core, I guess) to make the changes. > >Tony Plate > >At Tuesday 09:25 AM 11/2/2004, Dan Bolser wrote: >>On Tue, 2 Nov 2004, Tony Plate wrote: >> >> >Yup, I think you're right. R is a volunteer project, so what needs to >> >happen to improve the documentation is that some capable volunteers (or >> >just one volunteer) step forward. It is the prerogative of the members of >> >R-core to decide whether to spend their time on improving documentation or >> >improving the functionality (or merely having a life). >> >>I could try making better pages for the functions I use. >> >> >> >However it is worth noting that R does have really quite good documentation >> >for a piece of software of its kind, compared to both other open source and >> >commercial software. >> >>That is very true. However, I still maintain that the emphasis is on >>developers and not learners. >> >> >> >What would need to be improved in the document "An Introduction to R", >> >specifically, the subsubsection on "Graphical Elements" (under "Graphics >> >Parameters List" in "Graphical Procedures", p 77 in my copy) in order that >> >it would meet the criterion of being "less formal man pages"? There's a >> >>Having it to hand when you need it (i.e. at the command line) like other >>man style documentation systems. Also having reference to all the related >>functions. >> >>My problem is this, my barplot has decided to use SI for big numbers. I >>would rather it use the number in full... How do I do it? I don't know... >>Some of my column labels are going missing... how do I fix it... I don't >>know... My legend is in the top right when the top left would be much >>better, how do I fix it... >> >>I read ?barplot, but I didn't *see* what I needed - I don't doubt that >>someone who already knew how to do these things could look at ?barplot and >>say that its fine. I can't say that. >> >> >> >> >lot to be said for having the "less formal" documentation being organized >> >around concepts rather than specific functions (as the man pages are), >> >because the conceptual organization allows more organized discussion of how >> >functions work together and which are the appropriate functions to >> >accomplish certain types of tasks. >> >>True, but that is a different task. A 'guide to use' is different from a >>'user guide'. I find time and time again tiny problems (conceptually >>trivial) which are very frustrating in R, I don't want to ask a question >>on the list, I don't want to trawl the archives for the answer, I want a >>clearer explanation of how the darn function works! >> >>I think having a concept based approach is essential (as you say), but the >>'nuggets' should be posted around to the different functions, so each >>concept for each function is indexed under that function for easy >>retrieval (if that makes sense). >> >> >> >Maybe inserting automatically generated "see also" references to "An >> >Introduction to R" into the man pages would help beginners (and those who >> >>I think so. >> >> >have to deal with cleaning up bug reports that aren't really bugs)? >> >>Sorry, I made some comment about 'constantly wanted to improve the info >>pages' on the mailing list, (with regards to a Wiki dump of the said pages >>into the user domain). One reply said that instead I should request that >>the documents be changed via a bug report from the R web site. >> >>I honestly want to give my time and energy to help users like me use R. I >>very often find the man pages totally cryptic and often frustrating. >> >>Sometimes the examples read like entries from a Perl obfustication >>competition - people taking delight in doing things as tersely as possible >>to 'get kudos' from their 'knowledgeable' peers. >> >>The Perl documentation system is a joy to use. However, we shouldn't >>compare apples and oranges... >> >>Thanks for your help, and sorry for the inconvenience. I am (still) only >>trying to help :) >> >>All the best >>Dan. >> >> >-- Tony Plate >> > >> >At Tuesday 12:52 AM 11/2/2004, Dan Bolser wrote: >> > >> >>Should these be in the (see also section)? >> >> >> >>Like I said, the pages read fine if you understand the content already. I >> >>think some less formal man pages would drastically reduce the traffic on >> >>the R mailing list. >> >> >> >>Just a hunch, >> >>Dan. >> >> >> >>On Mon, 1 Nov 2004, Tony Plate wrote: >> >> >> >> >Look at the help page for "par" for explanations of "cex" and "lty". >> >> > >> >> >The use of 'mp' is as a variable, as in >> >> > >> >> > > mp <- barplot(....) >> >> > >> >> >The next paragraph refers to this variable. >> >> > >> >> >-- Tony Plate >> >> > >> >> >At Monday 05:12 PM 11/1/2004, [EMAIL PROTECTED] wrote: >> >> >>Full_Name: Dan B >> >> >>Version: R 2.0.0 (2004-10-04). >> >> >>OS: Fedora 2 >> >> >>Submission from: (NULL) (80.6.127.185) >> >> >> >> >> >> >> >> >>The man page for barplot (?barplot) is confusing... >> >> >> >> >> >><quote> >> >> >>cex.axis: expansion factor for numeric axis labels. >> >> >>cex.names: expansion factor for axis names (bar labels). >> >> >></quote> >> >> >> >> >> >>What is an 'expansion factor', and what does it do in this context? >> >> >> >> >> >> >> >> >><quote> >> >> >>axis.lty: the graphics parameter 'lty' applied to the axis and tick >> >> >> marks of the categorical (default horizontal) axis. Note >> >> >> that by default the axis is suppressed. >> >> >></quote> >> >> >> >> >> >>This makes no sense unless you know what it does already (which I >> >> don't). So >> >> >>this is more of a programmers cleft note in a 'common language' than a >> >> >>function >> >> >>documentation page. >> >> >> >> >> >><quote> >> >> >>say 'mp', giving the coordinates of _all_ the bar midpoints drawn, >> >> >></quote> >> >> >> >> >> >>Say what? >> >> >> >> >> >>______________________________________________ >> >> >>[EMAIL PROTECTED] mailing list >> >> >>https://stat.ethz.ch/mailman/listinfo/r-devel >> >> > >> > > ______________________________________________ [EMAIL PROTECTED] mailing list https://stat.ethz.ch/mailman/listinfo/r-devel
