From Kurt.Hornik at wu-wien.ac.at  Thu May  4 09:18:53 2006
From: Kurt.Hornik at wu-wien.ac.at (Kurt Hornik)
Date: Thu, 4 May 2006 09:18:53 +0200
Subject: [Rd] abline and its documentation
In-Reply-To: <20060503220436.GA18145@phenix.sram.qc.ca>
References: <20060503220436.GA18145@phenix.sram.qc.ca>
Message-ID: <17497.43741.908109.939891@mithrandir.hornik.net>

>>>>> Fran?ois Pinard writes:

> Hi, people.  The documentation of abline says:
> Usage:

>      abline(a, b, untf = FALSE, ...)
>      abline(h=, untf = FALSE, ...)
>      abline(v=, untf = FALSE, ...)
>      abline(coef=, untf = FALSE, ...)
>      abline(reg=, untf = FALSE, ...)


> so suggesting that h= and v= usages are exclusive.  There are examples 
> in the mailing list archives of using both at the same time, and I find 
> convenient, for example, doing:

>     abline(h=0, v=0, ...)

> for bolding the position of the origin or the axes through the origin.


> By doing so, we are using undocumented capabilities of abline and 
> consequently, writing bugged R code.  It does not matter so much 
> interactively, but scripts may be more sensitive.

> Would it be acceptable to amend abline documentation, so to commit the 
> capability of abline to do both h= and v= at once?   Or even combined 
> with intercept and slope?  (abline is able to do all three at once 
> already!)  Then, R users and code could more safely rely on this.

> Just a suggestion, and not a big matter, of course! :-)

Afaic, I would change the \usage to just given the function synopsis
(removing \synopsis along the way), and indicate the various usage
scenarios via details and/or examples.

-k



[Rd] abline and its documentation
Kurt Hornik