Magic Book... (was Re: Re[2]: Good, thorough Smalltalk reference)

Russell N Hyer hrothgar.ofstingan at
Wed Jan 18 18:55:21 UTC 2006

Hey Squeakers,

...& Göran

On 1/18/06, goran at <goran at> wrote:
> Hi folks!
> I am not sure anyone is reading this thread anymore (pretty long),
> especially since it is one of those yearly
> let's-talk-about-documentation-discussions. :)

Nice self-reference ;)

> But I would like to remind you about an idea I floated a while back
> (2003): The Magic Book.


> The Magic Book idea came from the realization (after numerous rants to
> get people to write unit tests from Stephane Ducasse :) ) that one of
> the grand properties of unit tests - as being a form of documentation
> (unit tests can often be used as example code) - is that they *are*
> coupled to the code. If the code breaks the "external contract" the
> tests break. And if the tests are modified - meaning that the "external
> contract" is changed - the code possibly breaks. So a unit test can be
> seen as an "external contract" of the behavior/API of one or more
> objects.
 [snip (color coded `pages' ``linked'' to test code to check the
environment, which does not break the ```book'')]


Cheers for that message. I wasn't even on the Squeak Dev list back in
2003. Though I might have just been tinkering with it then, perhaps.
And this idea is so extremely cool, that I will have to give it a
proper ponder, since documentation is so important. General as well as
specific, seeing as I've been hacking PDFs to display on my ancient
Macintosh family of machines (1997 backwards...) - then, maybe a cool
feature of a Squeak Based PDF Reader would be its comprehending of
special objects, which were executable scripts. (this would then fit
in with the cool feature of OO environments, namely, Polymorphism).

So, that's the general idea GPL Copyright me. Implementation to come,
seeing as it's 2006 and I'm being overly optimistic.

Russell Hyer

More information about the Squeak-dev mailing list