From m@ech|er @end|ng |rom @t@t@m@th@ethz@ch  Wed Oct  2 08:50:01 2019
From: m@ech|er @end|ng |rom @t@t@m@th@ethz@ch (Martin Maechler)
Date: Wed, 2 Oct 2019 08:50:01 +0200
Subject: [Rd] Improvement in hist command documentation
In-Reply-To: <86B01203-9D0C-45FA-A4F1-762E4B22C41E@u-bourgogne.fr>
References: <86B01203-9D0C-45FA-A4F1-762E4B22C41E@u-bourgogne.fr>
Message-ID: <23956.18585.282365.676969@stat.math.ethz.ch>

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



[Rd] Improvement in hist command documentation
Martin Maechler