[Doc-SIG] RE: Doc-SIG digest, Vol 1 #134 - 1 msg

[Ken Manheimer]

> 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