[Doc-SIG] more user testing

[Moshe Zadka]

  This message is in MIME format.  The first part should be readable text,
  while the remaining parts are likely unreadable without MIME-aware tools.
  Send mail to mime@docserver.cac.washington.edu for more info.

---559023410-959030623-949689884=:4222
Content-Type: TEXT/PLAIN; charset=US-ASCII

I've tested both painfullness and time of my inline docs suggestion.
On a whim (with no relation to the doc-sig) I wrote a small generic dict
module. Then I decided to document it and see how much it puts me off. I
discovered that it was pretty easy. (This was with vi -- if you're using 
an editor that's less friendly it might be harder). 

I then decided to re-do fileinput.py's doc-string (it has only a module
level doc-string) in the new output.

I've discovered that most of my time was in filling out neccessary
information, rather then in markup technicalities.

Attached are the results of this test.
It rather suprised me, because it reminded me more of writing LaTeX then
writing HTML or XML: I did both pretty heavily be hand, and LaTeX writing
is much easier.

I have a small request: would anyone be willing to take a doc-string'ed
module a redo it in my suggested syntax and return to tell us of the
experience? (See, Randy got to me too)


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

---559023410-959030623-949689884=:4222
Content-Type: TEXT/PLAIN; charset=US-ASCII; name="fileinput.py"
Content-ID: <Pine.SOL.3.96.1000204204444.4222B@sundial>
Content-Description: 
Content-Transfer-Encoding: BASE64

IiIiSGVscGVyIGNsYXNzIHRvIHF1aWNrbHkgd3JpdGUgYSBsb29wIG92ZXIg
YWxsIHN0YW5kYXJkIGlucHV0IGZpbGVzLg0KDQpUeXBpY2FsIHVzZSBpczoN
Cg0KICAgIGV4YW1wbGU6Og0KICAgICAgICBpbXBvcnQgZmlsZWlucHV0DQog
ICAgICAgIGZvciBsaW5lIGluIGZpbGVpbnB1dC5pbnB1dCgpOg0KICAgICAg
ICAgICAgcHJvY2VzcyhsaW5lKQ0KDQpUaGlzIGl0ZXJhdGVzIG92ZXIgdGhl
IGxpbmVzIG9mIGFsbCBmaWxlcyBsaXN0ZWQgaW4gW3N5cy5hcmd2WzE6XV0s
DQpkZWZhdWx0aW5nIHRvIFt2YXIgc3lzLnN0ZGluXSBpZiB0aGUgbGlzdCBp
cyBlbXB0eS4gIElmIGEgZmlsZW5hbWUgaXMgDQpbY29kZSAnLSddIGl0IGlz
IGFsc28gcmVwbGFjZWQgYnkgW2NvZGUgc3lzLnN0ZGluXS4gIFRvIHNwZWNp
ZnkgYW4gYWx0ZXJuYXRpdmUgDQpsaXN0IG9mIGZpbGVuYW1lcywgcGFzcyBp
dCBhcyB0aGUgYXJndW1lbnQgdG8gW2Z1bmN0aW9uIGlucHV0KCldLiAgQSBz
aW5nbGUgDQpmaWxlIG5hbWUgaXMgYWxzbyBhbGxvd2VkLg0KDQpGdW5jdGlv
bnMgW2Z1bmN0aW9uIGZpbGVuYW1lKCldLCBbZnVuY3Rpb24gbGluZW5vKCld
IHJldHVybiB0aGUgZmlsZW5hbWUgYW5kIA0KY3VtdWxhdGl2ZSBsaW5lIG51
bWJlciBvZiB0aGUgbGluZSB0aGF0IGhhcyBqdXN0IGJlZW4gcmVhZDsgDQpb
ZnVuY3Rpb24gZmlsZWxpbmVubygpXSByZXR1cm5zIGl0cyBsaW5lIG51bWJl
ciBpbiB0aGUgY3VycmVudCBmaWxlOyANCltmdW5jdGlvbiBpc2ZpcnN0bGlu
ZSgpXSByZXR1cm5zIHRydWUgaWZmIHRoZSBsaW5lIGp1c3QgcmVhZCBpcyB0
aGUgZmlyc3QgbGluZSANCm9mIGl0cyBmaWxlOyBbZnVuY3Rpb24gaXNzdGRp
bigpXSByZXR1cm5zIHRydWUgaWZmIHRoZSBsaW5lIHdhcyByZWFkIGZyb20g
DQpbdmFyIHN5cy5zdGRpbl0uICBGdW5jdGlvbiBbZnVuY3Rpb24gbmV4dGZp
bGUoKV0gY2xvc2VzIHRoZQ0KY3VycmVudCBmaWxlIHNvIHRoYXQgdGhlIG5l
eHQgaXRlcmF0aW9uIHdpbGwgcmVhZCB0aGUgZmlyc3QgbGluZSBmcm9tDQp0
aGUgbmV4dCBmaWxlIChpZiBhbnkpOyBsaW5lcyBub3QgcmVhZCBmcm9tIHRo
ZSBmaWxlIHdpbGwgbm90IGNvdW50DQp0b3dhcmRzIHRoZSBjdW11bGF0aXZl
IGxpbmUgY291bnQ7IHRoZSBmaWxlbmFtZSBpcyBub3QgY2hhbmdlZCB1bnRp
bA0KYWZ0ZXIgdGhlIGZpcnN0IGxpbmUgb2YgdGhlIG5leHQgZmlsZSBoYXMg
YmVlbiByZWFkLiAgRnVuY3Rpb24gDQpbZnVuY3Rpb24gY2xvc2UoKV0gY2xv
c2VzIHRoZSBzZXF1ZW5jZS4NCg0KQmVmb3JlIGFueSBsaW5lcyBoYXZlIGJl
ZW4gcmVhZCwgW2Z1bmN0aW9uIGZpbGVuYW1lKCldIHJldHVybnMgW3ZhciBO
b25lXSBhbmQgDQpib3RoIGxpbmUgbnVtYmVycyBhcmUgemVybzsgW2Z1bmN0
aW9uIG5leHRmaWxlKCldIGhhcyBubyBlZmZlY3QuICBBZnRlciBhbGwgDQps
aW5lcyBoYXZlIGJlZW4gcmVhZCwgW2Z1bmN0aW9uIGZpbGVuYW1lKCldIGFu
ZCB0aGUgbGluZSBudW1iZXIgZnVuY3Rpb25zIA0KcmV0dXJuIHRoZSB2YWx1
ZXMgcGVydGFpbmluZyB0byB0aGUgbGFzdCBsaW5lIHJlYWQ7IFtmdW5jdGlv
biBuZXh0ZmlsZSgpXSBoYXMgDQpubyBlZmZlY3QuDQoNCkFsbCBmaWxlcyBh
cmUgb3BlbmVkIGluIHRleHQgbW9kZS4gIElmIGFuIEkvTyBlcnJvciBvY2N1
cnMgZHVyaW5nDQpvcGVuaW5nIG9yIHJlYWRpbmcgYSBmaWxlLCB0aGUgW2V4
Y2VwdGlvbiBJT0Vycm9yXSBleGNlcHRpb24gaXMgcmFpc2VkLg0KDQpJZiBb
dmFyIHN5cy5zdGRpbl0gaXMgdXNlZCBtb3JlIHRoYW4gb25jZSwgdGhlIHNl
Y29uZCBhbmQgZnVydGhlciB1c2Ugd2lsbA0KcmV0dXJuIG5vIGxpbmVzLCBl
eGNlcHQgcGVyaGFwcyBmb3IgaW50ZXJhY3RpdmUgdXNlLCBvciBpZiBpdCBo
YXMgYmVlbg0KZXhwbGljaXRseSByZXNldCAoZS5nLiB1c2luZyBbY29kZSBz
eXMuc3RkaW4uc2VlaygwKSldLg0KDQpFbXB0eSBmaWxlcyBhcmUgb3BlbmVk
IGFuZCBpbW1lZGlhdGVseSBjbG9zZWQ7IHRoZSBvbmx5IHRpbWUgdGhlaXIN
CnByZXNlbmNlIGluIHRoZSBsaXN0IG9mIGZpbGVuYW1lcyBpcyBub3RpY2Vh
YmxlIGF0IGFsbCBpcyB3aGVuIHRoZQ0KbGFzdCBmaWxlIG9wZW5lZCBpcyBl
bXB0eS4NCg0KSXQgaXMgcG9zc2libGUgdGhhdCB0aGUgbGFzdCBsaW5lIG9m
IGEgZmlsZSBkb2Vzbid0IGVuZCBpbiBhIG5ld2xpbmUNCmNoYXJhY3Rlcjsg
b3RoZXJ3aXNlIGxpbmVzIGFyZSByZXR1cm5lZCBpbmNsdWRpbmcgdGhlIHRy
YWlsaW5nDQpuZXdsaW5lLg0KDQpDbGFzcyBbY2xhc3MgRmlsZUlucHV0XSBp
cyB0aGUgaW1wbGVtZW50YXRpb247IGl0cyBtZXRob2RzIA0KW2Z1bmN0aW9u
IGZpbGVuYW1lKCldLCBbZnVuY3Rpb24gbGluZW5vKCldLCBbZnVuY3Rpb24g
ZmlsZWxpbmUoKV0sIA0KW2Z1bmN0aW9uIGlzZmlyc3RsaW5lKCldLCBbZnVu
Y3Rpb24gaXNzdGRpbigpXSwgW2Z1bmN0aW9uIG5leHRmaWxlKCldIGFuZCAN
CltmdW5jdGlvbiBjbG9zZSgpXSBjb3JyZXNwb25kIHRvIHRoZSBmdW5jdGlv
bnMgaW4gdGhlIG1vZHVsZS4gIEluIGFkZGl0aW9uIGl0IA0KaGFzIGEgW2Z1
bmN0aW9uIHJlYWRsaW5lKCldIG1ldGhvZCB3aGljaCByZXR1cm5zIHRoZSBu
ZXh0IGlucHV0IGxpbmUsIGFuZCBhDQpbZnVuY3Rpb24gX19nZXRpdGVtX18o
KV0gbWV0aG9kIHdoaWNoIGltcGxlbWVudHMgdGhlIHNlcXVlbmNlIGJlaGF2
aW9yLiAgVGhlDQpzZXF1ZW5jZSBtdXN0IGJlIGFjY2Vzc2VkIGluIHN0cmlj
dGx5IHNlcXVlbnRpYWwgb3JkZXI7IHNlcXVlbmNlDQphY2Nlc3MgYW5kIFtm
dW5jdGlvbiByZWFkbGluZSgpXSBjYW5ub3QgYmUgbWl4ZWQuDQoNCk9wdGlv
bmFsIGluLXBsYWNlIGZpbHRlcmluZzogaWYgdGhlIGtleXdvcmQgYXJndW1l
bnQgW3ZhciBpbnBsYWNlXSBpcyBwYXNzZWQNCnRvIFtmdW5jdGlvbiBpbnB1
dCgpXSB3aXRoIGEgdHJ1ZSB2YWx1ZSBvciB0byB0aGUgW2NsYXNzIEZpbGVJ
bnB1dF0gDQpjb25zdHJ1Y3RvciwgdGhlIGZpbGUgaXMgbW92ZWQgdG8gYSBi
YWNrdXAgZmlsZSBhbmQgc3RhbmRhcmQgb3V0cHV0IGlzIA0KZGlyZWN0ZWQg
dG8gdGhlIGlucHV0IGZpbGUuICBUaGlzIG1ha2VzIGl0IHBvc3NpYmxlIHRv
IHdyaXRlIGEgZmlsdGVyIHRoYXQgDQpyZXdyaXRlcyBpdHMgaW5wdXQgZmls
ZSBpbiBwbGFjZS4gIElmIHRoZSBrZXl3b3JkIGFyZ3VtZW50IFt2YXIgYmFj
a3VwXSBpcyANCnBhc3NlZCB0byBbZnVuY3Rpb24gaW5wdXQoKV0gb3IgdG8g
dGhlIGNvbnN0cnVjdG9yIG9mIFtjbGFzcyBGaWxlSW5wdXRdLA0KaXQgaXMg
dHJlYXRlZCBhcyB0aGUgZXh0ZW5zaW9uIGZvciB0aGUgYmFja3VwIGZpbGUs
IGFuZCB0aGUgYmFja3VwDQpmaWxlIHJlbWFpbnMgYXJvdW5kOyBieSBkZWZh
dWx0LCB0aGUgZXh0ZW5zaW9uIGlzIFtjb2RlICIuYmFrIl0gYW5kIGl0IGlz
DQpkZWxldGVkIHdoZW4gdGhlIG91dHB1dCBmaWxlIGlzIGNsb3NlZC4gIElu
LXBsYWNlIGZpbHRlcmluZyBpcw0KZGlzYWJsZWQgd2hlbiBzdGFuZGFyZCBp
bnB1dCBpcyByZWFkLiAgWFhYIFRoZSBjdXJyZW50IGltcGxlbWVudGF0aW9u
DQpkb2VzIG5vdCB3b3JrIGZvciBNUy1ET1MgOCszIGZpbGVzeXN0ZW1zLg0K
DQpYWFggUG9zc2libGUgYWRkaXRpb25zOg0KDQpsaXN0OjoNCiAgICBpdGVt
Ojogb3B0aW9uYWwgW21vZHVsZSBnZXRvcHRdIGFyZ3VtZW50IHByb2Nlc3Np
bmcNCiAgICBpdGVtOjogc3BlY2lmeSBvcGVuIG1vZGUgKFtjb2RlICdyJ10g
b3IgW2NvZGUgJ3JiJ10pDQogICAgaXRlbTo6IHNwZWNpZnkgYnVmZmVyIHNp
emUNCiAgICBpdGVtOjogW2Z1bmN0aW9uIGZpbGVubygpXQ0KICAgIGl0ZW06
OiBbZnVuY3Rpb24gaXNhdHR5KCldDQogICAgaXRlbTo6IFtmdW5jdGlvbiBy
ZWFkKCldLCBbZnVuY3Rpb24gcmVhZChzaXplKV0sIGV2ZW4gW2Z1bmN0aW9u
IHJlYWRsaW5lcygpXQ0KIiIiDQo=
---559023410-959030623-949689884=:4222
Content-Type: TEXT/PLAIN; charset=US-ASCII; name="GeneralDict.py"
Content-ID: <Pine.SOL.3.96.1000204204444.4222C@sundial>
Content-Description: 
Content-Transfer-Encoding: BASE64

Y2xhc3MgR2VuZXJhbERpY3Q6DQoNCgknJydcDQoJQSBkaWN0aW9uYXJ5IHdo
aWNoIGNhbiBiZSBpbmRleGVkIGJ5IGFueSB0eXBlLCBpbmNsdWRpbmcgbXV0
YWJsZSB0eXBlcy4gDQoNCglUaGlzIGNsYXNzIGltcGxlbWVudHMgYSBkaWN0
aW9uYXJ5IHdoaWNoIGNhbiBiZSBpbmRleGVkIGJ5IGFueSB0eXBlLA0KCWlu
Y2x1ZGluZyBtdXRhYmxlcyBsaWtlIGxpc3RzIGFuZCBkaWN0aW9uYXJpZXMu
IA0KCScnJw0KCQ0KDQoJZGVmIF9faW5pdF9fKHNlbGYpOg0KCQlzZWxmLl9k
aWN0PXt9DQoJCXNlbGYuX3RlbXBfa2V5cz17fQ0KDQoJZGVmIF9fZ2V0aXRl
bV9fKHNlbGYsIG5hbWUpOg0KCQknJydcDQoJCWdldCBhbiBpdGVtIGJ5IG5h
bWUuDQoNCgkJW2VtcGggY2F2ZWF0XTogaWYgW3ZhciBuYW1lXSBpcyBtdXRh
YmxlLCB0aGVuIG9iamVjdA0KCQllcXVhbGl0eSBhbW9uZyBrZXlzIGlzIG5v
dCBlbm91Z2guIEluIG90aGVyIHdvcmRzLA0KCQlleGFtcGxlOjoNCgkJCT4+
PiBhID0gR2VuZXJhbERpY3QoKQ0KCQkJPj4+IGFbWzEsMiwzXV09MQ0KCQkJ
Pj4+IHRyeToNCgkJCS4uLiAgICAgYVtbMSwyLDNdXQ0KCQkJLi4uIGV4Y2Vw
dCBLZXlFcnJvcjoNCgkJCS4uLiAgICAgcHJpbnQgIkNhdmVhdCEiDQoJCQku
Li4gDQoJCQlDYXZlYXQhDQoNCgkJYXJnIG5hbWU9bmFtZTo6DQoJCQl0aGUg
bmFtZSB0byBsb29rdXAgaW4gdGhlIGRpY3Rpb25hcnkNCgkJJycnDQoJCXRy
eToNCgkJCWhhc2gobmFtZSkNCgkJZXhjZXB0IFR5cGVFcnJvcjoNCgkJCXJl
dHVybiBzZWxmLl9kaWN0W2lkKG5hbWUpXQ0KCQllbHNlOg0KCQkJcmV0dXJu
IHNlbGYuX2RpY3RbMSwgbmFtZV0NCg0KCWRlZiBfX3NldGl0ZW1fXyhzZWxm
LCBuYW1lLCB2YWx1ZSk6DQoJCScnJ1wNCgkJc2V0IGEgbmFtZS92YWx1ZSBt
YXBwaW5nDQoNCgkJYXJnIG5hbWU9bmFtZTo6DQoJCQl0aGUgbmFtZSB0byBh
c3NvY2lhdGUgYSB2YWx1ZSB3aXRoLg0KDQoJCWFyZyBuYW1lPXZhbHVlOjoN
CgkJCXRoZSB2YWx1ZSB0byBhc3NvY2lhdGUgd2l0aCB0aGUgbmFtZQ0KCQkn
JycNCgkJdHJ5Og0KCQkJc2VsZi5fZGljdFsxLCBuYW1lXT12YWx1ZQ0KCQll
eGNlcHQgVHlwZUVycm9yOg0KCQkJIyBrZWVwIGEgcmVmZXJlbmNlIHRvICdu
YW1lJw0KCQkJc2VsZi5fdGVtcF9rZXlzW2lkKG5hbWUpXT1uYW1lIA0KCQkJ
c2VsZi5fZGljdFtpZChuYW1lKV09dmFsdWUNCg0KCWRlZiBfX2RlbGl0ZW1f
XyhzZWxmLCBuYW1lKToNCgkJJycnXA0KCQlkZWxldGUgYW4gYXNzb2NpYXRp
b24gZnJvbSB0aGUgbWFwcGluZy4NCg0KCQlhcmcgbmFtZT1uYW1lOjoNCgkJ
CXRoZSBuYW1lIHRvIGRlbGV0ZSB0aGUgYXNzb2NpYXRpb24gdG8uDQoJCScn
Jw0KCQkjIEknZCByYXRoZXIgZXhwbGljaXRseSB0ZXN0IGZvciBoYXNoLCBi
ZWNhdXNlDQoJCSMgb3RoZXJ3aXNlIHRoZSBleGNlcHRpb25zIGdldCBtaXhl
ZA0KCQl0cnk6DQoJCQloYXNoKG5hbWUpDQoJCWV4Y2VwdCBUeXBlRXJyb3I6
DQoJCQlkZWwgc2VsZi5fZGljdFtpZChuYW1lKV0NCgkJCWRlbCBzZWxmLl90
ZW1wX2tleXNbaWQobmFtZSldDQoJCWVsc2U6DQoJCQlkZWwgc2VsZi5fZGlj
dFsxLCBuYW1lXQ0KDQoJZGVmIGtleXMoc2VsZik6DQoJCScnJ3JldHVybiBh
IGxpc3Qgb2YgYWxsIGtleXMgaW4gdGhlIG1hcHBpbmcnJycNCgkJcmV0ID0g
W10NCgkJZm9yIGsgaW4gc2VsZi5fZGljdC5rZXlzKCk6DQoJCQlpZiB0eXBl
KGspIGlzIHR5cGUoKCkpOg0KCQkJCXJldC5hcHBlbmQoa1sxXSkNCgkJCWVs
c2U6DQoJCQkJcmV0LmFwcGVuZChzZWxmLl90ZW1wX2tleXNba10pDQoJCXJl
dHVybiByZXQNCg0KDQpkZWYgX3Rlc3QoKToNCglhPUdlbmVyYWxEaWN0KCkN
CglhWyBbMSwgMiwgM10gXSA9IDENCglzZXEgPSBrID0gYS5rZXlzKClbMF0N
Cglhc3NlcnQgYVtrXSA9PSAxDQoJYVsgMiBdID0gNg0KCWZvciBrIGluIGEu
a2V5cygpOg0KCQlpZiBrID09IDI6DQoJCQlhc3NlcnQgYVtrXSA9PSA2DQoJ
CWlmIGsgPT0gWzEsIDIsIDNdOg0KCQkJYXNzZXJ0IGFba10gPT0gMQ0KCWRl
bCBhW3NlcV0NCglhc3NlcnQgbGVuKGEua2V5cygpKSA9PSAxDQoJYXNzZXJ0
IGFbYS5rZXlzKClbMF1dID09IDYNCg0KaWYgX19uYW1lX18gPT0gJ19fbWFp
bl9fJzogDQoJX3Rlc3QoKQ0K
---559023410-959030623-949689884=:4222--