----boundary-LibPST-iamunique-1635710201_-_-
Content-type: text/plain
Hi,
>It is an important requirement that good documentation should be up to
>date to be of practical value. This was illustrated by the Reiser's book,
>unfortunately to the Oberon System's peril.
this is quite true. Trying to document the university Oberon system, and
Bluebottle, would be like trying to catch wild geese. However, Blackbox/CP
is more static and was/is intended to be a commercial offering.
I take your point about the out-of-date content of Reiser's book;
nevertheless, the overall structure is good, and I found it very usable when
I first became interested in Oberon. I also prefer his format for module
documentation to that used in BB/CP. Reiser starts by providing an overview,
lists the services offered by the module, then gives some definitions
related to each module, before he shows the module's interface After that he
discusses each type, procedure and so on in detail. Compare this with the
BB/CP format where the document opens with the definition, which can be
quite intimidating, and rarely provides the same quality of overview or
detail. This, I should think, is the result of commerical pressures that do
not apply in the university. I am subject to similar pressures, and my own
standard of documentation suffers.
Regards,
Bob
_________________________________________________________________
Hotmail messages direct to your mobile phone
http://www.msn.co.uk/msnmobile
--------------------------------------------
To unsubscribe from this mailing list, send a message containing the word "unsubscribe" to:
blackbox-request{([at]})nowhere.xy
To get a list of valid e-mail commands and instructions on their usage, send a message containing the word "help" to the above address.
Send any problem reports or questions related to this email list to the list owner at
owner-blackbox{([at]})nowhere.xy
Current posting policy:
a) To post you should use the same address by which you are subscribed to the mailing list. That way, the list server will recognize you as subscriber and forward your posting immediately, without creating any overhead.
b) If, for some reason, you cannot post from the address, by which you are subscribed, your message will be moderated to avoid spam. Please understand that moderation will often cause some delay, in particular over weekends or holydays.
----boundary-LibPST-iamunique-1635710201_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIEhpLFxwYXINClxwYXINCj5JdCBpcyBhbiBpbXBv
cnRhbnQgcmVxdWlyZW1lbnQgdGhhdCBnb29kIGRvY3VtZW50YXRpb24gc2hvdWxkIGJlIHVwIHRv
XHBhcg0KPmRhdGUgdG8gYmUgb2YgcHJhY3RpY2FsIHZhbHVlLiBUaGlzIHdhcyBpbGx1c3RyYXRl
ZCBieSB0aGUgUmVpc2VyJ3MgYm9vayxccGFyDQo+dW5mb3J0dW5hdGVseSB0byB0aGUgT2Jlcm9u
IFN5c3RlbSdzIHBlcmlsLlxwYXINClxwYXINCnRoaXMgaXMgcXVpdGUgdHJ1ZS4gVHJ5aW5nIHRv
IGRvY3VtZW50IHRoZSB1bml2ZXJzaXR5IE9iZXJvbiBzeXN0ZW0sIGFuZCBccGFyDQpCbHVlYm90
dGxlLCB3b3VsZCBiZSBsaWtlIHRyeWluZyB0byBjYXRjaCB3aWxkIGdlZXNlLiBIb3dldmVyLCBC
bGFja2JveC9DUCBccGFyDQppcyBtb3JlIHN0YXRpYyBhbmQgd2FzL2lzIGludGVuZGVkIHRvIGJl
IGEgY29tbWVyY2lhbCBvZmZlcmluZy5ccGFyDQpccGFyDQpJIHRha2UgeW91ciBwb2ludCBhYm91
dCB0aGUgb3V0LW9mLWRhdGUgY29udGVudCBvZiBSZWlzZXIncyBib29rOyBccGFyDQpuZXZlcnRo
ZWxlc3MsIHRoZSBvdmVyYWxsIHN0cnVjdHVyZSBpcyBnb29kLCBhbmQgSSBmb3VuZCBpdCB2ZXJ5
IHVzYWJsZSB3aGVuIFxwYXINCkkgZmlyc3QgYmVjYW1lIGludGVyZXN0ZWQgaW4gT2Jlcm9uLiBJ
IGFsc28gcHJlZmVyIGhpcyBmb3JtYXQgZm9yIG1vZHVsZSBccGFyDQpkb2N1bWVudGF0aW9uIHRv
IHRoYXQgdXNlZCBpbiBCQi9DUC4gUmVpc2VyIHN0YXJ0cyBieSBwcm92aWRpbmcgYW4gb3ZlcnZp
ZXcsIFxwYXINCmxpc3RzIHRoZSBzZXJ2aWNlcyBvZmZlcmVkIGJ5IHRoZSBtb2R1bGUsIHRoZW4g
Z2l2ZXMgc29tZSBkZWZpbml0aW9ucyBccGFyDQpyZWxhdGVkIHRvIGVhY2ggbW9kdWxlLCBiZWZv
cmUgaGUgc2hvd3MgdGhlIG1vZHVsZSdzIGludGVyZmFjZSBBZnRlciB0aGF0IGhlIFxwYXINCmRp
c2N1c3NlcyBlYWNoIHR5cGUsIHByb2NlZHVyZSBhbmQgc28gb24gaW4gZGV0YWlsLiBDb21wYXJl
IHRoaXMgd2l0aCB0aGUgXHBhcg0KQkIvQ1AgZm9ybWF0IHdoZXJlIHRoZSBkb2N1bWVudCBvcGVu
cyB3aXRoIHRoZSBkZWZpbml0aW9uLCB3aGljaCBjYW4gYmUgXHBhcg0KcXVpdGUgaW50aW1pZGF0
aW5nLCBhbmQgcmFyZWx5IHByb3ZpZGVzIHRoZSBzYW1lIHF1YWxpdHkgb2Ygb3ZlcnZpZXcgb3Ig
XHBhcg0KZGV0YWlsLiBUaGlzLCBJIHNob3VsZCB0aGluaywgaXMgdGhlIHJlc3VsdCBvZiBjb21t
ZXJpY2FsIHByZXNzdXJlcyB0aGF0IGRvIFxwYXINCm5vdCBhcHBseSBpbiB0aGUgdW5pdmVyc2l0
eS4gSSBhbSBzdWJqZWN0IHRvIHNpbWlsYXIgcHJlc3N1cmVzLCBhbmQgbXkgb3duIFxwYXINCnN0
YW5kYXJkIG9mIGRvY3VtZW50YXRpb24gc3VmZmVycy5ccGFyDQpccGFyDQpSZWdhcmRzLFxwYXIN
ClxwYXINCkJvYlxwYXINClxwYXINCl9fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19fX19f
X19fX19fX19fX19fX19fX19fX19fX19fX19fX19fXHBhcg0KSG90bWFpbCBtZXNzYWdlcyBkaXJl
Y3QgdG8geW91ciBtb2JpbGUgcGhvbmUgaHR0cDovL3d3dy5tc24uY28udWsvbXNubW9iaWxlXHBh
cg0KXHBhcg0KLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS1ccGFy
DQpccGFyDQpUbyB1bnN1YnNjcmliZSBmcm9tIHRoaXMgbWFpbGluZyBsaXN0LCBzZW5kIGEgbWVz
c2FnZSBjb250YWluaW5nIHRoZSB3b3JkICJ1bnN1YnNjcmliZSIgdG86XHBhcg0KICAgYmxhY2ti
b3gtcmVxdWVzdEBvYmVyb24uY2hccGFyDQpccGFyDQpUbyBnZXQgYSBsaXN0IG9mIHZhbGlkIGUt
bWFpbCBjb21tYW5kcyBhbmQgaW5zdHJ1Y3Rpb25zIG9uIHRoZWlyIHVzYWdlLCBzZW5kIGEgbWVz
c2FnZSBjb250YWluaW5nIHRoZSB3b3JkICJoZWxwIiB0byB0aGUgYWJvdmUgYWRkcmVzcy5ccGFy
DQpccGFyDQpTZW5kIGFueSBwcm9ibGVtIHJlcG9ydHMgb3IgcXVlc3Rpb25zIHJlbGF0ZWQgdG8g
dGhpcyBlbWFpbCBsaXN0IHRvIHRoZSBsaXN0IG93bmVyIGF0XHBhcg0KICAgb3duZXItYmxhY2ti
b3hAb2Jlcm9uLmNoXHBhcg0KXHBhcg0KQ3VycmVudCBwb3N0aW5nIHBvbGljeTpccGFyDQpccGFy
DQphKSBUbyBwb3N0IHlvdSBzaG91bGQgdXNlIHRoZSBzYW1lIGFkZHJlc3MgYnkgd2hpY2ggeW91
IGFyZSBzdWJzY3JpYmVkIHRvIHRoZSBtYWlsaW5nIGxpc3QuIFRoYXQgd2F5LCB0aGUgbGlzdCBz
ZXJ2ZXIgd2lsbCByZWNvZ25pemUgeW91IGFzIHN1YnNjcmliZXIgYW5kIGZvcndhcmQgeW91ciBw
b3N0aW5nIGltbWVkaWF0ZWx5LCB3aXRob3V0IGNyZWF0aW5nIGFueSBvdmVyaGVhZC5ccGFyDQpc
cGFyDQpiKSBJZiwgZm9yIHNvbWUgcmVhc29uLCB5b3UgY2Fubm90IHBvc3QgZnJvbSB0aGUgYWRk
cmVzcywgYnkgd2hpY2ggeW91IGFyZSBzdWJzY3JpYmVkLCB5b3VyIG1lc3NhZ2Ugd2lsbCBiZSBt
b2RlcmF0ZWQgdG8gYXZvaWQgc3BhbS4gUGxlYXNlIHVuZGVyc3RhbmQgdGhhdCBtb2RlcmF0aW9u
IHdpbGwgb2Z0ZW4gY2F1c2Ugc29tZSBkZWxheSwgaW4gcGFydGljdWxhciBvdmVyIHdlZWtlbmRz
IG9yIGhvbHlkYXlzfX0AKiEoUEjAYcIuwyg=
----boundary-LibPST-iamunique-1635710201_-_---
Received on Sun Aug 03 2003 - 23:10:52 UTC