Hi BlackBoxers,

Finally after many trials and tribulations (disk crash etc.) a first 4 page
draft outline of the proposed Practical Guide to BlackBox (BlackBox odc
document appended to this email). 

On a lot of the topics of the present outline I have some content as well
(which I will endeavor to add over the coming months). However I do not want
to just present my idiosyncratic efforts but hope  to first come to a
broadly accepted common outline of sufficient detail so that it becomes easy
for everyone to add small pieces. 

The outline presented needs further expansion, particularly on the more
complex subjects.
So please feel invited to amend, add to, detail etc. this outline

Before everyone start to chop and cut too savagely I'd like to explain the
methodology behind the outline (i.e. the buildup of the guide):

The Idea
1. I envisioned a guide which is a fairly comprehensive guide into the
system for the (beginner and) moderately experienced programmer. With
comprehensive I do not mean every esoteric and specific detail, but the sort
of general things you expect a normal person to want to be able to do:
general programming, making a "real" database application, use forms and
reports (text views), making some simple compound views, some simple
controls, making a simple but real Internet application etc.

2. Under comprehensive I also wanted to cover general programming in
Component Pascal. This is ofcourse covered in various ways in other books
like "Into the Realm of Oberon (Nikitin), Oberon-2 Programming in Windows
(Muhlbacher etc.), Programming in Oberon (Reiser/Wirth), Object-Oriented
Programming in Oberon-2 (Mossenbock), Module Klassen Vertrage (Hug) and
ofcourse Programming in BlackBox (Warford). These books are however not
directly available to all (and some hard to get or out of print) and have
different coverage. I wanted to have as much as possible one document which
is immediately available (as .odc document) within BlackBox which is a sort
of summary / practical guide of the pertinent parts of these books. E.g. you
can see the same subject as in the exellent Mossebock's book in the outline.

3. I also envisioned it to be a quick & practical reference for the more
experienced BlackBox user, in the sense of "how did I do that again". For
example a generic tree or the setting up an Internet Client with the Dbu
system. In short templates to copy into programs.

4. Lastly it was my intention (unfortunately not yet worked out in the
outline) to bridge the gap to Helmut Zinn's and other Extra-BlackBox
subsystems. Specifically for the generic Subsystems (e.g. Html). Not in the
sense of at the end of a chapter just referring to these ("have a look at
xxx subsytem") but explaining them then and there. 

The Approach
1. I have tried as much as possible to simply name the items of the outline
with WHAT you want to do, instead of HOW to do it, or which CONCEPT, PATTERN
or CLASS is involved. So generally I just talk about non-interacting and
interacting Views in the outline, instead of Controllers, Models, Iterators,
Containers etc. 

2. As a general principle I have endeavored to split subjects into chunks
like basic, intermediate and advanced. Or simply 1, 2, 3, 4 with simular
types of meaning and/or not to  lump too much together. I do not want to
lose the learner. He/She should be able to say "I understand that Chapter".
This is different from the general BlackBox documentation which often start
with the most complicated bits first, has pretty big chapters and leaves
quite a few things pretty unexplained.

3. I have made some particular choices

- Database programming (see also the second part of Hallett's Developing
Programs in BlackBox) I split into 2 parts. The database sec part and the
View/ Interface part. It's easier to understand that way plus the database
sec part is not too complicated and allows users to access databases without
getting into the Forms part (i.e. just using say StdLog or making a simple
report). For that reason that part is put early on in the outline.

- View programming. It seems to me most people have a kind of elementary
understanding that a document can contain different kind of views (a
picture, a text etc.). The first notion of this is usually fairly static and
simple. Only later on it dawns that it can be much more complicated than
that with dynamic view sizes proportional to the Window size (or not),
interactions, states etc. Therefore I first divided the subject into
Non-Interactive and Interactive views and within that into singular view
types and composite view types. It may be the power of BlackBox that you can
make very complex controls, make wrapper views, broadcast, cut and paste
between views etc. etc. but most times that is NOT NEEDED. Generally if I
take myself as an example I want to access a database, make 'passive'
reports and use forms. The most complex it generally get for me is to say
have a graph view displaying data in a form or updating parts of a text. 

Shortcomings
Quite a few matters are still a bit lost. For example non-modal programming.
Also there are a fair few conceptual issues which are still a bit fuzzy.
Just to give one example:
When I first tried to learn BlackBox I quickly understood Text Views and
(thanks to Warford) Form Views. Then I wanted to make some graphs and turned
to the last chapter View Construction. I assumed all views would have some
generic operations like displaying or copying but to my surprise the views
you have to draw or paint in this chapter need up calls like Deposit and to
display them you need to place them on a stack. I could not find a simple
Draw Dot procedure. So this chapter's views seemed somehow more low level (I
have called them 'base' views in the outline for want of a better term) but
also more obtuse. I'm not very sure how to present this in the guide
(already in the outline)

I hope the rest is more or less self-evident.

Please react. If you have very concreet suggestions for the outline, comment
them in a red font.

Regards, Bart

 <<The Practical Guide to BlackBox.odc>> 

-- 
The contents of this e-mail are intended for the named addressee only. It
contains information that may be confidential. Unless you are the named
addressee or an authorized designee, you may not copy or use it, or disclose
it to anyone else. If you received it in error please notify us immediately
and then destroy it. 
5JLj