diff --git a/doc/reference/ChangeLog b/doc/reference/ChangeLog
index bea05a480..3f3f519a3 100644
--- a/doc/reference/ChangeLog
+++ b/doc/reference/ChangeLog
@@ -1,3 +1,11 @@
+2008-06-06  Emmanuele Bassi  <ebassi@openedhand.com>
+
+	Bug #927 - Created ports for clutter, clutter-cairo in macports
+
+	* clutter/clutter-docs.sgml: Update the OSX build instructions
+	and mention that the preferred way to build Clutter for developing
+	applications is via MacPorts. (#927, Idan Gazit)
+
 2008-05-15  Emmanuele Bassi  <ebassi@openedhand.com>
 
 	* clutter/clutter-sections.txt: Update with new symbols.
diff --git a/doc/reference/clutter/clutter-docs.sgml b/doc/reference/clutter/clutter-docs.sgml
index 3ec0a6349..9586b4407 100644
--- a/doc/reference/clutter/clutter-docs.sgml
+++ b/doc/reference/clutter/clutter-docs.sgml
@@ -279,11 +279,20 @@
 
       <section id='building-osx'>
           <title>OSX</title>
-          <para>The recommended way of building Clutter on OSX is to use
-            <ulink href="http://live.gnome.org/Jhbuild">Jhbuild</ulink>,
-            following the documentation for building the GTK+ stack as shown
-            <ulink href="http://developer.imendio.com/projects/gtk-macosx/build-instructions">here</ulink>.
-          </para>
+          <para>For developing an application with Clutter, the recommended
+          way of installing it using the <ulink href="http://www.macports.org/">MacPorts</ulink>
+          project, by simply invoking:</para>
+
+          <informalexample><programlisting>
+            $ sudo port install clutter
+          </programlisting></informalexample>
+
+          <para>on a terminal, after installing and updating MacPorts.</para>
+
+          <para>For developing Clutter itself, the recommended way of building
+          it OSX is to use <ulink href="http://live.gnome.org/Jhbuild">Jhbuild</ulink>,
+          following the documentation for building the GTK+ stack as shown
+          <ulink href="http://developer.imendio.com/projects/gtk-macosx/build-instructions">here</ulink>.</para>
 
           <para>
             Jhbuild depends on SVN, which can be installed on OSX by using
@@ -293,16 +302,19 @@
 
           <para>
             XCode should also be installed, either from the OSX installation
-            disk or downloading it from the Apple website.
+            disk or downloading it from the Apple website. It is recommended
+            to also install the X11 development files, even though Clutter
+            does not strictly depend on them.
           </para>
 
           <para>
-            Due to Clutter's dependency on GDK-Pixbuf, GTK+ for OSX must
-            also be built. After building GTK+, extract the files from
-            Clutter's release tar archive or check out the project from
-            SVN. Clutter OSX backend is built by passing the
+            The Clutter Quartz backend is built by passing the
             <literal>--with-flavour=osx</literal> command line argument
-            to the configure script.
+            to the configure script. If not passed, the GLX backend will
+            be built. By default, the Quartz backend depends on CoreGraphics
+            in order to load images into textures, but it can also depend
+            on GDK-Pixbuf or an internal, highly experimental PNG and JPEG
+            loader.
           </para>
 
           <para>