barplot manpage (PR#7331)
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, dan@bolser.co.uk 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?
______________________________________________ R-devel@stat.math.ethz.ch mailing list https://stat.ethz.ch/mailman/listinfo/r-devel