[Doc-SIG] lightweight markup: bullets

[klm@digicool.com]

First chance i've had to chime in this week, and only have a moment to
sound my repeating refrain: i would like to see the
structured-text-ish approach.

Someone (was it you, edward?) mentioned the non-geek CP4E-type
audience earlier this week - i'm dismayed to think that we're talking
about exposing them to code in docstrings, eg C<> or Z{} or whatever,
that's more cryptic than lots of python code.  The docstrings should
be more self-obvious, not less!!

Truly, even as a *programmer* i find it helpful that docstring
encoding is written-language encoding, which i can automatically
decipher.  **That's** the reason that the structured text approach
makes sense - the overt meanings of the conventions for the reader,
even the unitiated reader, are the intended ones.  You don't need the
secret codes or a tool to read the docstrings in the program text.

Evidently, the trick is coming up with a decent set of structured text
style rules that are unambiguous and "unsurprising" - in particular,
conventions that don't collide with common writing practices.  (Eg,
collide ones recently discussed: use of '--' for description lists, or
"1." at the end of a sentence but beginning of line translating to the
start of an ordered list item.)  Once again, it seems to me that we're
close to this goal, but veering off to a new language, with C<> or
whatever - totally at the expense of the reader.

Really, it seems to me that such docstrings would make python code
*less* readable, not more.

Oh well.

Ken
klm@digicool.com