[Rd] barplot manpage (PR#7331)

[Tony Plate]

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