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

[frederik m@ili@g off ofb@@et]

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 using 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 using 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 using r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel