diff --git a/doc/cookbook/clutter-cookbook.xml.in b/doc/cookbook/clutter-cookbook.xml.in
index ade193535..3bd710821 100644
--- a/doc/cookbook/clutter-cookbook.xml.in
+++ b/doc/cookbook/clutter-cookbook.xml.in
@@ -44,6 +44,7 @@
+ Contributing to this document
diff --git a/doc/cookbook/layouts.xml b/doc/cookbook/layouts.xml
new file mode 100644
index 000000000..73899248b
--- /dev/null
+++ b/doc/cookbook/layouts.xml
@@ -0,0 +1,281 @@
+
+
+
+
+ Layout management
+
+
+ who
+ what they said
+
+
+
+ Introduction
+
+ Layout management in Clutter controls how an actor and
+ children "inside" that actor are sized and positioned. More
+ specifically, layouts are managed by associating a parent with a
+ ClutterLayoutManager; the parent is usually either a
+ composite ClutterActor (composed of several
+ ClutterActors) or a ClutterContainer
+ (containing child ClutterActors). The
+ ClutterLayoutManager then manages:
+
+
+
+ The size requisition
+ (determination of the desired height and width) of the
+ parent.
+
+
+ The allocation (size and position)
+ assigned to each composed or child ClutterActor.
+
+
+
+ The following sections give a brief overview of how layout
+ management works in Clutter.
+
+
+ Using layouts
+
+ Although Clutter provides plenty of flexibility in how you
+ can use layout management, the simplest way to get started is to
+ use the built-in ClutterBox class with one of the
+ provided ClutterLayoutManager implementations.
+
+ The pattern for doing this is:
+
+
+
+ Create an instance of one of the
+ ClutterLayoutManager implementations (see
+ the
+ following section).
+
+
+ Configure the layout manager's default policies
+ (e.g. how actors are aligned by default, whether to pack
+ actors horizontally or vertically, spacing between actors
+ in the layout).
+
+
+ Create a ClutterBox, setting its layout
+ manager to the one you just created.
+
+
+ Pack actors into the ClutterBox,
+ setting layout properties (if required) as each is added.
+
+
+ Modify layout properties of child actors using
+ clutter_layout_manager_child_set()
+ (if required).
+
+
+
+ Individual recipes in this section give more examples of
+ how to make use of the different layout manager
+ implementations.
+
+
+
+
+ Types of layout manager
+
+ Clutter provides a range of layout managers suitable
+ for different use cases:
+
+
+
+ ClutterFixedLayout arranges actors
+ at fixed positions on the stage. No alignment options are
+ available, so you have to manually compute and manage the
+ coordinates (or use ClutterConstraints) which
+ will align actors how you want them.
+
+
+ ClutterBinLayout arranges actors in a
+ depth-ordered stack on top of each other, aligned to the container.
+ This is useful for arranging actors inside composites (e.g.
+ creating a button widget from a ClutterTexture
+ with a ClutterText on top of it).
+
+
+ ClutterBoxLayout arranges actors in a
+ single horizontal row or vertical column. This type of layout is
+ common in UI elements like toolbars and menus.
+
+
+ ClutterFlowLayout arranges actors
+ in reflowing columns and rows. If the container's allocation
+ changes, the child actors are rearranged to fit inside its
+ new allocation. This can be useful for arranging actors
+ where you're not sure how many there might be; or where
+ new ones are going to be added into the UI, perhaps displacing
+ others. An example might be a photo viewer or an
+ RSS feed display.
+
+
+
+
+
+
+ Layout properties
+
+ How actors are sized and positioned inside a container
+ associated with a layout manager depends on two things:
+
+
+
+
+ Properties which apply to all actors added to the layout
+ There will be one setting at the layout level which can't
+ be overridden per actor. This includes properties like spacing
+ between rows and columns, whether the layout is homogenous
+ (each actor gets the same allocation), etc.
+
+
+
+
+ Properties for each actor added to the layout
+ These are properties of the relationship between the
+ layout, the container associated with the layout, and the
+ children of the container. Each layout/container/actor
+ combination can have different settings for each of these
+ properties.
+
+
+
+
+ Each layout manager implementation supports a subset of the
+ following layout properties; different managers may have different
+ names or functions for setting them, but the functionality remains
+ the same. Individual recipes give more details about which
+ properties can be set for each layout manager implementation.
+
+
+
+
+ Alignment
+ How an actor aligns to the container's axes, e.g.
+ aligned to the container's left, right, or center.
+
+
+
+
+ Horizontal/vertical orientation
+ Whether actors are arranged in a horizontal row or
+ vertical column.
+
+
+
+
+ Homogenous rows and columns
+ Grid-like layouts (e.g. ClutterFlowLayout)
+ can be configured to have uniform rows and/or columns,
+ expanding to fit the largest actor they contain.
+
+
+
+
+ Row height and column width
+ Grid-like layouts arranged in rows and columns
+ can be configured with maximum and minimum row height and
+ column width.
+
+
+
+
+ Row and column spacing
+ Grid-like layouts enable you to define a space (in pixels)
+ between rows and columns.
+
+
+
+
+ Expand
+ Some layouts can be configured to minimize their size request
+ to fit the actors they contain (expand is FALSE);
+ or to increase the allocation of actors they contain so
+ that all available space in the layout is used
+ (expand is TRUE). In the latter case, you'd
+ also need to set a size for the container associated with
+ the layout, otherwise the container will just fit itself to the
+ actors inside it.
+
+
+
+
+ Fill
+ This property only has an effect when
+ expand is on. The fill
+ setting controls whether actors are resized to fill their
+ allocation (fill is TRUE); or if the
+ space around the actor is increased (fill is
+ FALSE).
+
+
+
+
+ Pack at start/end
+ This controls whether actors at prepended or appended
+ to the layout.
+
+
+ If the orientation is vertical, prepended
+ actors are added to the top of the layout and appended
+ actors to the bottom.
+
+
+ If the orientation is horizontal, prepended
+ actors are added at the left of the layout and appended actors
+ on the right.
+
+
+
+
+
+
+
+ Setting layout properties
+
+ Layout properties can be set in one or more of the following ways
+ (depending on the type of property and the layout manager):
+
+
+
+ By setting a default value for the property on the
+ layout manager (e.g. using
+ clutter_bin_layout_set_alignment(),
+ clutter_box_layout_set_expand()). Any
+ actor added to the layout gets this value for the property,
+ unless it is overridden for that actor.
+
+
+ When adding an actor to a ClutterBox container
+ using clutter_box_pack(), you can set
+ properties on the actor which you're adding.
+
+
+ When adding an actor to a layout you can use a function
+ which enables setting properties simultaneously (e.g.
+ clutter_box_layout_pack(),
+ clutter_bin_layout_add()).
+
+
+ By using
+ clutter_layout_manager_child_set() on
+ the child of a layout.
+
+
+
+
+
+
+
+
+
+