Last updated at 11:05 pm UTC on 24 May 2007
Goran Hultgren posted "The Magic Book - a design draft" to the squeak-dev mailing list on 2/11/2003:
The idea of a "Magic Book" inside Squeak acting as both an introductory documentation for Squeak and as a reference manual is quite intriguing.
A few basic ideas that got this started:
- Tying unit tests to documentation in order to detect stale documentation
- Not bloating the image
- Easily maintain the book cooperatively (like swiki)
Ok, what would be the STTCPW? (For all you non XP aware: "Simplest Thing That Could Possibly Work").
By applying reuse - what do we already have? We already have:
A very good format for "active content". I am not sure how easily they are backwardscompatible though. Could anyone post some insight in that matter?
In my experience, projects are not compatible between Squeak versions. They tend to mostly work, but to have little problems. On the other hand, it tends to be pretty easy to upgrade a project from an old image version to a newer version.
Projects seem like a great format for holding the Magic Book. First, they are the main way Squeak content is supposed to be generated, anyway, and so it seems appropriate to use it for a book about Squeak in Squeak. Second, they're really nice. They combine text, graphics, movies sound, and in general anything you can do with morphic. Finally, it is good to have example uses of Squeak for making Active Essays (which is what this would be); it would benefit the whole project to have such experience. -Lex Spoon
A universal UI kindof thing. We could easily let StarBrowser be the main UI of the Magic Book! It lends itself easily for the task - a treeview on the left, a dynamic area to the right etc. If we somehow find a good way to integrate a little search form then it would be quite perfect.
In whichever form we choose to have the Chapters of the book (Projects) we could register them on SM (a few new categories would be nice) and thus get a distributed always up to date model of chapters for free. And when SM1.1 gets completed it will track versions of the chapters for us, etc. And in SM1.1 it will have a sensible smart diskcache for the packages (read Chapters) so we get that too.
Free text engine:
Scott Crosby wrote a neat little engine for maintaining keyword indices that the book obviously should use. I have also been intending to integrate that into SM. We should be able to add it to SM in such a way that the Magic Book can simple get that "for free".
So... we already have a bunch of cool technology to implement the Magic Book IMHO. We just need to knit it all together in a smart way.
If we split the book in the following pieces:
- The TOC. This is essentially a list of chapters organized in a hierarchy with names and a link to the corresponding SM package that is the chapter content - a Project.
- The chapters themselves. These are simply Projects published as packages on SM. Perhaps we need to follow a few conventions for these Projects so that we easily can "jump into" them in a proper manner, extract keywords for indices etc. An approach to this would be to extract all the text from the project to a plain text file and include it in the package along with the project file. Is there a nice utility to do this? As for "jumping in", is there a way to specify a dynamically supplied command to a project when it is loaded?
- The search indices and the index (as books have last).
If 1 and 2 above also are packages on SM (in whichever suitable form, doesn't matter) it will be even more simplified. So the book contents are then managed as packages on SM. We get the possibility of having different owners for different chapters, release/version tracking etc. It is obvious when you think about it -why shouldn't they be packages?
The StarBrowser is the obvious choice of a UI - it already has navigation mechanisms and it can also show contents from the book along with other things in a highly dynamic fashion. Why reinvent that?
And SqueakMap gives us a lot of stuff like efficiently always updated
content, a smart cache etc.
And there will be no image bloat whatsoever.
Well, ok, what do you all think? Darn, this sounds like real fun... I
need to get cranking at my SM1.1 ... :-)
One person – probably Goran if he wants to – should probably be the chief editor. No one else touches the official version of the book. Written documentation needs to be coherent, even more so than code.
Goran Krampe: I don't really agree. :-) First of all I am not really interested in such an effort. Secondly I think a more distributed responsibility would be better.
So what should the book include? Some quick ideas:
- Overview of the Squeak project and examples things in the gestalt. Alan Kay's talks on Squeak should provide an idea of the material for this.
- necessary concepts for working in Squeak
- how to exit :)
- images, with saving and loading
- projects, with saving and loading
- flaps, maybe
- maybe, how to deal with it when a pink debugger pops up :(
- working the interface to do graphics. This should provide enough info for people to do Photoshop-like things in Squeak
- creating new morphs: "new object", etc.
- changing colors of things, including gradients
- combining things together
- use of layout
- cover various applications: glue for presentations, books (like the Magic Book), teaching
- examples: drive a car, ...
- emphasize that things should be explored. Many morphs have a useful set of etoys tiles available
- There is a good start on a TOC like this with some parts filled in at http://squeakland.org:8080/super/218
- Smalltalk programming? What to include here?!
- Joe the Box is awesome for people who don't already know how to program
- What else, though? Who is going to be reading this thing?
- what else?
What it should not include
Should it really have a reference for all of Squeak? That may be a fine ultimate goal, but it seems way to hard for a first cut.
It would be awesome to have it, though, no question about it. It would give a great place to hook in documentation about particular subsystems. If it was done, keep in mind that an aweful lot of it should simply be links into the code, e.g. class comments and examples.