From 146e15297fab2a087effdd3df1bc0d320f674a5d Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@linux.intel.com>
Date: Mon, 17 Oct 2011 10:24:25 +0100
Subject: [PATCH 1/4] debug: Clean up debugging notes

---
 clutter/clutter-backend.c                     |  6 ++---
 clutter/clutter-bezier.c                      |  2 +-
 clutter/clutter-debug.h                       | 27 +++++++++----------
 clutter/clutter-main.c                        |  4 ---
 clutter/deprecated/clutter-behaviour-depth.c  |  2 +-
 .../deprecated/clutter-behaviour-ellipse.c    |  2 +-
 .../deprecated/clutter-behaviour-opacity.c    |  2 +-
 clutter/deprecated/clutter-behaviour-path.c   |  2 +-
 clutter/deprecated/clutter-behaviour.c        | 12 ++++-----
 clutter/wayland/clutter-backend-wayland.c     |  2 +-
 clutter/win32/clutter-event-win32.c           |  4 +--
 11 files changed, 29 insertions(+), 36 deletions(-)

diff --git a/clutter/clutter-backend.c b/clutter/clutter-backend.c
index 80e4853d0..7243cac8a 100644
--- a/clutter/clutter-backend.c
+++ b/clutter/clutter-backend.c
@@ -465,7 +465,7 @@ _clutter_backend_ensure_context (ClutterBackend *backend,
         {
           new_stage = NULL;
 
-          CLUTTER_NOTE (MULTISTAGE,
+          CLUTTER_NOTE (BACKEND,
                         "Stage [%p] is not realized, unsetting the stage",
                         stage);
         }
@@ -473,7 +473,7 @@ _clutter_backend_ensure_context (ClutterBackend *backend,
         {
           new_stage = stage;
 
-          CLUTTER_NOTE (MULTISTAGE,
+          CLUTTER_NOTE (BACKEND,
                         "Setting the new stage [%p]",
                         new_stage);
         }
@@ -515,7 +515,7 @@ _clutter_backend_ensure_context (ClutterBackend *backend,
       current_context_stage = new_stage;
     }
   else
-    CLUTTER_NOTE (MULTISTAGE, "Stage is the same");
+    CLUTTER_NOTE (BACKEND, "Stage is the same");
 }
 
 
diff --git a/clutter/clutter-bezier.c b/clutter/clutter-bezier.c
index f4c480c1d..7b6ba3cbb 100644
--- a/clutter/clutter-bezier.c
+++ b/clutter/clutter-bezier.c
@@ -180,7 +180,7 @@ _clutter_bezier_advance (const ClutterBezier *b, gint L, ClutterKnot * knot)
   knot->x = _clutter_bezier_t2x (b, t);
   knot->y = _clutter_bezier_t2y (b, t);
   
-  CLUTTER_NOTE (BEHAVIOUR, "advancing to relative pt %f: t %f, {%d,%d}",
+  CLUTTER_NOTE (MISC, "advancing to relative pt %f: t %f, {%d,%d}",
                 (double) L / (double) CBZ_T_ONE,
                 (double) t / (double) CBZ_T_ONE,
                 knot->x, knot->y);
diff --git a/clutter/clutter-debug.h b/clutter/clutter-debug.h
index 88b7fcec3..9cd02b2e0 100644
--- a/clutter/clutter-debug.h
+++ b/clutter/clutter-debug.h
@@ -13,21 +13,18 @@ typedef enum {
   CLUTTER_DEBUG_TEXTURE             = 1 << 2,
   CLUTTER_DEBUG_EVENT               = 1 << 3,
   CLUTTER_DEBUG_PAINT               = 1 << 4,
-  CLUTTER_DEBUG_GL                  = 1 << 5,
-  CLUTTER_DEBUG_ALPHA               = 1 << 6,
-  CLUTTER_DEBUG_BEHAVIOUR           = 1 << 7,
-  CLUTTER_DEBUG_PANGO               = 1 << 8,
-  CLUTTER_DEBUG_BACKEND             = 1 << 9,
-  CLUTTER_DEBUG_SCHEDULER           = 1 << 10,
-  CLUTTER_DEBUG_SCRIPT              = 1 << 11,
-  CLUTTER_DEBUG_SHADER              = 1 << 12,
-  CLUTTER_DEBUG_MULTISTAGE          = 1 << 13,
-  CLUTTER_DEBUG_ANIMATION           = 1 << 14,
-  CLUTTER_DEBUG_LAYOUT              = 1 << 15,
-  CLUTTER_DEBUG_PICK                = 1 << 16,
-  CLUTTER_DEBUG_EVENTLOOP           = 1 << 17,
-  CLUTTER_DEBUG_CLIPPING            = 1 << 18,
-  CLUTTER_DEBUG_OOB_TRANSFORMS      = 1 << 19
+  CLUTTER_DEBUG_PANGO               = 1 << 5,
+  CLUTTER_DEBUG_BACKEND             = 1 << 6,
+  CLUTTER_DEBUG_SCHEDULER           = 1 << 7,
+  CLUTTER_DEBUG_SCRIPT              = 1 << 8,
+  CLUTTER_DEBUG_SHADER              = 1 << 9,
+  CLUTTER_DEBUG_MULTISTAGE          = 1 << 10,
+  CLUTTER_DEBUG_ANIMATION           = 1 << 11,
+  CLUTTER_DEBUG_LAYOUT              = 1 << 12,
+  CLUTTER_DEBUG_PICK                = 1 << 13,
+  CLUTTER_DEBUG_EVENTLOOP           = 1 << 14,
+  CLUTTER_DEBUG_CLIPPING            = 1 << 15,
+  CLUTTER_DEBUG_OOB_TRANSFORMS      = 1 << 16
 } ClutterDebugFlag;
 
 typedef enum {
diff --git a/clutter/clutter-main.c b/clutter/clutter-main.c
index d31b44485..128a30766 100644
--- a/clutter/clutter-main.c
+++ b/clutter/clutter-main.c
@@ -163,15 +163,11 @@ static const GDebugKey clutter_debug_keys[] = {
   { "event", CLUTTER_DEBUG_EVENT },
   { "paint", CLUTTER_DEBUG_PAINT },
   { "pick", CLUTTER_DEBUG_PICK },
-  { "gl", CLUTTER_DEBUG_GL },
-  { "alpha", CLUTTER_DEBUG_ALPHA },
-  { "behaviour", CLUTTER_DEBUG_BEHAVIOUR },
   { "pango", CLUTTER_DEBUG_PANGO },
   { "backend", CLUTTER_DEBUG_BACKEND },
   { "scheduler", CLUTTER_DEBUG_SCHEDULER },
   { "script", CLUTTER_DEBUG_SCRIPT },
   { "shader", CLUTTER_DEBUG_SHADER },
-  { "multistage", CLUTTER_DEBUG_MULTISTAGE },
   { "animation", CLUTTER_DEBUG_ANIMATION },
   { "layout", CLUTTER_DEBUG_LAYOUT },
   { "clipping", CLUTTER_DEBUG_CLIPPING },
diff --git a/clutter/deprecated/clutter-behaviour-depth.c b/clutter/deprecated/clutter-behaviour-depth.c
index 28eb3c058..fd329b52c 100644
--- a/clutter/deprecated/clutter-behaviour-depth.c
+++ b/clutter/deprecated/clutter-behaviour-depth.c
@@ -91,7 +91,7 @@ clutter_behaviour_depth_alpha_notify (ClutterBehaviour *behaviour,
   depth = (alpha_value * (priv->depth_end - priv->depth_start))
         + priv->depth_start;
 
-  CLUTTER_NOTE (BEHAVIOUR, "alpha: %.4f, depth: %d", alpha_value, depth);
+  CLUTTER_NOTE (ANIMATION, "alpha: %.4f, depth: %d", alpha_value, depth);
 
   clutter_behaviour_actors_foreach (behaviour,
                                     alpha_notify_foreach,
diff --git a/clutter/deprecated/clutter-behaviour-ellipse.c b/clutter/deprecated/clutter-behaviour-ellipse.c
index ab2cf60f8..ab05acab6 100644
--- a/clutter/deprecated/clutter-behaviour-ellipse.c
+++ b/clutter/deprecated/clutter-behaviour-ellipse.c
@@ -176,7 +176,7 @@ clutter_behaviour_ellipse_advance (ClutterBehaviourEllipse *e,
   knot->y = y;
   knot->z = z;
 
-  CLUTTER_NOTE (BEHAVIOUR, "advancing to angle %.2f [%d, %d] (a: %d, b: %d)",
+  CLUTTER_NOTE (ANIMATION, "advancing to angle %.2f [%d, %d] (a: %d, b: %d)",
                 angle,
                 knot->x, knot->y,
                 priv->a, priv->b);
diff --git a/clutter/deprecated/clutter-behaviour-opacity.c b/clutter/deprecated/clutter-behaviour-opacity.c
index 072b28fa1..bfd2f0cc8 100644
--- a/clutter/deprecated/clutter-behaviour-opacity.c
+++ b/clutter/deprecated/clutter-behaviour-opacity.c
@@ -97,7 +97,7 @@ clutter_behaviour_alpha_notify (ClutterBehaviour *behave,
             * (priv->opacity_end - priv->opacity_start)
             + priv->opacity_start;
 
-  CLUTTER_NOTE (BEHAVIOUR, "alpha: %.4f, opacity: %u",
+  CLUTTER_NOTE (ANIMATION, "alpha: %.4f, opacity: %u",
                 alpha_value,
                 opacity);
 
diff --git a/clutter/deprecated/clutter-behaviour-path.c b/clutter/deprecated/clutter-behaviour-path.c
index 48ada7ed8..69e94d7e4 100644
--- a/clutter/deprecated/clutter-behaviour-path.c
+++ b/clutter/deprecated/clutter-behaviour-path.c
@@ -128,7 +128,7 @@ actor_apply_knot_foreach (ClutterBehaviour *behaviour,
 {
   ClutterKnot *knot = data;
 
-  CLUTTER_NOTE (BEHAVIOUR, "Setting actor to %ix%i", knot->x, knot->y);
+  CLUTTER_NOTE (ANIMATION, "Setting actor to %ix%i", knot->x, knot->y);
 
   clutter_actor_set_position (actor, knot->x, knot->y);
 }
diff --git a/clutter/deprecated/clutter-behaviour.c b/clutter/deprecated/clutter-behaviour.c
index 1cbdbe742..c79e53284 100644
--- a/clutter/deprecated/clutter-behaviour.c
+++ b/clutter/deprecated/clutter-behaviour.c
@@ -518,17 +518,17 @@ notify_cb (GObject          *object,
 
   klass = CLUTTER_BEHAVIOUR_GET_CLASS (behave);
 
-  CLUTTER_NOTE (BEHAVIOUR, "notify::alpha");
+  CLUTTER_NOTE (ANIMATION, "notify::alpha");
 
   /* no actors, we can stop right here */
   if (behave->priv->actors == NULL)
     return;
 
-  if (klass->alpha_notify)
+  if (klass->alpha_notify != NULL)
     {
       gdouble alpha_value = clutter_alpha_get_alpha (behave->priv->alpha);
 
-      CLUTTER_NOTE (BEHAVIOUR, "calling %s::alpha_notify (%p, %.4f)",
+      CLUTTER_NOTE (ANIMATION, "calling %s::alpha_notify (%p, %.4f)",
                     g_type_name (G_TYPE_FROM_CLASS (klass)),
                     behave, alpha_value);
 
@@ -571,7 +571,7 @@ clutter_behaviour_set_alpha (ClutterBehaviour *behave,
 
   if (priv->notify_id)
     {
-      CLUTTER_NOTE (BEHAVIOUR, "removing previous notify-id (%d)",
+      CLUTTER_NOTE (ANIMATION, "removing previous notify-id (%d)",
                     priv->notify_id);
 
       g_signal_handler_disconnect (priv->alpha, priv->notify_id);
@@ -580,7 +580,7 @@ clutter_behaviour_set_alpha (ClutterBehaviour *behave,
 
   if (priv->alpha != NULL)
     {
-      CLUTTER_NOTE (BEHAVIOUR, "removing previous alpha object");
+      CLUTTER_NOTE (ANIMATION, "removing previous alpha object");
 
       g_object_unref (priv->alpha);
       priv->alpha = NULL;
@@ -594,7 +594,7 @@ clutter_behaviour_set_alpha (ClutterBehaviour *behave,
                                           G_CALLBACK(notify_cb),
                                           behave);
       
-      CLUTTER_NOTE (BEHAVIOUR, "setting new alpha object (%p, notify:%d)",
+      CLUTTER_NOTE (ANIMATION, "setting new alpha object (%p, notify:%d)",
                     priv->alpha, priv->notify_id);
     }
 
diff --git a/clutter/wayland/clutter-backend-wayland.c b/clutter/wayland/clutter-backend-wayland.c
index c21b81a11..56c23a251 100644
--- a/clutter/wayland/clutter-backend-wayland.c
+++ b/clutter/wayland/clutter-backend-wayland.c
@@ -401,7 +401,7 @@ try_create_context (ClutterBackend  *backend,
           goto fail;
         }
 
-      CLUTTER_NOTE (GL, "Created EGL Context");
+      CLUTTER_NOTE (BACKEND, "Created EGL Context");
     }
 
   if (!eglMakeCurrent (backend_wayland->edpy,
diff --git a/clutter/win32/clutter-event-win32.c b/clutter/win32/clutter-event-win32.c
index 287495ee3..197f665ad 100644
--- a/clutter/win32/clutter-event-win32.c
+++ b/clutter/win32/clutter-event-win32.c
@@ -440,8 +440,8 @@ clutter_win32_handle_event (const MSG *msg)
       break;
 
     case WM_PAINT:
-      CLUTTER_NOTE (MULTISTAGE, "expose for stage:%p, redrawing", stage);
-      clutter_redraw (stage);
+      CLUTTER_NOTE (BACKEND, "expose for stage:%p, redrawing", stage);
+      clutter_stage_ensure_redraw (stage);
       break;
 
     case WM_DESTROY:

From be4007ef53acce84dbb7b90be7f06eab1b845bc6 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@linux.intel.com>
Date: Mon, 17 Oct 2011 10:25:07 +0100
Subject: [PATCH 2/4] Remove mentions of clutter_redraw()

---
 clutter/clutter-actor.c        | 14 ++++++++------
 clutter/clutter-main.c         |  2 +-
 clutter/clutter-master-clock.c |  4 ++--
 3 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/clutter/clutter-actor.c b/clutter/clutter-actor.c
index 95b9a7b97..87aba079a 100644
--- a/clutter/clutter-actor.c
+++ b/clutter/clutter-actor.c
@@ -4832,23 +4832,25 @@ clutter_actor_class_init (ClutterActorClass *klass)
    * The default implementation for #ClutterActor chains up to the
    * parent actor and queues a redraw on the parent, thus "bubbling"
    * the redraw queue up through the actor graph. The default
-   * implementation for #ClutterStage queues a clutter_redraw() in a
-   * main loop idle handler.
+   * implementation for #ClutterStage queues a clutter_stage_ensure_redraw()
+   * in a main loop idle handler.
    *
    * Note that the @origin actor may be the stage, or a container; it
    * does not have to be a leaf node in the actor graph.
    *
    * Toolkits embedding a #ClutterStage which require a redraw and
    * relayout cycle can stop the emission of this signal using the
-   * GSignal API, redraw the UI and then call clutter_redraw()
+   * GSignal API, redraw the UI and then call clutter_stage_ensure_redraw()
    * themselves, like:
    *
    * |[
    *   static void
-   *   on_redraw_complete (void)
+   *   on_redraw_complete (gpointer data)
    *   {
+   *     ClutterStage *stage = data;
+   *
    *     /&ast; execute the Clutter drawing pipeline &ast;/
-   *     clutter_redraw ();
+   *     clutter_stage_ensure_redraw (stage);
    *   }
    *
    *   static void
@@ -4860,7 +4862,7 @@ clutter_actor_class_init (ClutterActorClass *klass)
    *     /&ast; queue a redraw with the host toolkit and call
    *      &ast; a function when the redraw has been completed
    *      &ast;/
-   *     queue_a_redraw (G_CALLBACK (on_redraw_complete));
+   *     queue_a_redraw (G_CALLBACK (on_redraw_complete), stage);
    *   }
    * ]|
    *
diff --git a/clutter/clutter-main.c b/clutter/clutter-main.c
index 128a30766..7d4d8159a 100644
--- a/clutter/clutter-main.c
+++ b/clutter/clutter-main.c
@@ -3329,7 +3329,7 @@ clutter_threads_add_repaint_func (GSourceFunc    func,
  * Executes the repaint functions added using the
  * clutter_threads_add_repaint_func() function.
  *
- * Must be called before calling clutter_redraw() and
+ * Must be called before calling _clutter_stage_do_paint() and
  * with the Clutter thread lock held.
  */
 void
diff --git a/clutter/clutter-master-clock.c b/clutter/clutter-master-clock.c
index ce8d70bc2..21a86d579 100644
--- a/clutter/clutter-master-clock.c
+++ b/clutter/clutter-master-clock.c
@@ -532,8 +532,8 @@ _clutter_master_clock_start_running (ClutterMasterClock *master_clock)
  * @master_clock: a #ClutterMasterClock
  *
  * Advances all the timelines held by the master clock. This function
- * should be called before calling clutter_redraw() to make sure that
- * all the timelines are advanced and the scene is updated.
+ * should be called before calling _clutter_stage_do_update() to
+ * make sure that all the timelines are advanced and the scene is updated.
  */
 void
 _clutter_master_clock_advance (ClutterMasterClock *master_clock)

From 3cc62523e6121a8e8316a578246da4db737f4a41 Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@linux.intel.com>
Date: Mon, 17 Oct 2011 10:25:20 +0100
Subject: [PATCH 3/4] docs: Clean up the 'running Clutter apps' chapter

---
 doc/reference/clutter/running-clutter.xml | 20 +++++++++++---------
 1 file changed, 11 insertions(+), 9 deletions(-)

diff --git a/doc/reference/clutter/running-clutter.xml b/doc/reference/clutter/running-clutter.xml
index 94cd2cd66..73b1d34bf 100644
--- a/doc/reference/clutter/running-clutter.xml
+++ b/doc/reference/clutter/running-clutter.xml
@@ -60,13 +60,20 @@
         <varlistentry>
           <term>CLUTTER_DEBUG</term>
           <listitem>
-            <para>Enables debugging modes for Clutter.</para>
+            <para>Enables debugging modes for Clutter; debugging modes are
+            used to print debugging messages on the console. Clutter must be
+            compiled with the --enable-debug configuration switch for these
+            messages to be printed out. Multiple debugging modes can be
+            enabled by separating them using a colon (":") or a comma
+            (",").</para>
           </listitem>
         </varlistentry>
         <varlistentry>
-          <term>COGL_DEBUG</term>
+          <term>CLUTTER_PAINT</term>
           <listitem>
-            <para>Enables debugging modes for Cogl.</para>
+            <para>Enables paint debugging modes for Clutter; the modes change
+            the way Clutter paints a scene and are useful for debugging the
+            behaviour of the paint cycle.</para>
           </listitem>
         </varlistentry>
       </variablelist>
@@ -177,7 +184,7 @@
 
       <para>The debugging flags can be used for the CLUTTER_DEBUG environment
       variable and the --clutter-debug command line switch. Multiple flags can
-      be separated by a colon (:).</para>
+      be separated by a colon (:) or a comma (,).</para>
 
       <!--
       keep in sync with the list of Clutter debug keys inside clutter-main.c
@@ -196,11 +203,6 @@
           <listitem><para>Backend-related notes, including initialization of
           the backend features and GL context creation</para></listitem>
         </varlistentry>
-        <varlistentry>
-          <term>behaviour</term>
-          <listitem><para>#ClutterBehaviour notes</para></listitem>
-        </varlistentry>
-        <varlistentry>
           <term>event</term>
           <listitem><para>Event handling notes</para></listitem>
         </varlistentry>

From 8083dd51786492237355003278208824cf99edcb Mon Sep 17 00:00:00 2001
From: Emmanuele Bassi <ebassi@linux.intel.com>
Date: Mon, 17 Oct 2011 11:48:47 +0100
Subject: [PATCH 4/4] docs: Improve documentation of LayoutManager

Especially with regards to layout properties and their usage inside a
ClutterScript UI definition.
---
 clutter/clutter-layout-manager.c | 103 ++++++++++++++++++++++---------
 1 file changed, 74 insertions(+), 29 deletions(-)

diff --git a/clutter/clutter-layout-manager.c b/clutter/clutter-layout-manager.c
index 9f17f52b2..70bcecc7b 100644
--- a/clutter/clutter-layout-manager.c
+++ b/clutter/clutter-layout-manager.c
@@ -75,38 +75,10 @@
  *   <function>set_container()</function> virtual function. The layout manager
  *   should not hold a real reference (i.e. call g_object_ref()) on the
  *   container actor, to avoid reference cycles.</para>
- *   <para>If the layout manager has properties affecting the layout
+ *   <para>If a layout manager has properties affecting the layout
  *   policies then it should emit the #ClutterLayoutManager::layout-changed
  *   signal on itself by using the clutter_layout_manager_layout_changed()
  *   function whenever one of these properties changes.</para>
- *   <para>If the layout manager has layout properties, that is properties that
- *   should exist only as the result of the presence of a specific (layout
- *   manager, container actor, child actor) combination, and it wishes to store
- *   those properties inside a #ClutterLayoutMeta then it should override the
- *   <structname>ClutterLayoutManager</structname>::get_child_meta_type()
- *   virtual function to return the #GType of the #ClutterLayoutMeta sub-class
- *   used to store the layout properties; optionally, the #ClutterLayoutManager
- *   sub-class might also override the
- *   <structname>ClutterLayoutManager</structname>::create_child_meta() virtual
- *   function to control how the #ClutterLayoutMeta instance is created,
- *   otherwise the default implementation will be equivalent to:</para>
- *   <informalexample><programlisting>
- *  ClutterLayoutManagerClass *klass;
- *  GType meta_type;
- *
- *  klass = CLUTTER_LAYOUT_MANAGER_GET_CLASS (manager);
- *  meta_type = klass->get_child_meta_type (manager);
- *
- *  return g_object_new (meta_type,
- *                       "manager", manager,
- *                       "container", container,
- *                       "actor", actor,
- *                       NULL);
- *   </programlisting></informalexample>
- *   <para>Where <varname>manager</varname> is the  #ClutterLayoutManager,
- *   <varname>container</varname> is the #ClutterContainer using the
- *   #ClutterLayoutManager and <varname>actor</varname> is the #ClutterActor
- *   child of the #ClutterContainer.</para>
  * </refsect2>
  *
  * <refsect2 id="ClutterLayoutManager-animation">
@@ -279,6 +251,79 @@
  *   <varname>orientation</varname> layout property of a layout manager.</para>
  * </refsect2>
  *
+ * <refsect2 id="clutter-layout-properties">
+ *   <title>Layout Properties</title>
+ *   <para>If a layout manager has layout properties, that is properties that
+ *   should exist only as the result of the presence of a specific (layout
+ *   manager, container actor, child actor) combination, and it wishes to store
+ *   those properties inside a #ClutterLayoutMeta, then it should override the
+ *   <structname>ClutterLayoutManager</structname>::get_child_meta_type()
+ *   virtual function to return the #GType of the #ClutterLayoutMeta sub-class
+ *   used to store the layout properties; optionally, the #ClutterLayoutManager
+ *   sub-class might also override the
+ *   <structname>ClutterLayoutManager</structname>::create_child_meta() virtual
+ *   function to control how the #ClutterLayoutMeta instance is created,
+ *   otherwise the default implementation will be equivalent to:</para>
+ *   <informalexample><programlisting>
+ *  ClutterLayoutManagerClass *klass;
+ *  GType meta_type;
+ *
+ *  klass = CLUTTER_LAYOUT_MANAGER_GET_CLASS (manager);
+ *  meta_type = klass->get_child_meta_type (manager);
+ *
+ *  return g_object_new (meta_type,
+ *                       "manager", manager,
+ *                       "container", container,
+ *                       "actor", actor,
+ *                       NULL);
+ *   </programlisting></informalexample>
+ *   <para>Where <varname>manager</varname> is the  #ClutterLayoutManager,
+ *   <varname>container</varname> is the #ClutterContainer using the
+ *   #ClutterLayoutManager and <varname>actor</varname> is the #ClutterActor
+ *   child of the #ClutterContainer.</para>
+ * </refsect2>
+ *
+ * <refsect2 id="clutter-layout-script">
+ *   <title>Using ClutterLayoutManager with ClutterScript</title>
+ *   <para>#ClutterLayoutManager instance can be created in the same way
+ *   as other objects in #ClutterScript; properties can be set using the
+ *   common syntax.</para>
+ *   <para>Layout properties can be set on children of a container with
+ *   a #ClutterLayoutManager using the <emphasis>layout::</emphasis>
+ *   modifier on the property name, for instance:</para>
+ *   <informalexample><programlisting>
+ * {
+ *   "type" : "ClutterBox",
+ *   "layout-manager" : { "type" : "ClutterTableLayout" },
+ *   "children" : [
+ *     {
+ *       "type" : "ClutterTexture",
+ *       "filename" : "image-00.png",
+ *
+ *       "layout::row" : 0,
+ *       "layout::column" : 0,
+ *       "layout::x-align" : "left",
+ *       "layout::y-align" : "center",
+ *       "layout::x-expand" : true,
+ *       "layout::y-expand" : true
+ *     },
+ *     {
+ *       "type" : "ClutterTexture",
+ *       "filename" : "image-01.png",
+ *
+ *       "layout::row" : 0,
+ *       "layout::column" : 1,
+ *       "layout::x-align" : "right",
+ *       "layout::y-align" : "center",
+ *       "layout::x-expand" : true,
+ *       "layout::y-expand" : true
+ *     }
+ *   ]
+ * }
+ *   </programlisting></informalexample>
+ *
+ * </refsect2>
+ *
  * #ClutterLayoutManager is available since Clutter 1.2
  */