[Rd] barplot manpage (PR#7331)
Prof Brian Ripley
ripley at stats.ox.ac.uk
Tue Nov 2 18:39:40 CET 2004
There are books about R: have you tried reading a couple (or more)?
And what training have you had in technical communication (which includes
honing your reading skills)?
In contrast, I find the Perl documentation very hard to use and
insufficiently precise, and would be surprised if many learners used it
before reading one of the Perl books.
Precision is a great virtue in written technical communication. Far more
common a problem on R-help is a far too vague statement of the problem, or
a user failing to read the documentation.
On Tue, 2 Nov 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
> >> >
> >
>
> ______________________________________________
> R-devel at stat.math.ethz.ch mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>
>
--
Brian D. Ripley, ripley at stats.ox.ac.uk
Professor of Applied Statistics, http://www.stats.ox.ac.uk/~ripley/
University of Oxford, Tel: +44 1865 272861 (self)
1 South Parks Road, +44 1865 272866 (PA)
Oxford OX1 3TG, UK Fax: +44 1865 272595
More information about the R-devel
mailing list