On Thursday, April 28, 2005, at 06:17 PM, rpgoldman@real-time.com wrote:
I think one thing that makes it more confusing for a newcomer to CLIM is the way many of the manuals are written.
Indeed.
I have looked at both the LW and the Allegro manuals, and maybe they're great manuals, but they are terrible to learn from.
For example, the Franz CLIM UG seems to be written from the bottom-up, in parallel to the architecture of the software. It starts with drawing planes and the screen, and then works up to gadgets.
I think both the Franz + Lispworks docs are derived pretty much from the spec, and as such follow a structure that makes sense in a specification but probably less sense in a tutorial. Whether the 'user guides' can be considered tutorials or not is a different question, I suspect many people would say they can't.
The specification itself seems to be written in the order the different layers of CLIM need to be implemented to have everything work; geometry comes first (most specific, the foundation of windows, sheets, output recording, etc.) followed by the next layer (Windowing) which is the basis for presenting information to the user and reading input from the user; then the input and output protocols (implemented on top of the fundamental windowing features) and finally 'application building'.
You almost want to read the spec from back to front as an application developer I think. Probably the most important thing to take on board is that CLIM is rigidly layered. The lower, more detailed parts can be used if needed but generally only the high level parts are necessary for a large class of applications (default behaviours, basic windowing, input handling and basic drawing).
There's a good paper floating around somewhere that describes this layering (for CLIM 1 I think but the general principles are the same even if some specifics are different). I don't have the link to this handy either, but it's called "A Guided Tour of the Common Lisp Interface Manager" by Rao, York and Doughty.
But if one looks at sources that try to teach a programmer how to do things, they always start with tasks the programmer might want to accomplish, and work down into detail. So a guide to using CLIM should start with application frames, move to gadgets, etc.
I agree with this; I think that this is the approach the McCLIM tutorial is taking (I seem to have mislaid this document, perhaps somebody else can provide a pointer). Here's another document (referenced from the McCLIM wiki) which takes the approach you propose:
http://constantly.at/lisp/ui.html
Again, I'm not trying to complain that this isn't in those manuals --- manuals and tutorials aren't the same.
And I don't want to be seen as a whiner who just wants everything given to him on a platter.
What I'd like to do is just share some perceptions of what I think might make things easier for McCLIM users and might make McCLIM more popular.
We could ask the same of Lisp in general perhaps ;-)
-Duncan
Best, R _______________________________________________ mcclim-devel mailing list mcclim-devel@common-lisp.net http://common-lisp.net/cgi-bin/mailman/listinfo/mcclim-devel