R devel - Oct 2019 - Improvement in hist command documentation

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

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