Improve documentation on backends

9 files changed, 161 insertions, 111 deletions

diff --git a/docs/users_guide/codegens.xml b/docs/users_guide/codegens.xml
index b63c4d8b56..f854e1137e 100644
--- a/docs/users_guide/codegens.xml
+++ b/docs/users_guide/codegens.xml
@@ -1,49 +1,117 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <sect1 id="code-generators">
   <title>GHC Backends</title>
-  <sect2 id="replacing-phases">
+  <indexterm><primary>ghc backends</primary></indexterm>
+  <indexterm><primary>ghc code generators</primary></indexterm>
   
-     <para>GHC supports multiple backend code-generators. This is the part
-        of the compiler responsible for taking the the last intermediate
-        representation that GHC uses and compiling it to executable code.
-        The supported backends are described below.
-     </para>
-
-     <sect3 id="native-code-gen">
-        <title>Native Code Generator (<option>-fasm</option>)</title>
-        This is the default backend used by GHC. It is a native code generator,
-        compiling all the way to assembly code. It is the fastest backend and
-        generally produces good performance code.  Select it with the
-        <option>-fasm</option> flag.
-     </sect3>
-
-     <sect3 id="llvm-code-gen">
-        <title>LLVM Code Generator (<option>-fllvm</option>)</title>
-        <para>This is an alternative backend that uses the
-           <ulink url="http://llvm.org">LLVM</ulink> compiler to produce
-           executable code.  It generally produces code as with performance as
-           good as the native code generator but for some cases can produce
-           much faster code. This is especially true for numeric, array heavy
-           code using packages like vector.
-        </para>
-          
-        <para>You must install and have LLVM available on your PATH for the
-           LLVM code generator to work. Specifically it needs to be able to
-           call the <literal>opt</literal>and <literal>llc</literal> tools.
-           Secondly, if you are running Mac OS X with LLVM 3.0 or greater then
-           you also need the
-           <ulink url="http://clang.llvm.org">Clang c compiler</ulink> compiler
-           available on your PATH. Clang and LLVM are both included with OS X
-           by default from 10.6 onwards.
-        </para>
-         
-     </sect3>
-
-     <sect3 id="c-code-gen">
-        <title>C Code Generator (<option>-fvia-C</option>)</title>
-
-     </sect3>
+  <para>GHC supports multiple backend code generators. This is the part
+    of the compiler responsible for taking the last intermediate
+    representation that GHC uses (a form called Cmm that is a simple, C like
+    language) and compiling it to executable code. The backends that GHC
+    support are described below.
+  </para>
 
+  <sect2 id="native-code-gen">
+    <title>Native code Generator (<option>-fasm</option>)</title>
+    <indexterm><primary>native code generator</primary></indexterm>
+
+    The default backend for GHC. It is a native code generator, compiling Cmm
+    all the way to assembly code. It is the fastest backend and generally
+    produces good performance code. It has the best support for compiling
+    shared libraries. Select it with the <option>-fasm</option> flag.
+  </sect2>
+
+  <sect2 id="llvm-code-gen">
+    <title>LLVM Code Generator (<option>-fllvm</option>)</title>
+    <indexterm><primary>LLVM code generator</primary></indexterm>
+
+    <para>This is an alternative backend that uses the
+      <ulink url="http://llvm.org">LLVM</ulink> compiler to produce
+      executable code. It generally produces code as with performance as
+      good as the native code generator but for some cases can produce
+      much faster code. This is especially true for numeric, array heavy
+      code using packages like vector. The penalty is a significant increase in
+      compilation times. Select the LLVM backend with the
+      <option>-fllvm</option> flag. Currently <emphasis>LLVM 2.8</emphasis> and
+      later are supported.
+    </para>
+       
+    <para>You must install and have LLVM available on your PATH for the LLVM
+      code generator to work. Specifically GHC needs to be able to call the
+      <command>opt</command>and <command>llc</command> tools.  Secondly, if you
+      are running Mac OS X with LLVM 3.0 or greater then
+      you also need the <ulink url="http://clang.llvm.org">Clang c
+        compiler</ulink> compiler available on your PATH. Clang and LLVM are
+      both included with OS X by default from 10.6 onwards.
+    </para>
+
+    <para>To install LLVM and Clang:
+      <itemizedlist>
+        <listitem><emphasis>Linux</emphasis>: Use your package management tool.
+        </listitem>
+        <listitem><emphasis>Mac OS X</emphasis>: LLVM and Clang are included by
+          default from <literal>10.6</literal> and later. For
+          <literal>10.5</literal> you should install the
+          <ulink url="http://mxcl.github.com/homebrew/">Homebrew</ulink> package
+          manager for OS X. Alternatively you can download binaries for LLVM
+          and Clang from
+          <ulink url="http://llvm.org/releases/download.html">here</ulink>.
+        </listitem>
+        <listitem><emphasis>Windows</emphasis>: You should download binaries for
+          LLVM and clang from
+          <ulink url="http://llvm.org/releases/download.html">here</ulink>.
+        </listitem>
+      </itemizedlist>
+    </para>
+  </sect2>
+
+  <sect2 id="c-code-gen">
+    <title>C Code Generator (<option>-fvia-C</option>)</title>
+    <indexterm><primary>C code generator</primary></indexterm>
+    <indexterm><primary>-fvia-C</primary></indexterm>
+
+    <para>This is the oldest code generator in GHC and is generally not included
+      any more having been deprecated around GHC 7.0. Select it with the
+      <option>-fvia-C</option> flag.
+    </para>
+
+    <para>The C code generator is only supported when GHC is built in
+      unregisterised mode, a mode where GHC produces 'portable' C code as
+      output to facilitate porting GHC itself to a new platform. This mode
+      produces much slower code though so it's unlikely your version of
+      GHC was built this way. If it has then the native code generator
+      probably won't be available. You can check this information by calling
+      <link linkend="ghc-info"><literal>ghc --info</literal></link>.
+    </para>
+  </sect2>
+
+  <sect2 id="unreg">
+    <title>Unregisterised compilation</title>
+    <indexterm><primary>unregisterised compilation</primary></indexterm>
+
+    <para>The term "unregisterised" really means "compile via vanilla C",
+      disabling some of the platform-specific tricks that GHC normally uses to
+      make programs go faster.  When compiling unregisterised, GHC simply
+      generates a C file which is compiled via gcc.</para>
+    
+    <para>When GHC is build in unregisterised mode only the LLVM and C code
+      generators will be available. The native code generator won't be. LLVM
+      usually offers a substantial performance benefit over the C backend in
+      unregisterised mode.</para>
+
+    <para>Unregisterised compilation can be useful when porting GHC to a new
+      machine, since it reduces the prerequisite tools to
+      <command>gcc</command>, <command>as</command>, and <command>ld</command>
+      and nothing more, and furthermore the amount of platform-specific code
+      that needs to be written in order to get
+    unregisterised compilation going is usually fairly small.</para>
+
+    <para>Unregisterised compilation cannot be selected at compile-time; you
+      have to build GHC with the appropriate options set.  Consult the GHC
+      Building Guide for details.</para>
+
+    <para>You can check if your GHC is unregisterised by calling
+      <link linkend="ghc-info"><literal>ghc --info</literal></link>.</para>
   </sect2>
 
 </sect1>
diff --git a/docs/users_guide/debugging.xml b/docs/users_guide/debugging.xml
index 2502d60249..003d2b5cd4 100644
--- a/docs/users_guide/debugging.xml
+++ b/docs/users_guide/debugging.xml
@@ -286,7 +286,8 @@
                 <indexterm><primary><option>-ddump-asm</option></primary></indexterm>
 	      </term>
 	      <listitem>
-		<para>assembly language from the native-code generator</para>
+            <para>assembly language from the
+              <link linkend="native-code-gen">native code generator</link></para>
 	      </listitem>
 	    </varlistentry>
 
@@ -296,7 +297,8 @@
                 <indexterm><primary><option>-ddump-llvm</option></primary></indexterm>
 	      </term>
 	      <listitem>
-		<para>LLVM code from the LLVM code generator</para>
+	        <para>LLVM code from the <link linkend="llvm-code-gen">LLVM code
+	          generator</link></para>
 	      </listitem>
 	    </varlistentry>
 
@@ -787,28 +789,6 @@ Main.skip2{-r1L6-} =
 
   </sect2>
 
-  <sect2 id="unreg">
-    <title>Unregisterised compilation</title>
-    <indexterm><primary>unregisterised compilation</primary></indexterm>
-
-    <para>The term "unregisterised" really means "compile via vanilla
-    C", disabling some of the platform-specific tricks that GHC
-    normally uses to make programs go faster.  When compiling
-    unregisterised, GHC simply generates a C file which is compiled
-    via gcc.</para>
-
-    <para>Unregisterised compilation can be useful when porting GHC to
-    a new machine, since it reduces the prerequisite tools to
-    <command>gcc</command>, <command>as</command>, and
-    <command>ld</command> and nothing more, and furthermore the amount
-    of platform-specific code that needs to be written in order to get
-    unregisterised compilation going is usually fairly small.</para>
-
-   <para>Unregisterised compilation cannot be selected at
-   compile-time; you have to build GHC with the appropriate options
-   set.  Consult the GHC Building Guide for details.</para>
-  </sect2>
-
 </sect1>
 
 <!-- Emacs stuff:
diff --git a/docs/users_guide/ffi-chap.xml b/docs/users_guide/ffi-chap.xml
index e6cf9edc92..678164136b 100644
--- a/docs/users_guide/ffi-chap.xml
+++ b/docs/users_guide/ffi-chap.xml
@@ -434,7 +434,8 @@ typedef enum {
 
       <para>GHC no longer includes external header files when
         compiling via C, so this checking is not performed.  The
-        change was made for compatibility with the native code backend
+        change was made for compatibility with the
+        <ulink linkend="native-code-gen">native code generator</ulink>
         (<literal>-fasm</literal>) and to comply strictly with the FFI
         specification, which requires that FFI calls are not subject
         to macro expansion and other CPP conversions that may be
diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml
index f4a8ba89d3..e554797740 100644
--- a/docs/users_guide/flags.xml
+++ b/docs/users_guide/flags.xml
@@ -1859,13 +1859,15 @@ phase <replaceable>n</replaceable></entry>
 	  <tbody>
 	    <row>
 	      <entry><option>-fasm</option></entry>
-	      <entry>Use the native code generator</entry>
+        <entry>Use the <link linkend="native-code-gen">native code
+            generator</link></entry>
 	      <entry>dynamic</entry>
 	      <entry>-fllvm</entry>
 	    </row>
 	    <row>
 	      <entry><option>-fllvm</option></entry>
-	      <entry>Compile via LLVM</entry>
+        <entry>Compile using the <link linkend="llvm-code-gen">LLVM code
+            generator</link></entry>
 	      <entry>dynamic</entry>
 	      <entry>-fasm</entry>
 	    </row>
@@ -2771,7 +2773,7 @@ phase <replaceable>n</replaceable></entry>
 	    </row>
 	    <row>
 	      <entry><option>-funregisterised</option></entry>
-	      <entry>Unregisterised compilation (use <option>-unreg</option> instead)</entry>
+        <entry><link linkend="unreg">Unregisterised</link> compilation (use <option>-unreg</option> instead)</entry>
 	      <entry>static</entry>
 	      <entry>-</entry>
 	    </row>
diff --git a/docs/users_guide/phases.xml b/docs/users_guide/phases.xml
index 1f048f2612..f98fe90477 100644
--- a/docs/users_guide/phases.xml
+++ b/docs/users_guide/phases.xml
@@ -531,8 +531,8 @@ $ cat foo.hspp</screen>
           <indexterm><primary><option>-fasm</option></primary></indexterm>
         </term>
         <listitem>
-          <para>Use GHC's native code generator rather than
-          compiling via LLVM.
+          <para>Use GHC's <link linkend="native-code-gen">native code generator
+            </link>rather than compiling via LLVM.
           <option>-fasm</option> is the default.</para>
         </listitem>
       </varlistentry>
@@ -543,12 +543,12 @@ $ cat foo.hspp</screen>
           <indexterm><primary><option>-fllvm</option></primary></indexterm>
         </term>
         <listitem>
-          <para>Compile via LLVM instead of using the native code
-          generator. This will generally take slightly longer than the
-          native code generator to compile.
-          Produced code is generally the same speed or faster
-          than the other two code generators. Compiling via LLVM
-          requires LLVM version 2.8 or later to be on the path.</para>
+          <para>Compile via <link linkend="llvm-code-gen">LLVM</link>instead
+          of using the native code generator. This will generally take slightly
+          longer than the native code generator to compile. Produced code is
+          generally the same speed or faster than the other two code
+          generators. Compiling via LLVM requires LLVM to be on the
+          path.</para>
         </listitem>
       </varlistentry>
 
@@ -597,10 +597,9 @@ $ cat foo.hspp</screen>
         </term>
         <listitem>
           <para>Generate position-independent code (code that can be put into
-          shared libraries). This currently works on Linux x86 and x86-64 when
-          using the native code generator (-fasm).
-          On Windows, position-independent code is never used
-          so the flag is a no-op on that platform.</para>
+          shared libraries). This currently works on Linux x86 and x86-64. On
+          Windows, position-independent code is never used so the flag is a
+          no-op on that platform.</para>
         </listitem>
       </varlistentry>
 
diff --git a/docs/users_guide/runtime_control.xml b/docs/users_guide/runtime_control.xml
index 57e89c7151..793ceec46b 100644
--- a/docs/users_guide/runtime_control.xml
+++ b/docs/users_guide/runtime_control.xml
@@ -1357,7 +1357,7 @@ $ ./prog -f +RTS -H32m -S -RTS -h foo bar
 
   </sect2>
 
-  <sect2>
+  <sect2 id="ghc-info">
     <title>Getting information about the RTS</title>
 
     <indexterm><primary>RTS</primary></indexterm>
@@ -1477,7 +1477,8 @@ $ ./a.out +RTS --info
       <varlistentry>
         <term><literal>Compiler unregistered</literal></term>
         <listitem>
-          <para>Was this program compiled with an &ldquo;unregistered&rdquo;
+          <para>Was this program compiled with an
+          <link linkend="unreg">&ldquo;unregistered&rdquo;</link>
           version of GHC? (I.e., a version of GHC that has no platform-specific
           optimisations compiled in, usually because this is a currently
           unsupported platform.) This value will usually be no, unless you're
diff --git a/docs/users_guide/separate_compilation.xml b/docs/users_guide/separate_compilation.xml
index 9d482e138a..d0acbfb39f 100644
--- a/docs/users_guide/separate_compilation.xml
+++ b/docs/users_guide/separate_compilation.xml
@@ -473,8 +473,9 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `uname -m`
 	  <listitem>
 	    <para>Keep intermediate <literal>.hc</literal> files when
 	    doing <literal>.hs</literal>-to-<literal>.o</literal>
-	    compilations via C (NOTE: <literal>.hc</literal> files
-	    are only generated by unregisterised compilers).</para>
+      compilations via <link linkend="c-code-gen">C</link> (NOTE:
+      <literal>.hc</literal> files are only generated by
+      <link linkend="unreg">unregisterised</link> compilers).</para>
 	  </listitem>
 	</varlistentry>
 
@@ -488,10 +489,10 @@ $ ghc -c parse/Foo.hs parse/Bar.hs gurgle/Bumble.hs -odir `uname -m`
 	  <listitem>
 	    <para>Keep intermediate <literal>.ll</literal> files when
 	    doing <literal>.hs</literal>-to-<literal>.o</literal>
-	    compilations via LLVM (NOTE: <literal>.ll</literal> files
-	    aren't generated when using the native code generator, you
-	    may need to use <option>-fllvm</option> to force them
-	    to be produced).</para>
+      compilations via <link linkend="llvm-code-gen">LLVM</link>
+      (NOTE: <literal>.ll</literal> files aren't generated when using the
+      native code generator, you may need to use <option>-fllvm</option> to
+      force them to be produced).</para>
 	  </listitem>
 	</varlistentry>
 
diff --git a/docs/users_guide/sooner.xml b/docs/users_guide/sooner.xml
index 068908a3ae..c6445b9455 100644
--- a/docs/users_guide/sooner.xml
+++ b/docs/users_guide/sooner.xml
@@ -152,17 +152,17 @@ should go here!</para>
       </varlistentry>
 
       <varlistentry>
-	<term>Compile via LVM:</term>
+	<term>Compile via LLVM:</term>
 	<listitem>
-		<para>The LLVM code generator can sometimes do a far better job
-			    at producing fast code then either the native code generator
-					or the C code generator. This is not universal and depends
-					on the code. Numeric heavy code seems to show the best
-					improvement when compiled via LLVM. You can also experiment
-					with passing specific flags to LLVM with the
-					<option>-optlo</option> and <option>-optlc</option> flags.
-				   Be careful though as setting these flags stops GHC from setting
-				   its usual flags for the LLVM optimiser and compiler.</para>
+		<para>The <link linkend="llvm-code-gen">LLVM code generator</link> can
+			sometimes do a far better job at producing fast code than the <link
+				linkend="native-code-gen">native code generator</link>. This is not
+			universal and depends on the code. Numeric heavy code seems to show
+			the best improvement when compiled via LLVM. You can also experiment
+			with passing specific flags to LLVM with the <option>-optlo</option>
+			and <option>-optlc</option> flags.  Be careful though as setting these
+			flags stops GHC from setting its usual flags for the LLVM optimiser
+			and compiler.</para>
 	</listitem>
       </varlistentry>
 
diff --git a/docs/users_guide/using.xml b/docs/users_guide/using.xml
index 57057e86e2..47fec9ae1c 100644
--- a/docs/users_guide/using.xml
+++ b/docs/users_guide/using.xml
@@ -731,11 +731,9 @@ ghc -c Foo.hs</screen>
       <filename>Foo.hs</filename> to an object file
       <filename>Foo.o</filename>.</para>
 
-      <para>Note: What the Haskell compiler proper produces depends on
-      whether a native-code generator<indexterm><primary>native-code
-      generator</primary></indexterm> is used (producing assembly
-      language) or not (producing C).  See <xref
-      linkend="options-codegen"/> for more details.</para>
+      <para>Note: What the Haskell compiler proper produces depends on what
+      backend code generator is used. See <xref linkend="code-generators"/>
+      for more details.</para>
 
       <para>Note: C pre-processing is optional, the
       <option>-cpp</option><indexterm><primary><option>-cpp</option></primary></indexterm>
@@ -2234,13 +2232,13 @@ f "2"    = 2
 	<term><option>-msse2</option>:</term>
 	<listitem>
           <para>
-            (x86 only, added in GHC 7.0.1) Use the SSE2 registers and
-            instruction set to implement floating point operations
-            when using the native code generator.  This gives a
-            substantial performance improvement for floating point,
-            but the resulting compiled code will only run on
-            processors that support SSE2 (Intel Pentium 4 and later,
-            or AMD Athlon 64 and later).
+				(x86 only, added in GHC 7.0.1) Use the SSE2 registers and
+				instruction set to implement floating point operations when using
+				the <link linkend="native-code-gen">native code generator</link>.
+				This gives a substantial performance improvement for floating
+				point, but the resulting compiled code
+				will only run on processors that support SSE2 (Intel Pentium 4 and
+				later, or AMD Athlon 64 and later).
           </para>
           <para>
             SSE2 is unconditionally used on x86-64 platforms.