[Rd] Poor documentation for "adj" and text()

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