Poor documentation for "adj" and text()

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
2 messages Options
Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

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

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Poor documentation for "adj" and text()

frederik
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
>
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel

text.Rd.patch (3K) Download Attachment
Loading...