R devel - Nov 2005 - Inaccurate documentation for qr.R and qr.Q (PR#8347)

The documentation in QR.Auxiliaries {base} states

|qr.Q| returns part or all of *Q*, the order-nrow(X) orthogonal 
(unitary) transformation represented by |qr|. If |complete| is |TRUE|, 
*Q* has |nrow(X)| columns. If |complete| is |FALSE|, *Q* has |ncol(X)| 
columns. When |Dvec| is specified, each column of *Q* is multiplied by 
the corresponding value in |Dvec|.
|qr.R| returns *R*, the upper triangular matrix such that |X == Q %*% R|.

This last statement is true if there has been no pivoting, but if the 
LAPACK=TRUE option is turned on or the x matrix is complex, there is 
likely to be pivoting, and in that case Q %*% R is X with columns 
reordered by the pivot.  qr.X does return the original x matrix in 
either case, but a naive user who uses R alone (e.g. thinking that 
solve(R,crossprod(Q ,y)) will give ols estimates) could be misled.

Example:

 > x <- matrix(c(1,2,3,3,6,8),ncol=2)
 > qrlin <- qr(x)
 > qrla <- qr(x,LAPACK=TRUE)
 > qr.Q(qrlin) %*% qr.R(qrlin)
     [,1] [,2]
[1,]    1    3
[2,]    2    6
[3,]    3    8
 > qr.Q(qrla) %*% qr.R(qrla)
     [,1] [,2]
[1,]    3    1
[2,]    6    2
[3,]    8    3
 > qr.Q(qrla) %*% qr.R(qrla)[,qrla$pivot]
     [,1] [,2]
[1,]    1    3
[2,]    2    6
[3,]    3    8