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

[David Goldsmith]

On Sat, Mar 20, 2010 at 12:41 PM, David Goldsmith
<d.l.goldsmith at gmail.com> wrote:
> On Sat, Mar 20, 2010 at 11:00 AM, Charles R Harris
> <charlesr.harris at 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

OK, reverted my changes, and "demoted" to "Being written" pending some
form of resolution vis-a-vis the Returns list debate.

DG