Date: Fri, 28 Jan 2000 08:16:06 +0200 (IST) From: Moshe Zadka <moshez@math.huji.ac.il> Reply-To: Moshe Zadka <mzadka@geocities.com> To: doc-sig@python.org Subject: [Doc-SIG] Some Premilinary Thoughts on Syntax

[...] The first thing we would need is to make sure the two markups are semantically equivalent. More precisely, we'll need to figrue out what "element" (to use XML terminilogy) an embedded doc string corresponds to in the OOL (out of line) documentation, and make sure we have a one to one correspondence betweent the syntaxes. At the risk of being flamed to death, I will offer that this means throwing StructureText clean out of the door, as it is impossible to reason about it. The only structured text idea that would be left would be indentation for blocks, because it meashes well with the rest of the code.

No flames here, i'm only for going with StructuredText if it suits the purpose. But i don't understand your disqualifying criterion. Specifically, i don't see *why* there must be a one-to-one correspondence between the OOL and docstring documentation. I would think the requirement is that all docstring elements map to some OOL elements, but that it's acceptable - probably even desirable - for the collection of docstring elements to be a subset of the OOL collection. Ie, seems to me that there's a lot of stuff that the OOL needs that the docstrings emphatically don't - i'd assume docstrings are pretty localized elements that may need to refer to, but don't need to embody, the larger-scale (chapters, sections, etc) or more specialized (footnotes, tables-of-contents, etc) book structures. If so, i don't see why the StructuredText approach would be disqualified at the outset (colloquialism for "at the start"). And in fact it seems to me that something like StructuredText is necessary to satisfy readability/naturalness, if those are in fact requirements. Ken Manheimer klm@digicool.com