[Rd] barplot manpage (PR#7331)

[Dan Bolser]

Would you mind telling me how to get at the documentation source code?

Is there a - how to change the documentation document? ( I will make one
if you give me some instructions....

I guess I can just edit a copy of the source and diff the original and
send the diff ?

Cheers,
Dan.


On Tue, 2 Nov 2004, Tony Plate wrote:

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