[Rd] Error in documentation for ?legend

[Martin Maechler]

>>>>> POLITZER-AHLES, Stephen [CBS] <stephen.politzerahles at polyu.edu.hk>
>>>>>     on Sat, 25 Mar 2017 13:25:32 +0000 writes:

    > Right, that's my point. The help page mentions a
    > `title.cex`, like I said; saying that `cex` sets the
    > default `title.cex` sure implies to me (and presumably to
    > the other people whose discussion I linked) that a
    > `title.cex` parameter exists. Since no such parameter
    > exists, this bit in the documentation is misleading
    > (suggesting that there is a `title.cex` parameter which
    > can be set, when there really isn't). Regardless of
    > whether we call it an "oddity" or what, I don't think it's
    > controversial that this is misleading. If it's misleading,
    > shouldn't it be removed?

Yes.
I've done so now,  thank you for the report!

(You did not understand Peter:  He *did* agree with you that
 there's no 'title.cex' argument  and explained why the oddity
 probably has happened in the distant past ..)

Martin Maechler
ETH Zurich
and R Core Team (as Peter Dalgaard)

    > From: peter dalgaard <pdalgd at gmail.com>
    > Sent: Saturday, March 25, 2017 9:10:57 PM
    > To: POLITZER-AHLES, Stephen [CBS]
    > Cc: r-devel at r-project.org
    > Subject: Re: [Rd] Error in documentation for ?legend


    >> On 25 Mar 2017, at 00:39 , POLITZER-AHLES, Stephen [CBS] <stephen.politzerahles at polyu.edu.hk> wrote:
    >> 
    >> To whom it may concern:
    >> 
    >> 
    >> The help page for ?legend refers to a `title.cex` parameter, which suggests that the function has such a parameter.

    > No it does not. All arguments are listed and documented, none of them is title.cex, and there's no "...".

    > However, the documentation for "cex" has this oddity inside:

    > cex: character expansion factor *relative* to current
    > �par("cex")�.  Used for text, and provides the default for
    > �pt.cex� and �title.cex�.

    > Checking the sources suggests that this is the last anyone has seen of title.cex:

    > pd$ grep -r title.cex src
    > src/library/graphics/man/legend.Rd:    \code{pt.cex} and \code{title.cex}.}
    > pd$

    > The text was inserted as part of the addition of the title.col (!) argument, so it looks like the author got some wires crossed.

    > -pd

    >> As far as I can tell, though, it doesn't; here's an example:
    >> 
    >> 
    >>> plot(1,1)
    >>> legend("topright",pch=1, legend="something", title="my legend", title.cex=2)
    >> Error in legend("topright", pch = 1, legend = "something", title = "my legend",  :
    >> unused argument (title.cex = 2)
    >> 
    >> 
    >> This issue appears to have been discussed online before (e.g. here's a post from 2011 mentioning it: http://r.789695.n4.nabble.com/Change-the-text-size-of-the-title-in-a-legend-of-a-R-plot-td3482880.html) but I'm not sure if anyone ever reported it to R developers.
    >> 
    >> 
    >> Is it possible for someone to update the ?legend documentation page so that it doens't refer to a parameter that isn't usable?
    >> 
    >> Best,
    >> 
    >> Steve Politzer-Ahles
    >> 
    >> ---
    >> Stephen Politzer-Ahles
    >> The Hong Kong Polytechnic University
    >> Department of Chinese and Bilingual Studies
    >> http://www.mypolyuweb.hk/~sjpolit/<http://www.mypolyuweb.hk/%7Esjpolit/>
    >> 
    >> ______________________________________________
    >> R-devel at r-project.org mailing list
    >> https://stat.ethz.ch/mailman/listinfo/r-devel

    > --
    > Peter Dalgaard, Professor,
    > Center for Statistics, Copenhagen Business School
    > Solbjerg Plads 3, 2000 Frederiksberg, Denmark
    > Phone: (+45)38153501
    > Office: A 4.23
    > Email: pd.mes at cbs.dk  Priv: PDalgd at gmail.com