----boundary-LibPST-iamunique-1922619930_-_-
Content-type: text/plain
On Sat, 2 Aug 2003, Douglas G. Danforth wrote:
> I am in the midst of reading the TextModels documentation since I wish
> to understand how [--]
Hmm. A short while ago I aired a similar comment to a more narrow audience
and you remember how I was disciplined by our leader Fyodor. Are you
not afraid of a similar reprimend?
> In general for the Blackbox documentation it is not possible to step
> into the middle of it and extract what one needs. One must absorb the
> whole in order to use a part. This is not an optimal use of one's time.
A similar opinion can be found in the draft book "Programming in BlackBox
Oberon" by Brett S. Hallett:
> This book is written from the perspective of a practicing programmer
> who while trying to develop programs in Blackbox Oberon, found a lack
> of useful developer information in the supplied documentation or the few
> other sources available. [----]
Brett also assessed the BlackBox "help" facility:
> However I will say that the supplied help facility is not very
> programmer friendly, it simply returns a index to every reference of
> words entered, while powerful in its own right, is not very useful
> when trying to find out how to call another GUI form, for example.
You also wrote:
> There must be some way that the Blackbox user community can help Ominc
> improve its documentation.
As far as I know Ominc are well aware of our opinions, and they have
decided not to invest their time into either BB documentation or
BB marketing as a product. Both issues are closely related. I therefore
do not think it is realistic to "help Ominc" doing something they
decided not to do. I think a more realistic programme is to step forward
and do something ourselves, time permitting. I find books by Stan Warford
and the draft book by Brett of immense help. Such projects are extremely
time consuming.
It is also possible to just start working on the current BB documentation
by expanding what is missing and cross-referencing it using StdLinks,
even without the new tools that you have proposed. This would run against
the copyright note, but if the resulting documents are better than the
original, it might be worth the violation. (It would be illegal, but not
immoral to improve the current docu in such a way.) It is however possible
that the result would not be good because of lack of insider knowledge
of the software. My favorite example is Meta: just look how incomplete
the Meta docu is. Would it be possible to improve this piece without access
to insider knowledge about Meta?
It seems to me that the user opinions about the current BB documentation
are converging. The question is what can be done about it without Ominc.
I found it very time consuming to write documentation similar to theirs,
let alone any expanded version. I am not sure I can afford any more
time. Can you?
Wojtek
--------------------------------------------
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-1922619930_-_-
Content-type: application/rtf
Content-transfer-encoding: base64
Content-Disposition: attachment; filename="rtf-body.rtf"
e1xydGYxXGFuc2lcYW5zaWNwZzEyNTJcZnJvbXRleHQgXGRlZmYwe1xmb250dGJsDQp7XGYwXGZz
d2lzcyBBcmlhbDt9DQp7XGYxXGZtb2Rlcm4gQ291cmllciBOZXc7fQ0Ke1xmMlxmbmlsXGZjaGFy
c2V0MiBTeW1ib2w7fQ0Ke1xmM1xmbW9kZXJuXGZjaGFyc2V0MCBDb3VyaWVyIE5ldzt9fQ0Ke1xj
b2xvcnRibFxyZWQwXGdyZWVuMFxibHVlMDtccmVkMFxncmVlbjBcYmx1ZTI1NTt9DQpcdWMxXHBh
cmRccGxhaW5cZGVmdGFiMzYwIFxmMFxmczIwIE9uIFNhdCwgMiBBdWcgMjAwMywgRG91Z2xhcyBH
LiBEYW5mb3J0aCB3cm90ZTpccGFyDQpccGFyDQo+IEkgYW0gaW4gdGhlIG1pZHN0IG9mIHJlYWRp
bmcgdGhlIFRleHRNb2RlbHMgZG9jdW1lbnRhdGlvbiBzaW5jZSBJIHdpc2hccGFyDQo+IHRvIHVu
ZGVyc3RhbmQgaG93IFstLV1ccGFyDQpccGFyDQpIbW0uIEEgc2hvcnQgd2hpbGUgYWdvIEkgYWly
ZWQgYSBzaW1pbGFyIGNvbW1lbnQgdG8gYSBtb3JlIG5hcnJvdyBhdWRpZW5jZVxwYXINCmFuZCB5
b3UgcmVtZW1iZXIgaG93IEkgd2FzIGRpc2NpcGxpbmVkIGJ5IG91ciBsZWFkZXIgRnlvZG9yLiBB
cmUgeW91XHBhcg0Kbm90IGFmcmFpZCBvZiBhIHNpbWlsYXIgcmVwcmltZW5kP1xwYXINClxwYXIN
Cj4gSW4gZ2VuZXJhbCBmb3IgdGhlIEJsYWNrYm94IGRvY3VtZW50YXRpb24gaXQgaXMgbm90IHBv
c3NpYmxlIHRvIHN0ZXBccGFyDQo+IGludG8gdGhlIG1pZGRsZSBvZiBpdCBhbmQgZXh0cmFjdCB3
aGF0IG9uZSBuZWVkcy4gIE9uZSBtdXN0IGFic29yYiB0aGVccGFyDQo+IHdob2xlIGluIG9yZGVy
IHRvIHVzZSBhIHBhcnQuICBUaGlzIGlzIG5vdCBhbiBvcHRpbWFsIHVzZSBvZiBvbmUncyB0aW1l
LlxwYXINClxwYXINCkEgc2ltaWxhciBvcGluaW9uIGNhbiBiZSBmb3VuZCBpbiB0aGUgZHJhZnQg
Ym9vayAiUHJvZ3JhbW1pbmcgaW4gQmxhY2tCb3hccGFyDQpPYmVyb24iIGJ5IEJyZXR0IFMuIEhh
bGxldHQ6XHBhcg0KXHBhcg0KPiBUaGlzIGJvb2sgaXMgd3JpdHRlbiBmcm9tIHRoZSBwZXJzcGVj
dGl2ZSBvZiBhIHByYWN0aWNpbmcgcHJvZ3JhbW1lclxwYXINCj4gd2hvIHdoaWxlIHRyeWluZyB0
byBkZXZlbG9wIHByb2dyYW1zIGluIEJsYWNrYm94IE9iZXJvbiwgZm91bmQgYSBsYWNrXHBhcg0K
PiBvZiB1c2VmdWwgZGV2ZWxvcGVyIGluZm9ybWF0aW9uIGluIHRoZSBzdXBwbGllZCBkb2N1bWVu
dGF0aW9uIG9yIHRoZSBmZXdccGFyDQo+IG90aGVyIHNvdXJjZXMgYXZhaWxhYmxlLiBbLS0tLV1c
cGFyDQpccGFyDQpCcmV0dCBhbHNvIGFzc2Vzc2VkIHRoZSBCbGFja0JveCAiaGVscCIgZmFjaWxp
dHk6XHBhcg0KXHBhcg0KPiBIb3dldmVyIEkgd2lsbCBzYXkgdGhhdCB0aGUgc3VwcGxpZWQgaGVs
cCBmYWNpbGl0eSBpcyBub3QgdmVyeVxwYXINCj4gcHJvZ3JhbW1lciBmcmllbmRseSwgaXQgc2lt
cGx5IHJldHVybnMgYSBpbmRleCB0byBldmVyeSByZWZlcmVuY2Ugb2ZccGFyDQo+IHdvcmRzIGVu
dGVyZWQsIHdoaWxlIHBvd2VyZnVsIGluIGl0cyBvd24gcmlnaHQsIGlzIG5vdCB2ZXJ5IHVzZWZ1
bFxwYXINCj4gd2hlbiB0cnlpbmcgdG8gZmluZCBvdXQgaG93IHRvIGNhbGwgYW5vdGhlciBHVUkg
Zm9ybSwgZm9yIGV4YW1wbGUuXHBhcg0KXHBhcg0KWW91IGFsc28gd3JvdGU6XHBhcg0KXHBhcg0K
PiBUaGVyZSBtdXN0IGJlIHNvbWUgd2F5IHRoYXQgdGhlIEJsYWNrYm94IHVzZXIgY29tbXVuaXR5
IGNhbiBoZWxwIE9taW5jXHBhcg0KPiBpbXByb3ZlIGl0cyBkb2N1bWVudGF0aW9uLlxwYXINClxw
YXINCkFzIGZhciBhcyBJIGtub3cgT21pbmMgYXJlIHdlbGwgYXdhcmUgb2Ygb3VyIG9waW5pb25z
LCBhbmQgdGhleSBoYXZlXHBhcg0KZGVjaWRlZCBub3QgdG8gaW52ZXN0IHRoZWlyIHRpbWUgaW50
byBlaXRoZXIgQkIgZG9jdW1lbnRhdGlvbiBvclxwYXINCkJCIG1hcmtldGluZyBhcyBhIHByb2R1
Y3QuIEJvdGggaXNzdWVzIGFyZSBjbG9zZWx5IHJlbGF0ZWQuIEkgdGhlcmVmb3JlXHBhcg0KZG8g
bm90IHRoaW5rIGl0IGlzIHJlYWxpc3RpYyB0byAiaGVscCBPbWluYyIgZG9pbmcgc29tZXRoaW5n
IHRoZXlccGFyDQpkZWNpZGVkIG5vdCB0byBkby4gSSB0aGluayBhIG1vcmUgcmVhbGlzdGljIHBy
b2dyYW1tZSBpcyB0byBzdGVwIGZvcndhcmRccGFyDQphbmQgZG8gc29tZXRoaW5nIG91cnNlbHZl
cywgdGltZSBwZXJtaXR0aW5nLiBJIGZpbmQgYm9va3MgYnkgU3RhbiBXYXJmb3JkXHBhcg0KYW5k
IHRoZSBkcmFmdCBib29rIGJ5IEJyZXR0IG9mIGltbWVuc2UgaGVscC4gU3VjaCBwcm9qZWN0cyBh
cmUgZXh0cmVtZWx5XHBhcg0KdGltZSBjb25zdW1pbmcuXHBhcg0KXHBhcg0KSXQgaXMgYWxzbyBw
b3NzaWJsZSB0byBqdXN0IHN0YXJ0IHdvcmtpbmcgb24gdGhlIGN1cnJlbnQgQkIgZG9jdW1lbnRh
dGlvblxwYXINCmJ5IGV4cGFuZGluZyB3aGF0IGlzIG1pc3NpbmcgYW5kIGNyb3NzLXJlZmVyZW5j
aW5nIGl0IHVzaW5nIFN0ZExpbmtzLFxwYXINCmV2ZW4gd2l0aG91dCB0aGUgbmV3IHRvb2xzIHRo
YXQgeW91IGhhdmUgcHJvcG9zZWQuIFRoaXMgd291bGQgcnVuIGFnYWluc3RccGFyDQp0aGUgY29w
eXJpZ2h0IG5vdGUsIGJ1dCBpZiB0aGUgcmVzdWx0aW5nIGRvY3VtZW50cyBhcmUgYmV0dGVyIHRo
YW4gdGhlXHBhcg0Kb3JpZ2luYWwsIGl0IG1pZ2h0IGJlIHdvcnRoIHRoZSB2aW9sYXRpb24uIChJ
dCB3b3VsZCBiZSBpbGxlZ2FsLCBidXQgbm90XHBhcg0KaW1tb3JhbCB0byBpbXByb3ZlIHRoZSBj
dXJyZW50IGRvY3UgaW4gc3VjaCBhIHdheS4pIEl0IGlzIGhvd2V2ZXIgcG9zc2libGVccGFyDQp0
aGF0IHRoZSByZXN1bHQgd291bGQgbm90IGJlIGdvb2QgYmVjYXVzZSBvZiBsYWNrIG9mIGluc2lk
ZXIga25vd2xlZGdlXHBhcg0Kb2YgdGhlIHNvZnR3YXJlLiBNeSBmYXZvcml0ZSBleGFtcGxlIGlz
IE1ldGE6IGp1c3QgbG9vayBob3cgaW5jb21wbGV0ZVxwYXINCnRoZSBNZXRhIGRvY3UgaXMuIFdv
dWxkIGl0IGJlIHBvc3NpYmxlIHRvIGltcHJvdmUgdGhpcyBwaWVjZSB3aXRob3V0IGFjY2Vzc1xw
YXINCnRvIGluc2lkZXIga25vd2xlZGdlIGFib3V0IE1ldGE/XHBhcg0KXHBhcg0KSXQgc2VlbXMg
dG8gbWUgdGhhdCB0aGUgdXNlciBvcGluaW9ucyBhYm91dCB0aGUgY3VycmVudCBCQiBkb2N1bWVu
dGF0aW9uXHBhcg0KYXJlIGNvbnZlcmdpbmcuIFRoZSBxdWVzdGlvbiBpcyB3aGF0IGNhbiBiZSBk
b25lIGFib3V0IGl0IHdpdGhvdXQgT21pbmMuXHBhcg0KSSBmb3VuZCBpdCB2ZXJ5IHRpbWUgY29u
c3VtaW5nIHRvIHdyaXRlIGRvY3VtZW50YXRpb24gc2ltaWxhciB0byB0aGVpcnMsXHBhcg0KbGV0
IGFsb25lIGFueSBleHBhbmRlZCB2ZXJzaW9uLiBJIGFtIG5vdCBzdXJlIEkgY2FuIGFmZm9yZCBh
bnkgbW9yZVxwYXINCnRpbWUuIENhbiB5b3U/XHBhcg0KXHBhcg0KV29qdGVrXHBhcg0KXHBhcg0K
XHBhcg0KLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS0tLS1ccGFyDQpc
cGFyDQpUbyB1bnN1YnNjcmliZSBmcm9tIHRoaXMgbWFpbGluZyBsaXN0LCBzZW5kIGEgbWVzc2Fn
ZSBjb250YWluaW5nIHRoZSB3b3JkICJ1bnN1YnNjcmliZSIgdG86XHBhcg0KICAgYmxhY2tib3gt
cmVxdWVzdEBvYmVyb24uY2hccGFyDQpccGFyDQpUbyBnZXQgYSBsaXN0IG9mIHZhbGlkIGUtbWFp
bCBjb21tYW5kcyBhbmQgaW5zdHJ1Y3Rpb25zIG9uIHRoZWlyIHVzYWdlLCBzZW5kIGEgbWVzc2Fn
ZSBjb250YWluaW5nIHRoZSB3b3JkICJoZWxwIiB0byB0aGUgYWJvdmUgYWRkcmVzcy5ccGFyDQpc
cGFyDQpTZW5kIGFueSBwcm9ibGVtIHJlcG9ydHMgb3IgcXVlc3Rpb25zIHJlbGF0ZWQgdG8gdGhp
cyBlbWFpbCBsaXN0IHRvIHRoZSBsaXN0IG93bmVyIGF0XHBhcg0KICAgb3duZXItYmxhY2tib3hA
b2Jlcm9uLmNoXHBhcg0KXHBhcg0KQ3VycmVudCBwb3N0aW5nIHBvbGljeTpccGFyDQpccGFyDQph
KSBUbyBwb3N0IHlvdSBzaG91bGQgdXNlIHRoZSBzYW1lIGFkZHJlc3MgYnkgd2hpY2ggeW91IGFy
ZSBzdWJzY3JpYmVkIHRvIHRoZSBtYWlsaW5nIGxpc3QuIFRoYXQgd2F5LCB0aGUgbGlzdCBzZXJ2
ZXIgd2lsbCByZWNvZ25pemUgeW91IGFzIHN1YnNjcmliZXIgYW5kIGZvcndhcmQgeW91ciBwb3N0
aW5nIGltbWVkaWF0ZWx5LCB3aXRob3V0IGNyZWF0aW5nIGFueSBvdmVyaGVhZC5ccGFyDQpccGFy
DQpiKSBJZiwgZm9yIHNvbWUgcmVhc29uLCB5b3UgY2Fubm90IHBvc3QgZnJvbSB0aGUgYWRkcmVz
cywgYnkgd2hpY2ggeW91IGFyZSBzdWJzY3JpYmVkLCB5b3VyIG1lc3NhZ2Ugd2lsbCBiZSBtb2Rl
cmF0ZWQgdG8gYXZvaWQgc3BhbS4gUGxlYXNlIHVuZGVyc3RhbmQgdGhhdCBtb2RlcmF0aW9uIHdp
bGwgb2Z0ZW4gY2F1c2Ugc29tZSBkZWxheSwgaW4gcGFydGljdWxhciBvdmVyIHdlZWtlbmRzIG9y
IGhvbHlkYXl9fQB1IaEBoHMFsGIhIv8=
----boundary-LibPST-iamunique-1922619930_-_---
Received on Sun Aug 03 2003 - 00:32:15 UTC