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