[Doc-SIG] Comments on DPS and reStructuredText

[Tony J Ibbs (Tibs)]

OK, folks, I finally had time to read through all of David's documents
(whilst on holiday last week), and I've now had time to type up the
comments.

First off, I should say that there are no show-stoppers as far as I'm
concerned - I would prefer some things to be slightly different, but
would also be prepared to use reST (hope that abbreviation is OK) as it
is, if I could not influence any changes. That may not matter much to
other people, but is a vast relief to me (it is also, incidentally, the
result I expected to find).

I've attempted to write the comments up *using* reST, but I'm fairly
sure I'll have done it wrong because I was typing rather than looking up
reST syntax. I *shall* be working on a "cheat sheet" or quick reference,
for my own use if no-one else's - a *very* early version is at
http://homepage.ntlworld.com/tibsnjoan/reST/quick_reST.html, but I need
to look at the Python quick reference for inspiration on layout, and do
more typing.

I've lumped my comments up by source, so they are:

	* DPS comments
	* comments on PEP 257's example
	* reST comments
	* comments on reST "notes"
	* comments on "problems with structured text"
	* some notes on reST "modes"

I'll email them separately to the list. They're also available in the
same directory as the quick reference mentioned above.

I still want to write something on "field labels" (what were "paragraph
labels") and maybe on descriptive lists, but that will have to be
another day.

Oh - and if MoinMoin starts to use reST, that would be *brilliant*!

Sorry for the vast delay in producing any input - hope this helps...

Tibs

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)