[Rd] barplot manpage (PR#7331)

[Tony Plate]

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

-- 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 at 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 at stat.math.ethz.ch mailing list
> >>https://stat.ethz.ch/mailman/listinfo/r-devel
> >