diff --git a/doc/cookbook/actors.xml b/doc/cookbook/actors.xml
index 5d944fcae..3fd3a6a8e 100644
--- a/doc/cookbook/actors.xml
+++ b/doc/cookbook/actors.xml
@@ -96,92 +96,55 @@
         Reference Manual</ulink> before proceeding.</para>
       </tip>
 
-      <section>
-        <title><filename>cb-button.h</filename></title>
+      <example id="actors-composite-cb-button-h">
+        <title><filename>cb-button.h</filename>: header file</title>
 
-        <para>The header file defines the public API for the class,
-        including GObject type macros, class and object structures, and
+        <para>This defines the public API for the class, including
+        GObject type macros, class and object structures, and
         function prototypes.</para>
 
         <programlisting>
 <xi:include href="examples/cb-button.h" parse="text">
-  <xi:fallback>a code sample should be here... but isn't</xi:fallback>
+<xi:fallback>a code sample should be here... but isn't</xi:fallback>
 </xi:include>
         </programlisting>
+      </example>
 
-      </section>
-
-      <section>
-        <title><filename>cb-button.c</filename></title>
+      <example id="actors-composite-cb-button-c">
+        <title><filename>cb-button.c</filename>: <type>ClutterActor</type>
+        and GObject implementation</title>
 
         <para>This is the main C code file which implements both
         the GObject and Clutter parts of <type>CbButton</type>.
         The example below is commented liberally, and gives some samples
         of gtk-doc annotations to generate API docs for the
-        widget. The <link linkend="">discussion section</link>
-        comments more specifically about the Clutter-specific parts
-        of it.</para>
+        widget. The <link linkend="actors-composite-discussion">discussion
+        section</link> comments more specifically about the Clutter-specific
+        parts of it.</para>
 
-        <para>
-        enum for signals ???why do we need these
+        <programlisting>
+<xi:include href="examples/cb-button.c" parse="text">
+<xi:fallback>a code sample should be here... but isn't</xi:fallback>
+</xi:include>
+        </programlisting>
+      </example>
 
-        enum for properties ???why do we need these
+      <example id="actors-composite-actors-composite-main-c">
+        <title><filename>actors-composite-main.c</filename>: trivial
+        application demonstrating usage of <type>CbButton</type></title>
 
-        array for signals ???is it an array
+        <para>Note how any of the <type>ClutterActor</type>
+        functions (like <function>clutter_actor_set_size()</function>
+        and <function>clutter_actor_add_constraint()</function>) can
+        be applied to instances of our <type>ClutterActor</type>
+        implementation.</para>
 
-
-
-
-        and Clutter stuff (private to the class):
-
-        allocate (required)
-        paint (required)
-        you could get away with just these two
-        but if you're not composing your actor, or are creating a container,
-        you need to do more
-
-
-
-
-        then more GObject stuff (it should come after the Clutter method
-        implementations, i.e. allocate and paint):
-
-        class_init
-        - where we wire together our functions
-        - we can also do things like adding properties and signals
-
-        init
-        - where we create the private structure
-        - where we compose the actors together inside our ClutterActor
-        subclass
-
-
-
-
-
-        Then normally some public API:
-
-        typically you want a new() function
-
-        for our class, we'll put some wrappers around functions
-        on the composed actors
-
-        </para>
-
-      </section>
-
-      <section>
-        <title><filename>actors-composite-main.c</filename></title>
-
-        <para>
-        The cb-button-main.c file shows how to use the new
-        actor inside a Clutter application. Note how any of the
-        <type>ClutterActor</type> functions (like set_size,
-        add_constraint) can be applied to instance
-        of our <type>ClutterActor</type> implementation.
-        </para>
-
-      </section>
+        <programlisting>
+<xi:include href="examples/actors-composite-main.c" parse="text">
+<xi:fallback>a code sample should be here... but isn't</xi:fallback>
+</xi:include>
+        </programlisting>
+      </example>
 
     </section>
 
@@ -190,6 +153,8 @@
 
       <para>Explain about GObject a bit???</para>
 
+      <para>Note size requisition in the example application???</para>
+
       <para>The actor implemented here is put together through
       simple composition. This has the advantage of simplifying the
       code for the subclass: we can just wrap a facade round