[Doc-SIG] syntax vs semantics: implicit --> explicit

[Guido van Rossum]

> > I propose that this time around, we should focus on docstrings only,
> > and not on authoring other documents, lest we never reach an
> > agreement.
> 
> Agreed. But how long is a docstring? :> I like to put mini-to-full man-pages
> in my programs (accessible through --help), with section headers; perhaps
> I'm the exception.

How important is it that those mini-man pages are readable as part of
the source?  I've sometimes put arbitrary data in Python programs, for
bundling reasons, but not necessarily cared too much about how it
looks in the Python source (or even how easily editable it is).  I'm
just trying to figure out if your requirements really fit in the
requirements for docstrings.  It still sounds like you're stretching
things a bit.

I'm trying to argue for a smaller set of requirements, so we can make
progress.

> It was a matter of ill-defined styles in the publisher's stylesheet, Word
> quirks, cross-platform mangling, inter-version incompatibilities (I refuse
> to make M$ richer whenever they change a digit), and editorial bungling (I
> made sure all my curly quotes were right, and somebody converted them all to
> straight-quotes). Plus the stress of an all-nighter. Add a crash or two.

Sounds like a stretch to blame it on Word.

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