> On 5/15/07, Alan G Isaac <[EMAIL PROTECTED]> wrote:
>> Just to add a bit more specificity, I believe that the
>> HOWTO_DOCUMENT.txt document at
>> http://svn.scipy.org/svn/numpy/trunk/numpy/doc/HOWTO_DOCUMENT.txt
>> summarizes a substantial discussion and broad agreement.
>> I.e., it is currently the preferred standard.
On Tue, 15 May 2007, Charles R Harris apparently wrote:
> I think the output generated for the consolidated lists is too ugly to bear.
> The bullets are distracting, there is no spacing between entries, and the
> explanatory text is appended on the same line, making it difficult to read.
> So get rid of ":Parameters:" and just use "Parameters: ". Futhermore, the
> dashes under Notes and Examples make these section headers and PyDoc moves
> these blocks to the top so that they are printed before the Parameters list
> and other list blocks. Did no one actually run this stuff through PyDoc? So
> my recommendations are to remove the leading :'s from the list headings,
> making them definition lists, italicize them, and insert the mandatory blank
> line after. Then remove the dashes from under Notes and Examples, and let
> the documenter choose between lists with the appended : , or just indent the
> text after, which has the same effect if there are no list item headings,
> which there typically aren't in those sections.
If this is meant as a reply to my post, it seems to treat my
simple summary as advocacy.
Now I am in fact an advocate of sticking with
reStructuredText, but I was simply summarizing how
I understood a rather *extended* discussion.
There was an outcome; I believe the doc above captures it.
Charles apparently wishes to reopen that discussion.
It will probably help to keep a few things separate.
Bullets in consolidated lists:
if you don't like them, don't use them.
Use a definition list instead.
(I like this much better myself.)
Formatting:
this is just a style issue.
Submit a CSS file.
Placement of Notes and Examples:
Seems simple to change, and the Epydoc developer has
been very accommodating. Raise it as an issue or submit
a patch.
I will not try to summarize all the reasons *for* relying on
reST, since these were hashed over in the previous
discussion. I will just mention the obvious: getting
additional functionality can have some costs, and one cost
of having access to all the possible epydoc
conversions---including typeset math in both PDF and XHTML
documents---is the use of (very light) informative markup.
Cheers,
Alan Isaac
_______________________________________________
Numpy-discussion mailing list
[email protected]
http://projects.scipy.org/mailman/listinfo/numpy-discussion
