Documentation moving slowly; let's redesign/update some parts.

[Erik Enge]

The documentation is moving, but very slowly.  I've been thinking lately
that some of my efforts will be wasted rather quickly as we redesign
parts of Eclipse and this has been discouraging.  What I'm about to
suggest is that we redo some parts that we know could be done better
before documenting them.

For example, our theming concept needs some work.  Most notably, we need
to be able to change icons when a mouse moves over buttons but we also
should make the process of creating a theme slighly more elegant.

I'm not entirely sure what is required to make the buttons happen, but
making the process of creating a theme more elegant should be fairly
straighforward.  We should eliminate the excessively large macro
define-theme and replace it with smaller functions/macros that make more
sense and are easier to type without errors.  I'm hoping to create a
situation where you could build a theme in an incremental way, instead
of as now, where it's an all or nothing approach.

We need to clarify the draw-on-in* methods too so that they make more
sense to a person creating themes.  Perhaps we could use macros here so
that the syntax is more basic.  I don't have anything solid here, I just
would like to be more straightforward than it currently is.

In making the process more elegant I hope we will be able to keep it
around, even if we decide at a later stage that we need to do some
redesigning of how themes work.  This would eliminate the need for
themes for various versions of Eclipse (perhaps; I don't know how
realistic this is, but I do believe it is worth a shot).

While overhauling the theming-code, we should also take the time to
document all functions, macros, variables and slots to make it easier to
read the code without trying to defer from the name of a
function/macro/variable/slot what it does or what it represents.

Thoughts?

Erik.