barplot manpage (PR#7331)

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