On Sun, Mar 21, 2010 at 12:24 AM, Charles R Harris email@example.com wrote:
On Sat, Mar 20, 2010 at 8:54 PM, Ralf Gommers firstname.lastname@example.org wrote:
On Sun, Mar 21, 2010 at 10:18 AM, Charles R Harris email@example.com wrote:
On Sat, Mar 20, 2010 at 7:45 PM, Ralf Gommers firstname.lastname@example.org wrote:
On Sun, Mar 21, 2010 at 4:18 AM, Charles R Harris email@example.com wrote:
On Sat, Mar 20, 2010 at 1:32 PM, Alan G Isaac firstname.lastname@example.org wrote:
On 3/20/2010 2:15 PM, email@example.com wrote: > As far as I know, stars are the only way to render a list in > restructured txt, otherwise it looses the list formatting.
Try a definition list? Example below. Alan
q, r if mode = 'full': - q : ndarray of float or complex, shape (M, K) - r : ndarray of float or complex, shape (K, N)
K = min(M, N)
r if mode = 'r': - r : ndarray of float or complex, shape (K, N)
a2 if mode = 'economic': - a2 : ndarray of float or complex, shape (M, N)
The diagonal and the upper triangle of a2 contains r, while the rest of the matrix is undefined.
Maybe handle it in a manner similar to the other sections.
q,r <> mode = 'r'' q: [M,N] ndarray The columns of 'q' are orthonomal. r: [K,N] ndarray Upper triangular array. ...
The "<>" standing in for "if". The indentation could be moved out.
Looks good, but what determines that this is a list, the <>? What if you want a list that does not use if's? If this can be made to work, great, but it will probably be much more robust if there's some kind of markup. Stars or dashes would not look that bad imho if there would be no need for blank lines.
That was just a suggestion, I think it can probably be improved upon. Thoughts?
In general a list should just be defined with *. Like:
- item 1
* sub-item 1 Hey, a multi-line sub-item works too! * sub-item 2
- item 2
I really, really want to get rid of the asterisks, they are ugly and distracting (IMHO). Unlike dashes, colons, and underlines they aren't part of the usual textual repetoire.
but bullets (bullet lists) are, at least in latex and powerpoint, and asterisks are the ASCI version of bullet points, and all my regular notes (targeted for wiki markup or rst) use them heavily to structure lists.
dashes would be also ok, but I don't think rst would recognize them. My main problem with rst is that it doesn't allow hard line breaks, which forces some kind of markup to render lists.
But as Ralf's rewrite shows, there is often a way to get around lists. I only know of a few places in the scipy docs, where list items in the Parameters or Returns are really necessary.
In the specific case of a variable number of return values, I do not like the if..else construction. How about this:
q : ndarray The q-value. If mode='r' this contains .... If mode='economic' .... r : ndarray, optional The r-value. Is only returned if mode='r'.
In the case at hand, q is optional and r has two forms.
'optional' could be changed to 'conditional' or something like that.
NumPy-Discussion mailing list NumPy-Discussion@scipy.org http://mail.scipy.org/mailman/listinfo/numpy-discussion