POD (was RE: [Doc-SIG] using the same delimiter on the left and right..)

[Guido van Rossum]

> On Thu, 29 Mar 2001 14:40:53 -0500, Tim Peters wrote:
> 
> >It's easy to use, and is mostly idiot-proof.  OTOH, it's not *obvious* at
> >first glance, particularly not the list stuff.  But it's a matter of no more
> >than two minutes to *learn* the list conventions, and then they're easy too.
> 
> It is. It breaks the "purity" of the plain text ideal (not a problem
> _for me_).

Nor for me.

> I 100% dislike the notion visually empty lines are not
> logically empty (see the pitfalls).

There's no need to make the same mistakes.

> And finally, we'd need to extend the rules so that common leading
> whitespace is removed before processing (so we can properly indent
> docstrings).

Yes -- that's always a given for docstrings.  (I hate reading
unindented docstrings!)

> >pod-is-a-lot-more-pythonic-then-perl-ly y'rs  - tim
> 
> Think so too. I could live with it as a default docstring
> markup. Tim, what do you think about a way to identify which
> docstring format is used for a module, without resorting to some AI
> code figuring out the format from the text itself?
> 
> This would relieve the pressure to find a format liked by all
> people, and also open up easy upgrade paths.

A special marker anywhere in the first or second docstring of a module
(at the end of the first, assuming that any tool has to be able to
find the end of the docstring anyway; or at the beginning of the
second, which hides it from more primitive historic docstring
processors); or if that's too complicated, a funny-looking comment
would do fine.

--Guido van Rossum (home page: http://www.python.org/~guido/)