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