---------- Forwarded message ----------
From: Lukas Renggli <renggli@gmail.com>
Date: 17 November 2010 17:21
Subject: Re: Providing lookup environment for descriptions
To: "Magritte, Pier and Related Tools ..." <smallwiki@iam.unibe.ch>

The way Magritte builds descriptions by default has become quite a
nuisance. I think that at some point Magritte should be improved
in that regard. I wrote a proposal this summer for how to proceed,

but of course I had to finish my writing and never actually
found the time to implement it:

--------------------

I propose to perform the following (non-backward compatible) changes
in the Magritte 2 code-base to resolve some major annoyances and
issues that keep on reoccurring:

- Move descriptions from class-side to instance-side. This resolves
various issues such as cache-invalidation, instance specific
descriptions, dynamic descriptions, context dependent descriptions,
etc. Furthermore the descriptions will be closer to the code they
describe and it will be possible to describe class- and instance-side
of an object, not just the instance-side.

- Rename the method #description as the default entry point into
Magritte to #magritteDescription. This avoids common problems where
the domain model already defines such a method.

- Instead of using a naming convention for description methods, use a
pragma called <magritteDescription> to annotate the methods. And to extend and
change existing descriptions use <magritteDescription: aSelector>. Finally all
Smalltalk implementation reached a consensus of pragmas that can be
safely used cross-platform.

All in all the "new" Magritte would look like in the following
example. Imagine a shop item with the accessor #place:

Item>>place
^ place

Item>>place: aString
place := aString

The meta-description is defined on the instance-side and annotated. It
can refer to itself for the possible places:

Item>>placeDescription
<magritteDescription>

^ MASingleOptionDescription new
options: self possiblePlaces;
label: 'Place of Item';
accessor: #place;
yourself

Class extensions can modify a description using:

Item>>placeDescriptionXmlStorage: aDescription
<magritteDescription: #placeDescription>

^ placeDescription xmlTag: 'xname'

Since these changes are not backward compatible I'll try to provide
automatic refactorings for most parts. Moving existing code to the new
codebase will certainly cause some problems, but in the long run I
believe this to be a much better approach than the current one. If
people have any feedback, concerns or other changes that would be
important in the same run I am happy to hear them.