Hi Stéphane,

I'm very glad that you're digging around in the code,

> I have a few questions:
> 	- What is the difference between OB-Standard and OmniBrowser:
> 	I guess that one is the framework and the other is the standard code 
> browser?

That's right. There's also OB-Filesystem, which is the file browser 
that was part of the early alphas. It's been languishing while I worked 
on the code browsers, so I haven't included it in the later releases. 
When I get some spare time, I'll dust it off and release it separately.

> 	- so if I try to understand:
> 		A browser is described by a metaGraph.  This metaGraph is described 
> by node and edges.
> 		A node can be manipulated by actions
> 		which represent what can be done on a specific node. A node will 
> wrap the code entity.

Yes. The important thing to understand is that there are actually two 
graphs here.

The "domain graph" represents the objects in the domain we are 
browsing. The "domain nodes" wrap objects in the domain the user is 
working with - Smalltalk code in this case. There are many kinds of 
domain nodes; all the subclasses  of OBNode are domain nodes. The edges 
of this graph aren't reified.

The "metagraph" represents the paths through the domain graph that the 
browser makes available to the user. When the user clicks on a domain 
node, we look at its metanode to see what should happen in response. 
The edges incident on that metanode represent  navigation messages that 
we can send to the selected domain node. The domain node will respond 
with a collection of more domain nodes, which are then associated with 
the metanode the edge leads to.

That sounds more confusing than it really is, so I'll give a more 
concrete example. Imagine that we've just clicked on the class Date in 
an OBSystemBrowser. The currently selected domain node is an 
OBClassNode that wraps Date. Its metanode is touched by a single edge, 
labelled #categories. So we send #categories to the domain node that 
wraps Date, and get back a collection of OBMethodCategoryNodes. The 
edge points to another metanode, which we assign to all the nodes in 
our collection. Then we display the list of nodes in the column to the 
right of the one containing Date. If the user then clicks on a method 
category, we repeat the process to get a list of OBMethodNodes to 
display in the next column.

> 		It is not clear yet to me, how we represent state transition (for 
> example, how to pass
> 		from "we are editing a method, to the method is compiled so the 
> browser does not have to
> 		tell us that we will lose your code if we click on a method category 
> for example".

Hmm, Alexander asked me that question as well. I think it might be best 
to think about it in terms of two levels of state, corresponding to the 
metagraph and the domain graph.

The metagraph is very like a state machine. Metanodes represent states, 
and edges represent transitions between them. But you might say that 
these are "abstract states." There could be any number of nodes in the 
domain graph that correspond to a given metanode. The currently 
selected domain node is the concrete state of the browser. When the 
user does something that triggers a state change, the browser sends 
#okToChange to all of its panels. The panels all maintain secondary 
state that they can use to tell whether a state transition is ok. Then 
after the change has been done, the browser sends #nodeChanged to all 
the panels, and they update their secondary state (and the display) to 
reflect the change.

> 	- why OBCodeNode, OBClassVariableNode are totally empty?

This is the result of refactorings. They originally had more definite 
purpose, but gradually lost all their methods. I left OBCodeNode in 
because I wasn't sure that I wouldn't need to put behavior there again. 
I had removed it and then put it back once already, and it was enough 
of a hassle that I left it in. OBClassVariableNode is still there for 
structural reasons. It makes more sense to me to have an OBVariableNode 
class that both class and instance variable nodes inherit from, even if 
it results in an empty class. The alternative - having 
OBInstanceVariableNode inherit from OBClassVariableNode - would be 
confusing, I think.

> 	- is OB using the systemNotifier mechanism?

Yes. OBCodeBrowser registers for SCN events and refreshes its display 
when it receives them.

> 	- why the OBMetaGraphBuilder does not have any instance methods? I 
> understand that this is a metagraph Repository
> 	but without methods or state I do not understand.

This is more refactoring. As far as OB-Standard is concerned, this 
class can go away, but OB-Filesystem still has extension methods on it, 
and so I left it in until I get around to reviving OB-Filesystem.

> 	- what is an OBDefinition? Answer should also go in comments :)

An OBDefinition is a way to define domain nodes. It presents the domain 
node as text, and knows how to translate changes in the text into 
changes in the domain. So an OBMethodDefinitionNode knows how to 
compile methods, OBClassDefinitionNode knows how to create or alter 
classes. Definitions also do all the associated error checking - for 
example, OBClassDefinition is responsible for checking that a new class 
definition doesn't overwrite some other class in the system.

As for comments, yes. The comments in beta 1 haven't been updated in a 
while. I'm working on this, but it's a lot of work, and I wanted to at 
least get the code out there. The next release should have updated 
comments.

> 	- how can I open an OBHierarchyBrowser?

Ok, you caught me. This isn't implemented yet. I hardly ever use 
hierarchy browsers, so this one fell through the cracks. I'll put one 
in the next release.

> 	- I imagine that we really need the notion of environment to be able 
> to scope the search
> 	senders... in the image, and for example SystemNavigation could use 
> such search environment
> 	and also for the rbengine. Do you think that OBEnvironmentNode could 
> be one candidate,
> 	may be the namespace implementation we are doing could serve also 
> that purpose.

I agree that we need this, but I don't think OBEnvironmentNode is a 
candidate. Its purpose is to *wrap* an environment. Right now it wraps 
Smalltalk. I think we'd actually be in good shape if SystemNavigation 
were more analogous to SystemOrganization. Then you could send 
#navigation to a SystemDictionary to get a SystemNavigation that was 
limited to the classes it contains. That would be a big step towards 
being able to have multiple SystemDictionaries.

Colin