--- a/CharacterArray.st	Mon Nov 07 09:49:08 2016 +0100
+++ b/CharacterArray.st	Mon Nov 07 09:57:36 2016 +0100
@@ -551,8 +551,17 @@
 !
 
 setupNormalizationMaps
-    "returns a 2-stage map from ch2 -> ch1 -> mappedChar
-     for unicode normalization (i.e. for making combining chars regular ones)"
+    "returns a 2-stage map from ch2 -> ch1 -> mappedChar.
+     for unicode normalization 
+     (i.e. for replacing combining char-sequences with regular characters).
+     ch2 is the combining charCode (eg. 0x0308), ch1 is the previous character (eg. $A),
+     mappedChar is the result (eg. $Ä).
+     Caveat: 
+        possibly incomplete: only COMBINING_DIACRITICAL_MARKS are cared for.
+        Does not care for COMBINING_DIACRITICAL_MARKS_EXTENDED
+        and COMBINING_DIACRITICAL_MARKS_SUPPLEMENT.
+        However; those are used for German dialectology, ancient Greek and other similar
+        exotic uses. Probably noone will ever even notice that they are missing..."
      
     |def|
 
@@ -585,7 +594,13 @@
 
 unicodeDenormalizationMap
     "returns a 2-stage map from ch2 -> ch1 -> mappedChar
-     for unicode normalization (i.e. for making combining chars regular ones)"
+     for unicode normalization (i.e. for making combining chars regular ones).
+     Caveat: 
+        possibly incomplete: only COMBINING_DIACRITICAL_MARKS are cared for.
+        Does not care for COMBINING_DIACRITICAL_MARKS_EXTENDED
+        and COMBINING_DIACRITICAL_MARKS_SUPPLEMENT.
+        However; those are used for German dialectology, ancient Greek and other similar
+        exotic uses. Probably noone will ever even notice that they are missing..."
      
     UnicodeDenormalizationMap isNil ifTrue:[
         self setupNormalizationMaps
@@ -599,7 +614,13 @@
 
 unicodeNormalizationMap
     "returns a 2-stage map from ch2 -> ch1 -> mappedChar
-     for unicode normalization (i.e. for making combining chars regular ones)"
+     for unicode normalization (i.e. for making combining chars regular ones).
+     Caveat: 
+        possibly incomplete: only COMBINING_DIACRITICAL_MARKS are cared for.
+        Does not care for COMBINING_DIACRITICAL_MARKS_EXTENDED
+        and COMBINING_DIACRITICAL_MARKS_SUPPLEMENT.
+        However; those are used for German dialectology, ancient Greek and other similar
+        exotic uses. Probably noone will ever even notice that they are missing..."
      
     UnicodeNormalizationMap isNil ifTrue:[
         self setupNormalizationMaps
@@ -4740,7 +4761,9 @@
      Caveat: 
         possibly incomplete: only COMBINING_DIACRITICAL_MARKS are cared for.
         Does not care for COMBINING_DIACRITICAL_MARKS_EXTENDED
-        and COMBINING_DIACRITICAL_MARKS_SUPPLEMENT"
+        and COMBINING_DIACRITICAL_MARKS_SUPPLEMENT.
+        However; those are used for German dialectology, ancient Greek and other similar
+        exotic uses. Probably noone will ever even notice that they are missing..."
 
     |outStream prevChar map mapEntries mappedChar|