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

[Ulrich Windl]

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