From 58f1dfcf35626b8b1ea896dfbd27623b15779fce Mon Sep 17 00:00:00 2001
From: Joshua Lock <josh@linux.intel.com>
Date: Thu, 5 Nov 2009 15:31:56 +0000
Subject: [PATCH] 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 | 75 ++++++++++++----------
 1 file changed, 41 insertions(+), 34 deletions(-)

diff --git a/doc/reference/clutter/building-clutter.xml b/doc/reference/clutter/building-clutter.xml
index 09def99c3..cf6c0a37b 100644
--- a/doc/reference/clutter/building-clutter.xml
+++ b/doc/reference/clutter/building-clutter.xml
@@ -237,24 +237,41 @@
       </section>
 
       <section id='building-osx'>
-          <title>OSX</title>
-	  <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>
-
-          <informalexample><programlisting>
-            $ sudo port install pango libpixman-devel cairo-devel
-          </programlisting></informalexample>
-
-          <para>on a terminal, after installing and updating MacPorts.
-	  This should give you all of the required dependencies for building
-	  Clutter 1.0.</para>
+        <title>OSX</title>
+          <para>
+            Before you start you should install XCode either from the OSX
+            installation disk or by downloading it from the Apple website.
+          </para>
 
           <para>
-            XCode should also be installed, either from the OSX installation
-            disk or downloading it from the Apple website.
+            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>
+
+          <informalexample><programlisting>
+            $ sudo port install libpixman-devel cairo-devel pango gtk-doc
+          </programlisting></informalexample>
+
+          <para>
+            on a terminal, after installing and updating MacPorts.
+            This should give you all of the required dependencies for building
+            Clutter.
+          </para>
+
+          <para>
+            It should be noted that building gtk-doc pulls in a lot of other
+            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,29 +285,19 @@
           </para>
 
           <para>
-            GTK-Doc is not working on OSX, so API reference generation
-            should also be disabled when building Clutter, by using
-            the <literal>--disable-docs</literal> and
-            <literal>--disable-gtk-doc</literal> command line argument
-            to the configure script.
+            GTK introspection is untested on OSX (as there isn't a MacPorts
+            package) so it is recommended that you disable this with the
+            <literal>--disable-introspection</literal>.
           </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>
-
-	  <para>
-	    If building on top of MacPorts, as recommended, the following
-	    configure command should suffice:
+          <para>
+            If building on top of MacPorts, as recommended, the following
+            configure command should suffice:
           </para>
 
           <informalexample><programlisting>
-	    ./configure --disable-gtk-doc --disable-docs --disable-shave
-	    --with-flavour=osx --disable-introspection --prefix=/opt
-	  </programlisting></informalexample>
+            ./configure --with-flavour=osx --disable-introspection --prefix=/opt
+          </programlisting></informalexample>
       </section>
 
     </section>