docs: Fix OS X docs to install Ports in correct order

The order in which the MacPorts are installed is important otherwise we open
the user up to a world of pain.
This patch also tweaks the OS X docs to follow the formatting of the rest of
the docs and to discuss the option of GtkDoc.

http://bugzilla.openedhand.com/show_bug.cgi?id=1865

doc/reference/clutter/building-clutter.xml

@@ -238,23 +238,40 @@
 
       <section id='building-osx'>
         <title>OSX</title>
-	  <para>Currently the only way to install Clutter for developing
+          <para>
+            Before you start you should install XCode either from the OSX
+            installation disk or by downloading it from the Apple website.
+          </para>
+
+          <para>
+            Note: These instructions have only been tested on OS X 10.6
+            (a.k.a Snow Leopard)
+          </para>
+
+          <para>
+            Currently the only way to install Clutter for developing
             applications, or hacking on Clutter itself, is to build it yourself.
             The recommended route is to install the dependencies with
             the <ulink href="http://www.macports.org/">MacPorts</ulink>
-          project, by simply invoking:</para>
+            project, by simply invoking:
+          </para>
 
           <informalexample><programlisting>
-            $ sudo port install pango libpixman-devel cairo-devel
+            $ sudo port install libpixman-devel cairo-devel pango gtk-doc
           </programlisting></informalexample>
 
-          <para>on a terminal, after installing and updating MacPorts.
+          <para>
+            on a terminal, after installing and updating MacPorts.
             This should give you all of the required dependencies for building
-	  Clutter 1.0.</para>
+            Clutter.
+          </para>
 
           <para>
-            XCode should also be installed, either from the OSX installation
+            It should be noted that building gtk-doc pulls in a lot of other
-            disk or downloading it from the Apple website.
+            MacPorts dependencies and takes some considerable time. You can omit
+            this dependency so long as you disable documentation when you are
+            configuring the build with
+            <literal>--disable-gtk-doc --disable-docs</literal>
           </para>
 
           <para>
@@ -268,17 +285,8 @@
           </para>
 
           <para>
-            GTK-Doc is not working on OSX, so API reference generation
+            GTK introspection is untested on OSX (as there isn't a MacPorts
-            should also be disabled when building Clutter, by using
+            package) so it is recommended that you disable this with the
-            the <literal>--disable-docs</literal> and
-            <literal>--disable-gtk-doc</literal> command line argument
-            to the configure script.
-          </para>
-
-	  <para>
-	    GTK introspection and shave support are untested on OSX so it is
-	    also recommended that you disable these with the
-	    <literal>--disable-shave</literal> and
             <literal>--disable-introspection</literal>.
           </para>
 
@@ -288,8 +296,7 @@
           </para>
 
           <informalexample><programlisting>
-	    ./configure --disable-gtk-doc --disable-docs --disable-shave
+            ./configure --with-flavour=osx --disable-introspection --prefix=/opt
-	    --with-flavour=osx --disable-introspection --prefix=/opt
           </programlisting></informalexample>
       </section>