attic/building/old/using.md

@@ -187,36 +187,39 @@ communicates these snippets of information in two ways:
 to get a list of the available arguments.  Here are some of
 the ones you might need:
 
-<table><tr><th>`--with-ghc=<path>`</th>
+
+<table><tr><th><tt>--with-ghc=<path></tt></th>
 <td>
 Specifies the path to an installed GHC which you would like to use.
 This compiler will be used for compiling GHC-specific code (eg. GHC
-itself).  This option *cannot* be specified using `build.mk`
-(see later), because `configure` needs to auto-detect the
-version of GHC you're using.  The default is to look for a compiler
-named `ghc` in your path.
+itself).  This option <i>cannot</i> be specified using <tt>build.mk</tt>
+(see later), because <tt>configure</tt> needs to auto-detect the
+version of GHC you&apos;re using.  The default is to look for a compiler
+named <tt>ghc</tt> in your path.
               
 </td></tr>
-<tr><th>`--with-hc=<path>`</th>
+<tr><th><tt>--with-hc=<path></tt></th>
 <td>
 Specifies the path to any installed Haskell compiler.  This compiler
 will be used for compiling generic Haskell code.  The default is to
-use `ghc`. (NOTE: I'm not sure it actually works to specify a
-compiler other than GHC here; unless you really know what you're
+use <tt>ghc</tt>. (NOTE: I&apos;m not sure it actually works to specify a
+compiler other than GHC here; unless you really know what you&apos;re
 doing I suggest not using this option at all.)
               
 </td></tr>
-<tr><th>`--with-gcc=<path>`</th>
+<tr><th><tt>--with-gcc=<path></tt></th>
 <td>
 Specifies the path to the installed GCC. This compiler will be used
-to compile all C files, *except* any generated by the installed
+to compile all C files, <i>except</i> any generated by the installed
 Haskell compiler, which will have its own idea of which C compiler
-(if any) to use.  The default is to use `gcc`.
+(if any) to use.  The default is to use <tt>gcc</tt>.
 </td></tr></table>
 
+
 ### Step 3: build configuration.
 
 
+
 Next, you say how this build of GHC is to differ from the standard
 defaults by creating a new file `mk/build.mk` *in the build
 tree*.  This file is the one and only file you edit in the build
@@ -232,9 +235,11 @@ shortly.
 And that's it for configuration. Simple, eh?
 
 
+
 What do you put in your build-specific configuration file
 `mk/build.mk`?  *For almost all purposes all you will do is put
-make variable definitions that override those in*`mk/config.mk.in`.  The whole point of
+make variable definitions that override those in*
+`mk/config.mk.in`.  The whole point of
 `mk/config.mk.in` — and its derived counterpart
 `mk/config.mk` — is to define the build configuration. It is
 heavily commented, as you will see if you look at it.  So generally,
@@ -249,60 +254,69 @@ For your convenience, there's a file called `build.mk.sample` that
 can serve as a starting point for your `build.mk`.
 
 
+
 For example, `config.mk.in` contains the definition:
 
-<table><tr><th>`GhcHcOpts = -Rghc-timing`</th>
+
+<table><tr><th><tt>GhcHcOpts = -Rghc-timing</tt></th>
 <td>
 The accompanying comment explains that this is the list of flags
 passed to GHC when building GHC itself.  For doing development, it
-is wise to add `-DDEBUG`, to enable debugging code.  So you
-would add the following to `build.mk`:
+is wise to add <tt>-DDEBUG</tt>, to enable debugging code.  So you
+would add the following to <tt>build.mk</tt>:
       
 </td></tr>
-<tr><th>`GhcHcOpts += -DDEBUG`</th>
+<tr><th><tt>GhcHcOpts += -DDEBUG</tt></th>
 <td>
-GNU `make` allows existing definitions to have new text appended
-using the "`+=`" operator, which is quite a convenient feature.
-
-Haskell compilations by default have `-O` turned on, by virtue
-of this setting from `config.mk`:
+GNU <tt>make</tt> allows existing definitions to have new text appended
+using the &quot;<tt>+=</tt>&quot; operator, which is quite a convenient feature.
+<br><br>
+Haskell compilations by default have <tt>-O</tt> turned on, by virtue
+of this setting from <tt>config.mk</tt>:
 </td></tr></table>
 
-<table><tr><th>`SRC_HC_OPTS += -H16m -O`</th>
-<td>`SRC_HC_OPTS` means "options for HC from the source tree", where
-HC stands for Haskell Compiler.  `SRC_HC_OPTS` are added to
+
+<table><tr><th><tt>SRC_HC_OPTS += -H16m -O</tt></th>
+<td>
+<tt>SRC_HC_OPTS</tt> means &quot;options for HC from the source tree&quot;, where
+HC stands for Haskell Compiler.  <tt>SRC_HC_OPTS</tt> are added to
 every Haskell compilation.  To turn off optimisation, you could add
-this to `build.mk`:
+this to <tt>build.mk</tt>:
 </td></tr></table>
 
-<table><tr><th>`SRC_HC_OPTS = -H16m -O0`</th>
+
+<table><tr><th><tt>SRC_HC_OPTS = -H16m -O0</tt></th>
 <td>
-Or you could just add `-O0` to `GhcHcOpts` to turn off
-optimisation for the compiler.  See [Building/Hacking](building/hacking)
+Or you could just add <tt>-O0</tt> to <tt>GhcHcOpts</tt> to turn off
+optimisation for the compiler.  See <a href="building/hacking">Building/Hacking</a>
 for some more suggestions.
-
-When reading `config.mk.in`, remember that anything between
-"@...@" signs is going to be substituted by `configure` later.
-You *can* override the resulting definition if you want, but you
-need to be a bit surer what you are doing.  For example, there's a
+<br><br>
+When reading <tt>config.mk.in</tt>, remember that anything between
+&quot;@...@&quot; signs is going to be substituted by <tt>configure</tt> later.
+You <i>can</i> override the resulting definition if you want, but you
+need to be a bit surer what you are doing.  For example, there&apos;s a
 line that says:
 </td></tr></table>
 
-<table><tr><th>`TAR = @TarCmd@`</th>
+
+<table><tr><th><tt>TAR = @TarCmd@</tt></th>
 <td>
-This defines the Make variables `TAR` to the pathname for a
-`tar` that `configure` finds somewhere.  If you have your
-own pet `tar` you want to use instead, that's fine. Just add
-this line to `mk/build.mk`:
+This defines the Make variables <tt>TAR</tt> to the pathname for a
+<tt>tar</tt> that <tt>configure</tt> finds somewhere.  If you have your
+own pet <tt>tar</tt> you want to use instead, that&apos;s fine. Just add
+this line to <tt>mk/build.mk</tt>:
 </td></tr></table>
 
-<table><tr><th>`TAR = mytar`</th>
+
+<table><tr><th><tt>TAR = mytar</tt></th>
 <td>
-You do not *have* to have a `mk/build.mk` file at all; if you
-don't, you'll get all the default settings from
-`mk/config.mk.in`.
+You do not <i>have</i> to have a <tt>mk/build.mk</tt> file at all; if you
+don&apos;t, you&apos;ll get all the default settings from
+<tt>mk/config.mk.in</tt>.
 </td></tr></table>
 
+
+>
 >
 > You can also use `build.mk` to override anything that
 > `configure` got wrong.  One place where this happens often is
@@ -311,6 +325,8 @@ don't, you'll get all the default settings from
 > system uses an automounter then the correct directory is hard to
 > find automatically.  If you find that `configure` has got it
 > wrong, just put the correct definition in `build.mk`.
+>
+>
 
 ## The story so far
 
@@ -416,49 +432,57 @@ best to start `make` from the top of the tree.  The top-level
 `Makefile` is set up to do a 2-stage bootstrap by default (when
 you say `make`).  Some other targets it supports are:
 
-<table><tr><th>`stage1`</th>
+
+<table><tr><th><tt>stage1</tt></th>
 <td>
 Build everything as normal, including the stage 1 compiler.
 </td></tr></table>
 
-<table><tr><th>`stage2`</th>
+
+<table><tr><th><tt>stage2</tt></th>
 <td>
 Build the stage 2 compiler only.
 </td></tr></table>
 
-<table><tr><th>`stage3`</th>
+
+<table><tr><th><tt>stage3</tt></th>
 <td>
 Build the stage 3 compiler only.
 </td></tr></table>
 
-<table><tr><th>`bootstrap`, `bootstrap2`</th>
+
+<table><tr><th><tt>bootstrap</tt>, <tt>bootstrap2</tt></th>
 <td>
 Build stage 1 followed by stage 2.
 </td></tr></table>
 
-<table><tr><th>`bootstrap3`</th>
+
+<table><tr><th><tt>bootstrap3</tt></th>
 <td>
 Build stages 1, 2 and 3.
 </td></tr></table>
 
-<table><tr><th>`install`</th>
+
+<table><tr><th><tt>install</tt></th>
 <td>
 Install everything, including the compiler built in stage 2.  To
-override the stage, say `make install stage=n` where `n` is
+override the stage, say <tt>make install stage=n</tt> where <tt>n</tt> is
 the stage to install.
 </td></tr></table>
 
-<table><tr><th>`binary-dist`</th>
+
+<table><tr><th><tt>binary-dist</tt></th>
 <td>
 make a binary distribution.  This is the target we
 use to build the binary distributions of GHC.
 </td></tr></table>
 
-<table><tr><th>`dist`</th>
+
+<table><tr><th><tt>dist</tt></th>
 <td>
 make a source distribution.  Note that this target
-does `make distclean` as part of its work;
-don't use it if you want to keep what you've built.
+does <tt>make distclean</tt> as part of its work;
+don&apos;t use it if you want to keep what you&apos;ve built.
 </td></tr></table>
 
 
@@ -481,84 +505,93 @@ before `make stage2` in `compiler`.
 ## Standard Targets
 
 
+
 In any directory you should be able to make the following:
 
-<table><tr><th>`boot`</th>
+
+<table><tr><th><tt>boot</tt></th>
 <td>
 does the one-off preparation required to get ready for the real
 work, e.g. building the module dependency graph.
-
-Invoking the `boot` target explicitly is not normally necessary.
-From the top-level directory, invoking `make` causes `make boot`
+<br><br>
+Invoking the <tt>boot</tt> target explicitly is not normally necessary.
+From the top-level directory, invoking <tt>make</tt> causes <tt>make boot</tt>
 to be invoked in various subdirectories, in the right
 order.  Unless you really know what you are doing, it is best to
-always say `make` from the top level first.
-
-If you're working in a subdirectory somewhere and need to update the
-dependencies, `make boot` is a good way to do it.
+always say <tt>make</tt> from the top level first.
+<br><br>
+If you&apos;re working in a subdirectory somewhere and need to update the
+dependencies, <tt>make boot</tt> is a good way to do it.
 </td></tr></table>
 
-<table><tr><th>`all`</th>
+
+<table><tr><th><tt>all</tt></th>
 <td>
 makes all the final target(s) for this Makefile.  Depending on which
-directory you are in a "final target" may be an executable program,
+directory you are in a &quot;final target&quot; may be an executable program,
 a library archive, a shell script, or a Postscript file.  Typing
-`make` alone is generally the same as typing `make all`.
+<tt>make</tt> alone is generally the same as typing <tt>make all</tt>.
 </td></tr></table>
 
-<table><tr><th>`install`</th>
+
+<table><tr><th><tt>install</tt></th>
 <td>
-installs the things built by `all` (except for the
+installs the things built by <tt>all</tt> (except for the
 documentation).  Where does it install them?  That is specified by
-`mk/config.mk.in`; you can override it in `mk/build.mk`, or
-by running `configure` with command-line arguments like
-`--bindir=/home/simonpj/bin`; see `./configure --help` for
+<tt>mk/config.mk.in</tt>; you can override it in <tt>mk/build.mk</tt>, or
+by running <tt>configure</tt> with command-line arguments like
+<tt>--bindir=/home/simonpj/bin</tt>; see <tt>./configure --help</tt> for
 the full details.
 </td></tr></table>
 
-<table><tr><th>`install-docs`</th>
+
+<table><tr><th><tt>install-docs</tt></th>
 <td>
 installs the documentation. Otherwise behaves just like
-`install`.
+<tt>install</tt>.
 </td></tr></table>
 
-<table><tr><th>`clean`</th>
+
+<table><tr><th><tt>clean</tt></th>
 <td>
 Delete all files from the current directory that are normally
-created by building the program.  Don't delete the files that record
-the configuration, or files generated by `make boot`.  Also
-preserve files that could be made by building, but normally aren't
+created by building the program.  Don&apos;t delete the files that record
+the configuration, or files generated by <tt>make boot</tt>.  Also
+preserve files that could be made by building, but normally aren&apos;t
 because the distribution comes with them.
 </td></tr></table>
 
-<table><tr><th>`distclean`</th>
+
+<table><tr><th><tt>distclean</tt></th>
 <td>
 Delete all files from the current directory that are created by
 configuring or building the program. If you have unpacked the source
-and built the program without creating any other files, `make distclean`
+and built the program without creating any other files, <tt>make distclean</tt>
 should leave only the files that were in the distribution.
 </td></tr></table>
 
-<table><tr><th>`mostlyclean`</th>
+
+<table><tr><th><tt>mostlyclean</tt></th>
 <td>
-Like `clean`, but may refrain from deleting a few files that
-people normally don't want to recompile.
+Like <tt>clean</tt>, but may refrain from deleting a few files that
+people normally don&apos;t want to recompile.
 </td></tr></table>
 
-<table><tr><th>`maintainer-clean`</th>
+
+<table><tr><th><tt>maintainer-clean</tt></th>
 <td>
 Delete everything from the current directory that can be
 reconstructed with this Makefile.  This typically includes
-everything deleted by `distclean`, plus more: C source files
+everything deleted by <tt>distclean</tt>, plus more: C source files
 produced by Bison, tags tables, Info files, and so on.
-    
-One exception, however: `make maintainer-clean` should not
-delete `configure` even if `configure` can be remade using a
-rule in the `Makefile`. More generally, `make maintainer-clean`
+<br><br>    
+One exception, however: <tt>make maintainer-clean</tt> should not
+delete <tt>configure</tt> even if <tt>configure</tt> can be remade using a
+rule in the <tt>Makefile</tt>. More generally, <tt>make maintainer-clean</tt>
 should not delete anything that needs to exist in order to run
-`configure` and then begin to build the program.
-    
-After a `maintainer-clean`, a `configure` will be necessary
+<tt>configure</tt> and then begin to build the program.
+<br><br>    
+After a <tt>maintainer-clean</tt>, a <tt>configure</tt> will be necessary
 before building again.
 </td></tr></table>
 
@@ -566,23 +599,24 @@ before building again.
 All of these standard targets automatically recurse into
 sub-directories.  Certain other standard targets do not:
 
-<table><tr><th>`depend`</th>
+
+<table><tr><th><tt>depend</tt></th>
 <td>
-make a `.depend` file in each directory that needs it. This
-`.depend` file contains mechanically-generated dependency
+make a <tt>.depend</tt> file in each directory that needs it. This
+<tt>.depend</tt> file contains mechanically-generated dependency
 information; for example, suppose a directory contains a Haskell
-source module `Foo.lhs` which imports another module `Baz`.
-Then the generated `.depend` file will contain the dependency:
+source module <tt>Foo.lhs</tt> which imports another module <tt>Baz</tt>.
+Then the generated <tt>.depend</tt> file will contain the dependency:
 
 ```wiki
 Foo.o : Baz.hi
 ```
 
-which says that the object file `Foo.o` depends on the interface
-file `Baz.hi` generated by compiling module `Baz`.  The
-`.depend` file is automatically included by every Makefile.
+which says that the object file <tt>Foo.o</tt> depends on the interface
+file <tt>Baz.hi</tt> generated by compiling module <tt>Baz</tt>.  The
+<tt>.depend</tt> file is automatically included by every Makefile.
 Now that we are using Cabal for most of the building, most directories
-don't support the `depend` target any more. Use `boot` instead.
+don&apos;t support the <tt>depend</tt> target any more. Use <tt>boot</tt> instead.
 </td></tr></table>