# [Numpy-discussion] Help!!! Docstrings overrun by markup crap.

Sat Mar 20 13:16:09 CDT 2010

On Sun, Mar 21, 2010 at 2: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.
>

That's already a rule, although it could be expressed even clearer. My
understanding is: latex only in the Notes section, and even there very
sparingly.

Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.scipy.org/pipermail/numpy-discussion/attachments/20100321/e9cbd565/attachment.html