[some tweaks to the HC bootstrapping instructions
Simon Marlow <simonmar@microsoft.com>**20060510115236] {
hunk ./docs/building/building.xml 2354
-    unsupported platform.  There are two distinct
-    possibilities:</para>
+    unsupported platform.  To avoid confusion, when we say
+    &ldquo;architecture&rdquo; we are referring to the processor, and
+    we use the term &ldquo;platform&rdquo; to refer to the combination
+    of architecture and operating system.</para>
+
+    <para>There are two distinct porting scenarios:</para>
hunk ./docs/building/building.xml 2363
-	<para>The hardware architecture for your system is already
-	supported by GHC, but you're running an OS that isn't
-	supported (or perhaps has been supported in the past, but
-	currently isn't).  This is the easiest type of porting job,
-	but it still requires some careful bootstrapping.  Proceed to
-	<xref linkend="sec-booting-from-hc"/>.</para>
+	<para>Your platform is already supported, but you want to
+	compile up GHC using just a C compiler.  This is a
+	straightforward bootstrap from HC files, and is described in
+	<xref linkend="sec-booting-from-hc" />.</para>
hunk ./docs/building/building.xml 2370
-	<para>Your system's hardware architecture isn't supported by
-	GHC.  This will be a more difficult port (though by comparison
-	perhaps not as difficult as porting gcc).  Proceed to <xref
-	linkend="unregisterised-porting"/>.</para>
+	<para>Your platform isn't supported by GHC.  You will need to
+	do an <emphasis>unregisterised bootstrap</emphasis>, proceed
+	to <xref linkend="unregisterised-porting"/>.</para>
hunk ./docs/building/building.xml 2393
-	that were generated on <emphasis>the same platform</emphasis>.  There
-	may be some supplied on the GHC download page, otherwise you'll have to
-	compile some up yourself, or start from
-	<emphasis>unregisterised</emphasis> HC files - see <xref
-	  linkend="unregisterised-porting"/>.</para>
+	that were generated on <emphasis>the same platform</emphasis>.
+	There may be some supplied on the GHC download page, otherwise
+	you'll have to compile some up yourself.</para>
hunk ./docs/building/building.xml 2402
-	  <para>Unpack the HC files on top of a fresh source tree
-          (make sure the source tree version matches the version of
-          the HC files <emphasis>exactly</emphasis>!).  This will
-          place matching <filename>.hc</filename> files next to the
-          corresponding Haskell source (<filename>.hs</filename> or
-          <filename>.lhs</filename>) in the compiler subdirectory
-          <filename>ghc/compiler</filename> and in the libraries
-          (subdirectories of 
+	  <para>Make a set of HC files.  On an identical system with
+	  GHC already installed, get a GHC source tree and put the
+	  following in <literal>mk/build.mk</literal>:</para>
+
+<programlisting>
+SRC_HC_OPTS     = -H32m -O -fasm -Rghc-timing -keep-hc-files
+GhcLibHcOpts    = -O
+GhcLibWays      =
+SplitObjs       = NO
+</programlisting>
+
+	  <para>Build GHC as normal, and then <literal>make
+	  hc-file-bundle Project=ghc</literal> to creates the tar file
+	  containing the hc files.</para>
+	</listitem>
+
+	<listitem>
+	  <para>On the target system, unpack the HC files on top of a
+          fresh source tree (make sure the source tree version matches
+          the version of the HC files <emphasis>exactly</emphasis>!).
+          This will place matching <filename>.hc</filename> files next
+          to the corresponding Haskell source
+          (<filename>.hs</filename> or <filename>.lhs</filename>) in
+          the compiler subdirectory <filename>ghc/compiler</filename>
+          and in the libraries (subdirectories of
hunk ./docs/building/building.xml 2458
-      <title>Porting GHC to a new architecture</title>
+      <title>Porting GHC to a new platform</title>
hunk ./docs/building/building.xml 2460
-      <para>The first step in porting to a new architecture is to get
-      an <firstterm>unregisterised</firstterm> build working.  An
+      <para>The first step in porting to a new platform is to get an
+      <firstterm>unregisterised</firstterm> build working.  An
hunk ./docs/building/building.xml 2492
+      <para>You should go through this process even if your
+      architecture is already has registerised support in GHC, but
+      your OS currently isn't supported.  In this case you probably
+      won't need to port any of the architecture-specific parts of the
+      code, and you can proceed straight from the unregisterised build
+      to build a registerised compiler.</para>
+
hunk ./docs/building/building.xml 2555
-              architecture, and re-generate
+              platform, and re-generate
hunk ./docs/building/building.xml 2877
-	(<filename>$(GHC&lowbar;TOP)/rts/Linker.c</filename>).  The linker
-	currently supports the ELF and PEi386 object file formats - if
-	your platform uses one of these then things will be
-	significantly easier.  The majority of Unix platforms use the
-	ELF format these days.  Even so, there are some
+	(<filename>$(GHC&lowbar;TOP)/rts/Linker.c</filename>).  The
+	linker currently supports the ELF and PEi386 object file
+	formats - if your platform uses one of these then things will
+	be significantly easier.  The majority of Unix platforms use
+	the ELF format these days.  Even so, there are some
hunk ./docs/building/building.xml 2885
-	architecture will probaly be necessary.</para>
+	architecture and/or OS will probaly be necessary.</para>
}