[ZWeb] Re: [Zope] user contributions to Zope.org

[Graham Chiu]

In message <Pine.LNX.4.21.0006101101270.14801-100000@korak.digicool.com>
, Ken Manheimer <klm@digicool.com> writes
>On Sat, 10 Jun 2000, Graham Chiu wrote:
>
>> How about another alternative - such as in Forth where they used shadow
>> screens for commentary on source code?
>
>I've not used forth - can you say more about what's done there?
>
>(It *sounds* like having a separate screen which "projects" annotations
>onto the text - which is what ka-ping's mediator architecture does...)
>

Well, my recollection is not that clear but here goes.  

In the olden days Forth used 1024 byte pages directly mapped to the
storage medium which were called screens.  You then got from that 16
lines of about 64 chars to write your code.  Forth words were encouraged
to be small, and fit into one screen.  For many reasons, Forth became
very hard to read, and so shadow blocks were invented where each page of
source code was associated with a screen of commentary.

This idea fell into disuse as file mapped source code became more
popular, and Forth's reputation as a write only computer language grew!
Dare I say this shares some parallels with Zope <g>

But I would imagine that one could reserve an extension so that each
HTML page could be mapped to a commentary page.


This is taken from a google search

http://dec.bournemouth.ac.uk/staff/pknaggs/papers/literate.html

4.1. The Forth Block
In Appendix A we see the code as a traditional Forth screen, or block.
The first line is an index line, used to give a general title to the
block. The index line has lead to the practice of collecting together
related definitions into the same block or sequence of blocks. In this
example we have gathered together the definitions relating to the memory
management of the application. Thus making it easy to find and
concentrate on for debugging purposes. 
The text on the right of the index line is an indication of last time
the block was modified (10-May-1990) and by whom (PjK). This is placed
on the block automatically by the Forth++ editor and is useful for
maintenance and project management reasons. 

One of the drawbacks of using blocks is that the space is limited and
one is tempted to shoehorn the code and not document it. For this reason
the "shadow" block was developed to allow documentation of the code
presented in the associated block (as shown in the example). Normally
the two blocks are printed side by side, thus making it obvious which
code is referred to in the shadow (or "comment") block. The shadow block
provides us with an extremely useful documentation technique, yet it is
suprising how many seasoned Forth programmers do not bother with the
shadow block, thus increasing the difficulty of maintenance. 


-- 
Regards,  Graham Chiu