On Sat, Mar 20, 2010 at 11:00 AM, Charles R Harris charlesr.harris@gmail.com wrote:

Example,

Compute the qr factorization of a matrix.

Factor the matrix `a` as `qr`, where `q` is orthonormal (:math:`dot( q_{:,i}, q_{:,j}) = \delta_{ij}`, the Kronecker delta) and `r` is upper-triangular.

Arrggghhhh... Totally. Unreadable. Why not say the columns of q are orthonormal vectors and r is upper triangular? The math tutorial should go in the notes, if anywhere. Might mention that this is a 'thin' factorization (Golub). Let me propose a rule: no math markup in the summary, ever.

Parameters ---------- a : array_like, shape (M, N) Matrix to be factored. mode : {'full', 'r', 'economic'} Specifies the information to be returned. 'full' is the default. mode='r' returns a "true" `r`, while 'economic' returns a "polluted" `r` (albeit slightly faster; see Returns below).

Oh, come now, "true", "polluted"? Sounds a bit political... Actually, 'economic' contains info on the Householder reflections. In any case, why mention it at all, just refer to the return documentation. And wouldn't values be a better word than information?

Mea culpa (at least up to this point) - I'll change it back.

I'm going to stay out of the whole terminal v. higher-tech display debate: I'm having trouble seeing a win-win.

DG