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

[Guido van Rossum]

> (Last year I wrote a chapter on Python for Wrox Press' "Professional
> Linux Programming". I would have been much happier using a complete
> ST-like markup than futzing around in MSWord.)

I've a feeling that one reason the doc-sig is going around in circles
is the tension between the needs of formatting docstrings and the
needs of formatting larger documents.  For docstrings, there's an
explicit requirement (although not everybody gives it the same weight)
that the source is pleasantly readable as plain text.  For authoring
larger documents like your Wrox chapter, that argument doesn't have
the same importance: wat you want is easy authoring, which is subtly
but importantly different.

I propose that this time around, we should focus on docstrings only,
and not on authoring other documents, lest we never reach an
agreement.

(Aside: I'd like to know more about why you think Word didn't work for
you; I wonder if it could be unfamiliarity with advanced Word
features?  When using styles properly, Word is quite a capable
authoring tool -- depending, of course, on the processing done by the
publisher.)

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