Index: doc/example-scripts/ruby-mixins.html
===================================================================
diff -u -r4d11e2bfb1180867d9b5b6764ac1124d081b7ef1 -r0f57269d982e98ad81b82a12a5ab5b936784813f
--- doc/example-scripts/ruby-mixins.html	(.../ruby-mixins.html)	(revision 4d11e2bfb1180867d9b5b6764ac1124d081b7ef1)
+++ doc/example-scripts/ruby-mixins.html	(.../ruby-mixins.html)	(revision 0f57269d982e98ad81b82a12a5ab5b936784813f)
@@ -734,25 +734,29 @@
 <h1>Listing of doc/example-scripts/ruby-mixins.tcl</h1>
 </div>
 <div id="content">
-<div id="preamble">
+<div class="sect1">
+<h2 id="_design_study_to_show_the_differences_between_decorator_mixin_classes_and_ruby_8217_s_mixin_modules">Design study to show the differences between decorator mixin classes and Ruby&#8217;s mixin modules</h2>
 <div class="sectionbody">
-<div class="paragraph"><p>Design study to show differences between NX/XOTcl style mixin
-classes and Ruby&#8217;s mixin modules.  The example shows that the
-dynamic class structure of NX (and XOTcl) is able to support
-<em>Ruby-style mixins</em> (called modules) and <em>decorator style mixins</em>
-(named after the design pattern Decorator) at the same time.</p></div>
+<div class="paragraph"><p>This example shows that the dynamic class structure of NX (and
+XOTcl) is able to support <em>Ruby style mixins</em> (called modules) and
+<em>decorator style mixins</em> (named after the design pattern Decorator)
+in the same script.</p></div>
 <div class="paragraph"><p>One important difference between mixin classes in NX and Ruby&#8217;s
 mixins is the precedence order. While in NX, mixins are decorators
 (the mixins have higher precedence than the intrinsic classes,
 therefore a mixin class can overload the methods of the current
-class), the mixins of Ruby have a lower precedence (they extend the
-<em>base behavior</em>; although Ruby&#8217;s modules are not full classes, they
-are folded into the <em>intrinsic class hierarchy</em>).</p></div>
-<div class="paragraph"><p>We define the method <code>module</code>, which behaves somewhat similar to
-Ruby&#8217;s <code>module</code> command and adds the provided class to the
-precedence order after the current class. The easiest way to achieve
-this is via multiple inheritance (i.e. via the <code>superclass</code>
-relationship).</p></div>
+class and its subclasses), the mixins of Ruby have a lower
+precedence (they extend the <em>base behavior</em>; although Ruby&#8217;s modules
+are not full classes, they are folded into the <em>intrinsic class
+hierarchy</em>). Therefore, a Ruby style mixin can be refined by the
+class, into which it is mixed in (or by a subclass). Decorator style
+mixins modify the behavior of a full intrinsic class tree, while
+Ruby style mixins are compositional units for a single class.</p></div>
+<div class="paragraph"><p>To show the differences, we define the method <code>module</code>, which
+behaves somewhat similar to Ruby&#8217;s <code>module</code> command. This method
+adds the provided class to the precedence order after the current
+class. The easiest way to achieve this is via multiple inheritance
+(i.e. via the <code>superclass</code> relationship).</p></div>
 <div class="listingblock">
 <div class="content"><style type='text/css'>
 .nx             {color: #000000; font-weight: normal; font-style: normal; padding-left: 10px}
@@ -825,7 +829,10 @@
     <span class='nx-keyword'>return</span> <span class='nx-variable'>$result</span>
   }
 }</pre></div></div>
-<div class="paragraph"><p>Create a class Group, which is essentially a subclass of "Enumerable".</p></div>
+<div class="paragraph"><p>After having defined the class <code>Enumerable</code>, we define a class
+<code>Group</code> using <code>Enumerable</code> as a Ruby style mixin. This makes
+essentially <code>Group</code> a subclass of <code>Enumerable</code>, but with the only
+difference that <code>Group</code> might have other superclasses as well.</p></div>
 <div class="listingblock">
 <div class="content"><style type='text/css'>
 .nx             {color: #000000; font-weight: normal; font-style: normal; padding-left: 10px}
@@ -1103,14 +1110,14 @@
 % s1 count
 alpha 4 omega</pre></div></div>
 <div class="paragraph"><p>This example showed that NX/XOTcl dynamic class structure is able to
-support Ruby-style mixins, and decorator style mixins at the same time.</p></div>
+support Ruby-style mixins, and decorator style mixins in the same script.</p></div>
 </div>
 </div>
 </div>
 <div id="footnotes"><hr /></div>
 <div id="footer">
 <div id="footer-text">
-Last updated 2012-08-01 19:16:32 CEST
+Last updated 2012-08-01 19:39:00 CEST
 </div>
 </div>
 </body>
Index: doc/example-scripts/ruby-mixins.tcl
===================================================================
diff -u -r4d11e2bfb1180867d9b5b6764ac1124d081b7ef1 -r0f57269d982e98ad81b82a12a5ab5b936784813f
--- doc/example-scripts/ruby-mixins.tcl	(.../ruby-mixins.tcl)	(revision 4d11e2bfb1180867d9b5b6764ac1124d081b7ef1)
+++ doc/example-scripts/ruby-mixins.tcl	(.../ruby-mixins.tcl)	(revision 0f57269d982e98ad81b82a12a5ab5b936784813f)
@@ -1,9 +1,10 @@
 #
-# Design study to show differences between NX/XOTcl style mixin
-# classes and Ruby's mixin modules.  The example shows that the
-# dynamic class structure of NX (and XOTcl) is able to support
-# _Ruby-style mixins_ (called modules) and _decorator style mixins_
-# (named after the design pattern Decorator) at the same time.
+# == Design study to show the differences between decorator mixin classes and Ruby's mixin modules
+#
+# This example shows that the dynamic class structure of NX (and
+# XOTcl) is able to support _Ruby style mixins_ (called modules) and
+# _decorator style mixins_ (named after the design pattern Decorator)
+# in the same script.
 
 package req nx::test
 nx::Test parameter count 1
@@ -13,15 +14,19 @@
 # mixins is the precedence order. While in NX, mixins are decorators
 # (the mixins have higher precedence than the intrinsic classes,
 # therefore a mixin class can overload the methods of the current
-# class), the mixins of Ruby have a lower precedence (they extend the
-# _base behavior_; although Ruby's modules are not full classes, they
-# are folded into the _intrinsic class hierarchy_).
+# class and its subclasses), the mixins of Ruby have a lower
+# precedence (they extend the _base behavior_; although Ruby's modules
+# are not full classes, they are folded into the _intrinsic class
+# hierarchy_). Therefore, a Ruby style mixin can be refined by the
+# class, into which it is mixed in (or by a subclass). Decorator style
+# mixins modify the behavior of a full intrinsic class tree, while
+# Ruby style mixins are compositional units for a single class.
 #
-# We define the method +module+, which behaves somewhat similar to
-# Ruby's +module+ command and adds the provided class to the
-# precedence order after the current class. The easiest way to achieve
-# this is via multiple inheritance (i.e. via the +superclass+
-# relationship).
+# To show the differences, we define the method +module+, which
+# behaves somewhat similar to Ruby's +module+ command. This method
+# adds the provided class to the precedence order after the current
+# class. The easiest way to achieve this is via multiple inheritance
+# (i.e. via the +superclass+ relationship).
 #
 package req nx
 
@@ -77,7 +82,10 @@
   }
 }
 
-# Create a class Group, which is essentially a subclass of "Enumerable".
+# After having defined the class +Enumerable+, we define a class
+# +Group+ using +Enumerable+ as a Ruby style mixin. This makes
+# essentially +Group+ a subclass of +Enumerable+, but with the only
+# difference that +Group+ might have other superclasses as well.
 nx::Class create Group {
   #
   # Include the "module" Enumerable
@@ -212,4 +220,4 @@
 ? {s1 count} {alpha 4 omega}
 
 # This example showed that NX/XOTcl dynamic class structure is able to
-# support Ruby-style mixins, and decorator style mixins at the same time.
+# support Ruby-style mixins, and decorator style mixins in the same script.