diff --git a/doc/reference/ChangeLog b/doc/reference/ChangeLog
index 17e599378..059b543b8 100644
--- a/doc/reference/ChangeLog
+++ b/doc/reference/ChangeLog
@@ -1,3 +1,10 @@
+2008-02-15  Emmanuele Bassi  <ebassi@openedhand.com>
+
+	* clutter-sections.txt: Add last-minute API additions.
+
+	* subclassing-ClutterActor.sgml: Fix some of the notes; the
+	Container implementation will need its own section.
+
 2008-02-14  Matthew Allum  <mallum@openedhand.com>
 
 	* clutter-animation.sgml:
diff --git a/doc/reference/clutter-sections.txt b/doc/reference/clutter-sections.txt
index 65b50eb75..17b63b987 100644
--- a/doc/reference/clutter-sections.txt
+++ b/doc/reference/clutter-sections.txt
@@ -321,6 +321,7 @@ clutter_actor_get_y
 clutter_actor_move_by
 clutter_actor_set_rotation
 clutter_actor_get_rotation
+clutter_actor_is_rotated
 clutter_actor_set_opacity
 clutter_actor_get_opacity
 clutter_actor_set_name
@@ -348,13 +349,17 @@ clutter_actor_set_depth
 clutter_actor_get_depth
 clutter_actor_set_scale
 clutter_actor_get_scale
+clutter_actor_is_scaled
 clutter_actor_get_abs_size
 clutter_actor_apply_transform_to_point
 clutter_actor_transform_stage_point
+clutter_actor_apply_relative_transform_to_point
 
 <SUBSECTION>
 ClutterVertex
 clutter_actor_get_vertices
+clutter_actor_get_relative_vertices
+clutter_actor_box_get_from_vertices
 
 <SUBSECTION>
 clutter_actor_set_anchor_point
diff --git a/doc/reference/subclassing-ClutterActor.sgml b/doc/reference/subclassing-ClutterActor.sgml
index d0de73221..3b3723500 100644
--- a/doc/reference/subclassing-ClutterActor.sgml
+++ b/doc/reference/subclassing-ClutterActor.sgml
@@ -15,12 +15,10 @@
 
   <programlisting>
   A few FIXMES:
-    - note use of units in sizing
     - more on composite/container actors, when/why to use...
       + implementaing a composite actor - set_parent() etc
       + implementing a container - interface etc
     - Painting
-      + note transform already applied. (including position, scale etc)
       + note on cogl_enable if painting texture or blended item
         (should at least call cogl_enable(0) - to reset state cache)
       + fine to use regular GL but then wont be portable
@@ -44,6 +42,11 @@
   each visible child. Remember: the returned coordinates must be relative
   to the parent actor.</para>
 
+  <note>All the coordinates are expressed using #ClutterUnit<!-- -->s,
+  the internal high-precision unit type, which guarantee sub-pixel
+  precision. #ClutterUnit has the same limitation that #ClutterFixed
+  has, see the <link linkend="clutter-Fixed-Point-Support">fixed point page</link>.</note>
+
   <example id="clutter-actor-query-coords-example">
     <para>This example shows how an actor class should override the
     query_coords() virtual function of #ClutterActor. In this case,
@@ -57,6 +60,10 @@ foo_actor_query_coords (ClutterActor    *actor,
 {
   FooActor *foo_actor = FOO_ACTOR (actor);
   GList *child;
+
+  /* Clutter uses high-precision units which can be converted from
+   * and into pixels, typographic points, percentages, etc.
+   */
   ClutterUnit width, height;
 
   /* initialize our size */
@@ -66,7 +73,7 @@ foo_actor_query_coords (ClutterActor    *actor,
     {
       ClutterActor *child_actor = child-&gt;data;
 
-      /* we return only visible actors */
+      /* we consider only visible actors */
       if (CLUTTER_ACTOR_IS_VISIBLE (child_actor))
         {
           ClutterActorBox child_box = { 0, };
@@ -100,6 +107,10 @@ foo_actor_query_coords (ClutterActor    *actor,
   or composite actors with internal children should do the same, and call
   clutter_actor_paint() on every visible child:</para>
 
+  <para>When inside the ClutterActor::paint() method the actor is already
+  positioned at the coordinates specified by its bounding box; all the
+  paint operations should then take place from the (0, 0) coordinates.</para>
+
   <example id="clutter-actor-paint-example">
     <programlisting>
 static void
@@ -142,6 +153,12 @@ foo_actor_pick (ClutterActor       *actor,
   FooActor *foo_actor = FOO_ACTOR (actor);
   guint width, height;
 
+  /* it is possible to avoid a costly paint by checking whether the
+   * actor should really be painted in pick mode
+   */
+  if (!clutter_actor_should_pick_paint (actor))
+    return;
+
   /* by including &lt;clutter/cogl.h&gt; it's possible to use the internal
    * COGL abstraction API, which is also used by Clutter itself and avoids
    * changing the GL calls depending on the target platform (GL or GL/ES).
@@ -150,6 +167,9 @@ foo_actor_pick (ClutterActor       *actor,
 
   clutter_actor_get_size (actor, &amp;width, &amp;height); 
 
+  /* it is also possible to use raw GL calls, at the cost of losing
+   * portability
+   */
   glEnable (GL_BLEND);
 
   /* draw a triangular shape */
@@ -164,4 +184,6 @@ foo_actor_pick (ClutterActor       *actor,
     </programlisting>
   </example>
 
+  <para></para>
+
 </chapter>