say more about dqrdc2 vs LINPACK`s DQRDC

git-svn-id: https://svn.r-project.org/R/trunk@71582 00db46b3-68df-0310-9c12-caf00c1e9a41

src/appl/dqrdc2.f

@@ -1,3 +1,4 @@
+C     Dqrdc2 is a *modification* Linpack's dqrdc ('DQRDC') for R
 c
 c     dqrdc2 uses householder transformations to compute the qr
 c     factorization of an n by p matrix x.  a limited column
@@ -55,21 +56,23 @@
 c
 c        k       integer.
 c                k contains the number of columns of x judged
-c                to be linearly independent.
+c                to be linearly independent, i.e., "the rank"
 c
 c        qraux   double precision(p).
 c                qraux contains further information required to recover
 c                the orthogonal part of the decomposition.
 c
-c        jpvt    jpvt(k) contains the index of the column of the
+c        jpvt    jpvt(j) contains the index of the column of the
 c                original matrix that has been interchanged into
-c                the k-th column.
+c                the j-th column.  Consequently, jpvt[] codes a
+c		 permutation of 1:p; it is called 'pivot' in R
+
 c
 c     original (dqrdc.f) linpack version dated 08/14/78 .
 c     g.w. stewart, university of maryland, argonne national lab.
 c
-c     this version dated 22 august 1995
-c     ross ihaka
+C     This version dated 22 August 1995
+C     Ross Ihaka
 c
 c     bug fixes 29 September 1999 BDR (p > n case, inaccurate ranks)
 c

src/library/base/man/qr.Rd

@@ -1,6 +1,6 @@
 % File src/library/base/man/qr.Rd
 % Part of the R package, https://www.R-project.org
-% Copyright 1995-2015 R Core Team
+% Copyright 1995-2016 R Core Team
 % Distributed under GPL 2 or later
 
 \name{qr}
@@ -88,18 +88,27 @@ as.qr(x)
   error giving a positive error code: these can only be interpreted by
   detailed study of the FORTRAN code.
 }
+\section{\code{*)}\sspace{} \code{dqrdc2} instead of LINPACK's DQRDC}{
+  In the (default) LINPACK case (\code{LAPACK = FALSE}), \code{qr()}
+  uses a \emph{modified} version of LINPACK's DQRDC, called
+  \sQuote{\code{dqrdc2}}.  It differs by using the tolerance \code{tol}
+  for a pivoting strategy which moves columns with near-zero 2-norm to
+  the right-hand edge of the x matrix.  This strategy means that
+  sequential one degree-of-freedom effects can be computed in a natural
+  way.
+}
 \value{
-  The QR decomposition of the matrix as computed by LINPACK or LAPACK.
+  The QR decomposition of the matrix as computed by LINPACK(*) or LAPACK.
   The components in the returned value correspond directly
-  to the values returned by DQRDC/DGEQP3/ZGEQP3.
+  to the values returned by DQRDC(2)/DGEQP3/ZGEQP3.
   \item{qr}{a matrix with the same dimensions as \code{x}.
     The upper triangle contains the \eqn{\bold{R}} of the decomposition
     and the lower triangle contains information on the \eqn{\bold{Q}} of
     the decomposition (stored in compact form).  Note that the storage
     used by DQRDC and DGEQP3 differs.}
   \item{qraux}{a vector of length \code{ncol(x)} which contains
     additional information on \eqn{\bold{Q}}.}
-  \item{rank}{the rank of \code{x} as computed by the decomposition:
+  \item{rank}{the rank of \code{x} as computed by the decomposition(*):
     always full rank in the LAPACK case.}
   \item{pivot}{information on the pivoting strategy used during
     the decomposition.}
@@ -116,7 +125,8 @@ as.qr(x)
   does not attempt to detect rank-deficient matrices.
 }
 \source{
-  For \code{qr}, the LINPACK routine \code{DQRDC} and the LAPACK
+  For \code{qr}, the LINPACK routine \code{DQRDC} (but modified to
+  \code{dqrdc2}(*)) and the LAPACK
   routines \code{DGEQP3} and \code{ZGEQP3}.  Further LINPACK and LAPACK
   routines are used for \code{qr.coef}, \code{qr.qy} and \code{qr.aty}.
 

src/main/registration.c

@@ -50,7 +50,7 @@
 #include <R_ext/Linpack.h>
 
 
-/*  These get the declarations of some routines refernced here but
+/*  These get the declarations of some routines referenced here but
     not explicitly declared.    This is necessary when we link with
     a C++ compiler because the linkage changes as the declarations
     are (currently) within extern "C" blocks.