Re: [Rd] barplot manpage (PR#7331)

From: Tony Plate <tplate_at_acm.org>
Date: Wed 03 Nov 2004 - 02:57:05 EST

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).

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.

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 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.

Maybe inserting automatically generated "see also" references to "An Introduction to R" into the man pages would help beginners (and those who have to deal with cleaning up bug reports that aren't really bugs)?

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
> >



R-devel@stat.math.ethz.ch mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel Received on Wed Nov 03 03:34:49 2004

This archive was generated by hypermail 2.1.8 : Fri 18 Mar 2005 - 09:01:01 EST