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

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

Thanks Martin.

I wouldn't necessarily fault Ulrich for his subject line - unless you
want to propose a better one... I might fault him for not following up
and checking out the patch that I submitted at his prompting.

I noticed that you committed my patch last Friday, with some welcome
improvements, thanks! I'm assuming there is no easy way to get
notified about commits, I just have to do 'svn update'?

FWIW there are a lot of things that I would want to improve about R if
I had the skill and the ability to do so. The patch hints at what I
would improve about text rotation. Additionally, perhaps some other
documentation issues; the fact that large plots can take forever and
are not interruptable on the command line; I want better compatibility
with tiling window managers (plots shouldn't have to be redrawn every
time I switch to the window; they should come up with correct
dimensions); better readline history facilities. I wouldn't assume
that just because something has been the same way for decades that
people like it that way! On the other hand I can see from the logs
that there are at least several commits per day, so there must be a
trade-off in different directions that the project can take.

I made this graph:

https://i.imgur.com/l4uCOek.png

Best wishes,

Frederick

On Fri, Sep 14, 2018 at 09:38:42AM +0200, Martin Maechler wrote:
> >>>>>   
> >>>>>     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
>     >> >