[Doc-SIG] StructuredText suitability for docstrings

[Moshe Zadka]

On Mon, 31 Jan 2000, Ken Manheimer wrote:

> 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.

You seemed to have missed my point -- it being that there is (in XML
nomencalture) an element type in OOL docs whose content corresponds
one-to-one to valid docstrings.

Please re-read my post in light of this clarification, and see if you
still have objections to it. I think that answers your problems, but then
again maybe *I* didn't understand *you*.

> 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.

Well, depends on the type of readability you mean. StructuredText seems
a bit too much DWIM (Perlish for "do what I mean") for it to be something
I'm too comfortable with, particularily as to how well it can satisfy some 
"one-to-one" mapping req. which I think we can agree is neccassery for any
coherence in the documentation system.

--
Moshe Zadka <mzadka@geocities.com>. 
INTERNET: Learn what you know.
Share what you don't.