--- a/Color.st	Sun Jan 22 10:51:27 2017 +0100
+++ b/Color.st	Sun Jan 22 11:02:51 2017 +0100
@@ -49,19 +49,23 @@
 
 documentation
 "
-    Color represents colors in a device independent manner, main info I keep about
-    mySelf are the red, green and blue components scaled into 0 .. MaxValue.
-    The device specific color can be acquired by sending a color the 'onDevice:aDevice' message,
-    which will return a color with the same rgb values as the receiver but specific
-    for that device.
-
-    Most of the device dependent coding was to support limited graphics devices (non-true color)
+    Color represents colors in a device independent manner.
+    The main info I keep in mySelf are the red, green and blue components scaled into 0 .. MaxValue.
+    
+    A device specific color can be acquired by sending a color the 'onDevice:aDevice' message,
+    which will return a color with the same r/g/b values as the receiver but with a specific
+    colorID for that device (which may or may not imply a colormap slot allocation on that device).
+    A device-specific color index (i.e. palette-ID) is then found in the newly allocated color's colorID slot.
+    
+    Most of the device dependent coding was to support limited graphics devices (non truecolor, eg. palette)
     in a transparent way. This was required at that time (late 80's, early 90's),
-    but is now almost obsolete, as these days, virtually any graphic systems supports it.
+    but is now almost obsolete, as these days, virtually any graphic systems supports true colors.
     It is arguably, if that stuff should remain here, or if we should simply give up support
-    for old VGA-like displays.
-
-    Colors can be pure or dithered, depending on the capabilities of the device.
+    for old VGA-like displays 
+    (actually, there are still such limited displays around, for example in the embedded area.
+     So we will leave that support in for another few years ;-) ).
+
+    On such limited devices, colors can be pure or dithered, depending on the capabilities of the device.
     For plain colors, the colorId-instvar is a handle (usually lookup-table entry) for that
     device. For dithered colors, the colorId is nil and ditherForm specifies the form
     used to dither that color. The ditherForm can be either a depth-1 bitmap or a pixmap
@@ -4854,18 +4858,17 @@
         ]
     ].
 
-    "/ round a bit within 1% in red & green, 2% in blue
-
     rV := red.
     gV := green.
     bV := blue.
 
+"/    "/ round a bit within 1% in red & green, 2% in blue
 "/    rV := (red / 100.0) rounded * 100.
 "/    gV := (green / 100.0) rounded * 100.
 "/    bV := (blue / 50.0) rounded * 50.
-
-    "/ if I am already assigned to that device ...
-
+"/
+"/    "/ if I am already assigned to that device ...
+"/
 "/    ((device == aDevice) and:[ditherForm notNil]) ifTrue:[
 "/
 "/        "/ mhmh - if I was dithered the last time (not enough colors then)