Improvement in hist command documentation

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

Improvement in hist command documentation

Jérôme LAURENS
Hi all,

In the histogram created with the `hist` command, the label of the y axis reads "Frequency ».
Finding that the ylab key is used to change (localize) that word may seem difficult for people
who are beginners either in R or in english.

I suggest very minor modifications of the file hist.Rd at https://svn.r-project.org/R/trunk/src/library/graphics/man/hist.Rd.
1) make the default value for ylab explicit, similarly to main and xlab
2) make the word "label" explicitly appear in the documentation for the ylab key

That way, people looking either for the word "label" or the word "Frequency" in hist’s help will get more chance to find the ylab key.

Here is the diff with revision 77240

17c17
<      xlab = xname, ylab,
---
>      xlab = xname, ylab = "Frequency",
65,66c65,66
<   \item{main, xlab, ylab}{these arguments to \code{title} have useful
<     defaults here.}
---
>   \item{main, xlab, ylab}{to change the default value of the main title,
>     the label of the x axis or the label of the y axis.}

Thanks for your efforts.

JL

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Improvement in hist command documentation

Martin Maechler
>>>>> Jérôme LAURENS
>>>>>     on Tue, 1 Oct 2019 11:47:38 +0200 writes:

    > Hi all,
    > In the histogram created with the `hist` command, the label of the y axis reads "Frequency ».
    > Finding that the ylab key is used to change (localize) that word may seem difficult for people
    > who are beginners either in R or in english.

    > I suggest very minor modifications of the file hist.Rd at https://svn.r-project.org/R/trunk/src/library/graphics/man/hist.Rd.
    > 1) make the default value for ylab explicit, similarly to main and xlab
    > 2) make the word "label" explicitly appear in the documentation for the ylab key

    > That way, people looking either for the word "label" or the word "Frequency" in hist’s help will get more chance to find the ylab key.

    > Here is the diff with revision 77240

    > 17c17
    > <      xlab = xname, ylab,
    > ---
    >> xlab = xname, ylab = "Frequency",
    > 65,66c65,66
    > <   \item{main, xlab, ylab}{these arguments to \code{title} have useful
    > <     defaults here.}
    > ---
    >> \item{main, xlab, ylab}{to change the default value of the main title,
    >> the label of the x axis or the label of the y axis.}

    > Thanks for your efforts.
    > JL

Thank you, Jérôme, for helping to improve R's documentation.

I was hoping others would point out that your '1)' is wrong
unfortunately:  As the current doc say  - not optimally -

   " these arguments ... have useful defaults here "

and the default for ylab is not just "Frequency", and the whole
thing is a bit more subtle than you think notably because a
"histogram" object is constructed with a plot method, etc.
Please look at the source code the development of which code is
always visible here
  https://svn.r-project.org/R/trunk/src/library/graphics/R/hist.R

But you are right that the

 \item{main, xlab, ylab}{these arguments to \code{title} have useful
    defaults here.}

can be improved and I will do so, ensuring that 'label' will
appear there.

Best regards,

Martin Maechler,
ETH Zurich and R Core Team

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel