[mcclim-devel] Black art

[Duncan Rose]

On Thursday, April 28, 2005, at 06:17 PM, rpgoldman at 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 at common-lisp.net
> http://common-lisp.net/cgi-bin/mailman/listinfo/mcclim-devel
>