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

Fri Sep 14 09:38:42 CEST 2018

>>>>>   
>>>>>     on Thu, 13 Sep 2018 23:33:41 -0700 writes:

    > 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 see it marked in my box as some (of too many !) thing I had
wanted to look at.

OTOH,   R core  may not be terribly motivated by e-mail threads
starting with "Poor <something>" notably when that thing has
been in R (and S before that) for decades.
OTOH^2,  improving documentation is often a good and helpful
thing.... and I will look at it now.

Thank you, Frederick, for trying to help making R better!
Martin

    > 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

    > ______________________________________________
    > R-devel using r-project.org mailing list
    > https://stat.ethz.ch/mailman/listinfo/r-devel