frederik m@ili@g off ofb@@et
2018-Sep-14 06:33 UTC
[Rd] Poor documentation for "adj" and text()
Hello Core Team, I sent this patch over a year ago. It looks like it was sent in response to another user's complaint which echoed some of my own observations about problems in the documentation for 'text'. Did anyone have a chance to look it over? I'd like to get it out of my queue. Thanks, Frederick On Tue, Apr 11, 2017 at 12:01:05PM -0700, frederik at ofb.net wrote:> Thanks Ulrich for sharing your experience. > > I'm attaching a patch which tries to address the issues you raised. > > I agree with you in principle, but I think it makes sense to leave > some details under "Details". However, the descriptions in "Arguments" > should give enough information that a user can get the function to do > something predictable in at least one situation, and I feel this is > not the case at present. > > I tried to fix the wording so that 'adj' and 'offset' are no longer > confusing to new users (or to me, every time I forget what they mean). > > I also fixed the paragraph on rotated text; it is more correct now, at > least for X11-cairo. > > I hope that someone in the Core Team can look this over and apply it. > > Thank you, > > Frederick > > On Tue, Apr 11, 2017 at 09:23:50AM +0200, Ulrich Windl wrote: > > Hi! > > > > (I'd like to be able to access your bugzilla, BTW) > > The documentation for parameter "adj" of text() in R 3.3.3 is hard to understand (unless you know what it does already): > > > > "adj > > one or two values in [0, 1] which specify the x (and optionally y) adjustment of the labels. On most devices values outside that interval will also work." > > > > What is the meaning of the values? I think the description ("adj allows adjustment of the text with respect to (x, y). Values of 0, 0.5, and 1 specify left/bottom, middle and right/top alignment, respectively. The default is for centered text, i.e., adj = c(0.5, NA). Accurate vertical centering needs character metric information on individual characters which is only available on some devices. Vertical alignment is done slightly differently for character strings and for expressions: adj = c(0,0) means to left-justify and to align on the baseline for strings but on the bottom of the bounding box for expressions. This also affects vertical centering: for strings the centering excludes any descenders whereas for expressions it includes them. Using NA for strings centers them, including descenders.") should be moved to the parameter. > > > > In general I'd suggest to describe the range, meaning and default of every parameter where the parameter is listed. "Details" should only give an overview of the functions. > > > > Likewise "offset": Will the direction be influenced by "pos"? The description is quite silent on that. > > > > Documentation should be structured to help the user to find the facts easily without having to read the whole page. > > > > Regards, > > Ulrich Windl > > > > ______________________________________________ > > R-devel at r-project.org mailing list > > https://stat.ethz.ch/mailman/listinfo/r-devel > >> --- text.Rd 2016-11-27 18:33:26.541516325 -0800 > +++ new-text.Rd 2017-04-11 11:48:32.668926075 -0700 > @@ -26,16 +26,18 @@ > If \code{labels} is longer than \code{x} and > \code{y}, the coordinates are recycled to the length of \code{labels}.} > \item{adj}{one or two values in \eqn{[0, 1]} which specify the x > - (and optionally y) adjustment of the labels. On most devices values > - outside that interval will also work.} > + (and optionally y) justification of the labels, with 0 for > + left/bottom, 1 for right/top, and 0.5 for centered. > + On most devices values > + outside \eqn{[0, 1]} will also work. See below.} > \item{pos}{a position specifier for the text. If specified this > overrides any \code{adj} value given. Values of \code{1}, > \code{2}, \code{3} and \code{4}, respectively indicate > positions below, to the left of, above and to the right of > - the specified coordinates.} > - \item{offset}{when \code{pos} is specified, this value gives the > - offset of the label from the specified coordinate in fractions > - of a character width.} > + \code{(x, y)}.} > + \item{offset}{when \code{pos} is specified, this value controls the > + distance of the text label from \code{(x, y)}, in fractions of a > + character width.} > \item{vfont}{\code{NULL} for the current font family, or a character > vector of length 2 for Hershey vector fonts. The first element of > the vector selects a typeface and the second element selects a > @@ -62,10 +64,11 @@ > mathematical notation is available such as sub- and superscripts, > greek letters, fractions, etc. > > - \code{adj} allows \emph{adj}ustment of the text with respect to > + \code{adj} allows \emph{adj}ustment of the text position with respect to > \code{(x, y)}. > - Values of 0, 0.5, and 1 specify left/bottom, middle and > - right/top alignment, respectively. The default is for centered text, i.e., > + Values of 0, 0.5, and 1 specify that \code{(x, y)} should align with > + the left/bottom, middle and > + right/top of the text, respectively. The default is for centered text, i.e., > \code{adj = c(0.5, NA)}. Accurate vertical centering needs > character metric information on individual characters which is > only available on some devices. Vertical alignment is done slightly > @@ -81,8 +84,17 @@ > labelled plot. > > Text can be rotated by using \link{graphical parameters} \code{srt} > - (see \code{\link{par}}); this rotates about the centre set by > - \code{adj}. > + (see \code{\link{par}}). When \code{adj} is specified, a non-zero > + \code{srt} rotates the label about \code{(x, y)}. If \code{pos} is > + specified, \code{srt} rotates the text about the point on its bounding > + box which is closest to \code{(x, y)}: top center for \code{pos = 1}, > + right center for \code{pos = 2}, bottom center for \code{pos = 3}, and > + left center for \code{pos = 4}. The \code{pos} interface is not as > + useful for rotated text because the result is no longer centered > + vertically or horizontally with respect to \code{(x, y)}. At present > + there is no interface in the base libraries to directly rotate text > + about its center, but you can achieve this by fiddling with \code{adj} > + each time you change \code{srt}. > > Graphical parameters \code{col}, \code{cex} and \code{font} can be > vectors and will then be applied cyclically to the \code{labels} (and> ______________________________________________ > R-devel at r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel
>>>>> >>>>> on Thu, 13 Sep 2018 23:33:41 -0700 writes:> Hello Core Team, I sent this patch over a year ago. It > looks like it was sent in response to another user's > complaint which echoed some of my own observations about > problems in the documentation for 'text'. Did anyone have > a chance to look it over? I see it marked in my box as some (of too many !) thing I had wanted to look at. OTOH, R core may not be terribly motivated by e-mail threads starting with "Poor <something>" notably when that thing has been in R (and S before that) for decades. OTOH^2, improving documentation is often a good and helpful thing.... and I will look at it now. Thank you, Frederick, for trying to help making R better! Martin > I'd like to get it out of my queue. > Thanks, > Frederick > On Tue, Apr 11, 2017 at 12:01:05PM -0700, frederik at ofb.net > wrote: >> Thanks Ulrich for sharing your experience. >> >> I'm attaching a patch which tries to address the issues >> you raised. >> >> I agree with you in principle, but I think it makes sense >> to leave some details under "Details". However, the >> descriptions in "Arguments" should give enough >> information that a user can get the function to do >> something predictable in at least one situation, and I >> feel this is not the case at present. >> >> I tried to fix the wording so that 'adj' and 'offset' are >> no longer confusing to new users (or to me, every time I >> forget what they mean). >> >> I also fixed the paragraph on rotated text; it is more >> correct now, at least for X11-cairo. >> >> I hope that someone in the Core Team can look this over >> and apply it. >> >> Thank you, >> >> Frederick >> >> On Tue, Apr 11, 2017 at 09:23:50AM +0200, Ulrich Windl >> wrote: > Hi! >> > >> > (I'd like to be able to access your bugzilla, BTW) > >> The documentation for parameter "adj" of text() in R >> 3.3.3 is hard to understand (unless you know what it does >> already): >> > >> > "adj > one or two values in [0, 1] which specify the x >> (and optionally y) adjustment of the labels. On most >> devices values outside that interval will also work." >> > >> > What is the meaning of the values? I think the >> description ("adj allows adjustment of the text with >> respect to (x, y). Values of 0, 0.5, and 1 specify >> left/bottom, middle and right/top alignment, >> respectively. The default is for centered text, i.e., adj >> = c(0.5, NA). Accurate vertical centering needs character >> metric information on individual characters which is only >> available on some devices. Vertical alignment is done >> slightly differently for character strings and for >> expressions: adj = c(0,0) means to left-justify and to >> align on the baseline for strings but on the bottom of >> the bounding box for expressions. This also affects >> vertical centering: for strings the centering excludes >> any descenders whereas for expressions it includes >> them. Using NA for strings centers them, including >> descenders.") should be moved to the parameter. >> > >> > In general I'd suggest to describe the range, meaning >> and default of every parameter where the parameter is >> listed. "Details" should only give an overview of the >> functions. >> > >> > Likewise "offset": Will the direction be influenced by >> "pos"? The description is quite silent on that. >> > >> > Documentation should be structured to help the user to >> find the facts easily without having to read the whole >> page. >> > >> > Regards, > Ulrich Windl >> > >> > ______________________________________________ > >> R-devel at r-project.org mailing list > >> https://stat.ethz.ch/mailman/listinfo/r-devel >> > >> --- text.Rd 2016-11-27 18:33:26.541516325 -0800 +++ >> new-text.Rd 2017-04-11 11:48:32.668926075 -0700 @@ -26,16 >> +26,18 @@ If \code{labels} is longer than \code{x} and >> \code{y}, the coordinates are recycled to the length of >> \code{labels}.} \item{adj}{one or two values in \eqn{[0, >> 1]} which specify the x - (and optionally y) adjustment >> of the labels. On most devices values - outside that >> interval will also work.} + (and optionally y) >> justification of the labels, with 0 for + left/bottom, 1 >> for right/top, and 0.5 for centered. + On most devices >> values + outside \eqn{[0, 1]} will also work. See below.} >> \item{pos}{a position specifier for the text. If >> specified this overrides any \code{adj} value given. >> Values of \code{1}, \code{2}, \code{3} and \code{4}, >> respectively indicate positions below, to the left of, >> above and to the right of - the specified coordinates.} >> - \item{offset}{when \code{pos} is specified, this value >> gives the - offset of the label from the specified >> coordinate in fractions - of a character width.} + >> \code{(x, y)}.} + \item{offset}{when \code{pos} is >> specified, this value controls the + distance of the text >> label from \code{(x, y)}, in fractions of a + character >> width.} \item{vfont}{\code{NULL} for the current font >> family, or a character vector of length 2 for Hershey >> vector fonts. The first element of the vector selects a >> typeface and the second element selects a @@ -62,10 >> +64,11 @@ mathematical notation is available such as sub- >> and superscripts, greek letters, fractions, etc. >> >> - \code{adj} allows \emph{adj}ustment of the text with >> respect to + \code{adj} allows \emph{adj}ustment of the >> text position with respect to \code{(x, y)}. - Values of >> 0, 0.5, and 1 specify left/bottom, middle and - right/top >> alignment, respectively. The default is for centered >> text, i.e., + Values of 0, 0.5, and 1 specify that >> \code{(x, y)} should align with + the left/bottom, middle >> and + right/top of the text, respectively. The default >> is for centered text, i.e., \code{adj = c(0.5, NA)}. >> Accurate vertical centering needs character metric >> information on individual characters which is only >> available on some devices. Vertical alignment is done >> slightly @@ -81,8 +84,17 @@ labelled plot. >> >> Text can be rotated by using \link{graphical parameters} >> \code{srt} - (see \code{\link{par}}); this rotates about >> the centre set by - \code{adj}. + (see >> \code{\link{par}}). When \code{adj} is specified, a >> non-zero + \code{srt} rotates the label about \code{(x, >> y)}. If \code{pos} is + specified, \code{srt} rotates the >> text about the point on its bounding + box which is >> closest to \code{(x, y)}: top center for \code{pos = 1}, >> + right center for \code{pos = 2}, bottom center for >> \code{pos = 3}, and + left center for \code{pos = 4}. The >> \code{pos} interface is not as + useful for rotated text >> because the result is no longer centered + vertically or >> horizontally with respect to \code{(x, y)}. At present + >> there is no interface in the base libraries to directly >> rotate text + about its center, but you can achieve this >> by fiddling with \code{adj} + each time you change >> \code{srt}. >> >> Graphical parameters \code{col}, \code{cex} and >> \code{font} can be vectors and will then be applied >> cyclically to the \code{labels} (and >> ______________________________________________ >> R-devel at r-project.org mailing list >> https://stat.ethz.ch/mailman/listinfo/r-devel > ______________________________________________ > R-devel at r-project.org mailing list > https://stat.ethz.ch/mailman/listinfo/r-devel
frederik m@ili@g off ofb@@et
2018-Sep-19 22:34 UTC
[Rd] Poor documentation for "adj" and text()
Thanks Martin. I wouldn't necessarily fault Ulrich for his subject line - unless you want to propose a better one... I might fault him for not following up and checking out the patch that I submitted at his prompting. I noticed that you committed my patch last Friday, with some welcome improvements, thanks! I'm assuming there is no easy way to get notified about commits, I just have to do 'svn update'? FWIW there are a lot of things that I would want to improve about R if I had the skill and the ability to do so. The patch hints at what I would improve about text rotation. Additionally, perhaps some other documentation issues; the fact that large plots can take forever and are not interruptable on the command line; I want better compatibility with tiling window managers (plots shouldn't have to be redrawn every time I switch to the window; they should come up with correct dimensions); better readline history facilities. I wouldn't assume that just because something has been the same way for decades that people like it that way! On the other hand I can see from the logs that there are at least several commits per day, so there must be a trade-off in different directions that the project can take. I made this graph: https://i.imgur.com/l4uCOek.png Best wishes, Frederick On Fri, Sep 14, 2018 at 09:38:42AM +0200, Martin Maechler wrote:> >>>>> > >>>>> on Thu, 13 Sep 2018 23:33:41 -0700 writes: > > > Hello Core Team, I sent this patch over a year ago. It > > looks like it was sent in response to another user's > > complaint which echoed some of my own observations about > > problems in the documentation for 'text'. Did anyone have > > a chance to look it over? > > I see it marked in my box as some (of too many !) thing I had > wanted to look at. > > OTOH, R core may not be terribly motivated by e-mail threads > starting with "Poor <something>" notably when that thing has > been in R (and S before that) for decades. > OTOH^2, improving documentation is often a good and helpful > thing.... and I will look at it now. > > Thank you, Frederick, for trying to help making R better! > Martin > > > > I'd like to get it out of my queue. > > > Thanks, > > > Frederick > > > On Tue, Apr 11, 2017 at 12:01:05PM -0700, frederik at ofb.net > > wrote: > >> Thanks Ulrich for sharing your experience. > >> > >> I'm attaching a patch which tries to address the issues > >> you raised. > >> > >> I agree with you in principle, but I think it makes sense > >> to leave some details under "Details". However, the > >> descriptions in "Arguments" should give enough > >> information that a user can get the function to do > >> something predictable in at least one situation, and I > >> feel this is not the case at present. > >> > >> I tried to fix the wording so that 'adj' and 'offset' are > >> no longer confusing to new users (or to me, every time I > >> forget what they mean). > >> > >> I also fixed the paragraph on rotated text; it is more > >> correct now, at least for X11-cairo. > >> > >> I hope that someone in the Core Team can look this over > >> and apply it. > >> > >> Thank you, > >> > >> Frederick > >> > >> On Tue, Apr 11, 2017 at 09:23:50AM +0200, Ulrich Windl > >> wrote: > Hi! > >> > > >> > (I'd like to be able to access your bugzilla, BTW) > > >> The documentation for parameter "adj" of text() in R > >> 3.3.3 is hard to understand (unless you know what it does > >> already): > >> > > >> > "adj > one or two values in [0, 1] which specify the x > >> (and optionally y) adjustment of the labels. On most > >> devices values outside that interval will also work." > >> > > >> > What is the meaning of the values? I think the > >> description ("adj allows adjustment of the text with > >> respect to (x, y). Values of 0, 0.5, and 1 specify > >> left/bottom, middle and right/top alignment, > >> respectively. The default is for centered text, i.e., adj > >> = c(0.5, NA). Accurate vertical centering needs character > >> metric information on individual characters which is only > >> available on some devices. Vertical alignment is done > >> slightly differently for character strings and for > >> expressions: adj = c(0,0) means to left-justify and to > >> align on the baseline for strings but on the bottom of > >> the bounding box for expressions. This also affects > >> vertical centering: for strings the centering excludes > >> any descenders whereas for expressions it includes > >> them. Using NA for strings centers them, including > >> descenders.") should be moved to the parameter. > >> > > >> > In general I'd suggest to describe the range, meaning > >> and default of every parameter where the parameter is > >> listed. "Details" should only give an overview of the > >> functions. > >> > > >> > Likewise "offset": Will the direction be influenced by > >> "pos"? The description is quite silent on that. > >> > > >> > Documentation should be structured to help the user to > >> find the facts easily without having to read the whole > >> page. > >> > > >> > Regards, > Ulrich Windl > >> > > >> > ______________________________________________ > > >> R-devel at r-project.org mailing list > > >> https://stat.ethz.ch/mailman/listinfo/r-devel > >> >