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
Poor documentation for "adj" and text()
2 messages · Ulrich Windl, frederik at ofb.net
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
-------------- next part -------------- A non-text attachment was scrubbed... Name: text.Rd.patch Type: text/x-diff Size: 3381 bytes Desc: not available URL: <https://stat.ethz.ch/pipermail/r-devel/attachments/20170411/23c8f0e0/attachment.bin>