[Doc-SIG] lightweight markup: bullets
klm@digicool.com
klm@digicool.com
Sat, 14 Apr 2001 12:37:56 -0400 (EDT)
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