[Doc-SIG] epydoc reST markup for stdlib docstrings

[Ralf Gommers]

On Wed, Apr 14, 2010 at 10:56 PM, Michael Foord
<fuzzyman at voidspace.org.uk>wrote:

>  On 14/04/2010 16:48, Ralf Gommers wrote:
>
> The vertical whitespace vs tags is a taste issue, I agree, from a developer
> perspective. From a user perspective however, the numpy standard is clearly
> more readable in a terminal. That's why it looks the way it does. And
> reading docstrings in a terminal is not a fringe use case by the way.
>
> I would say that reading docstrings in a terminal is the *main* use case -
> but that is why I tend to value the vertical space highly and personally
> prefer the less verbose way.
>

You're a core developer (I think). But for the *average* user, do you really
think tags are fine? Earlier in this thread there was a mention of people
that love to read XML. I'm exaggerating a bit of course, but this is
similar. Whitespace beats tags for readability.

Ralf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/doc-sig/attachments/20100414/63ea33d3/attachment.html>