POLITZER-AHLES, Stephen [CBS]
2017-Mar-25 13:25 UTC
[Rd] Error in documentation for ?legend
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? --- Stephen Politzer-Ahles The Hong Kong Polytechnic University Department of Chinese and Bilingual Studies http://www.mypolyuweb.hk/~sjpolit/<http://www.mypolyuweb.hk/%7Esjpolit/> ________________________________ 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/> > > > [http://mlm.polyu.edu.hk/PolyU80_Email_Signature.png] > > www.polyu.edu.hk/80anniversary<http://www.polyu.edu.hk/80anniversary<http://www.polyu.edu.hk/80anniversary<http://www.polyu.edu.hk/80anniversary>> > > Disclaimer:\ \ This message (including any attachments) ...{{dropped:19}} > > ______________________________________________ > 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 [http://mlm.polyu.edu.hk/PolyU80_Email_Signature.png] www.polyu.edu.hk/80anniversary<http://www.polyu.edu.hk/80anniversary> Disclaimer:\ \ This message (including any attachments) ...{{dropped:19}}
>>>>> 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
> On 27 Mar 2017, at 09:59 , Martin Maechler <maechler at stat.math.ethz.ch> wrote: > > > (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 ..)I was also pointing out that the help page specifically does NOT document any such argument - otherwise the self-tests would have found the inconsistency long ago. What it does have is a (false) hint that there might somewhere be something called title.cex defaulting to the value of cex. The main point is that when someone claims that there is inconsistency between documentation and code, the first thing I do is to check the (long) argument list, the second thing is the (even longer) list of documented arguments. Neither has title.cex. No version information was given, so I couldn't know whether it might have been fixed in one of the more recent releases, etc. (I didn't fix it immediately on the off chance that the original author had actually planned to implement a title.cex feature. But he probably didn't.) -- 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