Reformat other sections of INSTALL.adoc

1 files changed, 106 insertions, 111 deletions

diff --git a/INSTALL.adoc b/INSTALL.adoc
index 5f177f25ca..e020507b38 100644
--- a/INSTALL.adoc
+++ b/INSTALL.adoc
@@ -2,16 +2,15 @@
 
 == PREREQUISITES
 
-* The GNU C compiler gcc is recommended, as the bytecode
-  interpreter takes advantage of gcc-specific features to enhance
-  performance.  gcc is the standard compiler under Linux, MacOS X,
-  and many other systems.
+* The GNU C Compiler (gcc) is recommended, as the bytecode interpreter takes
+  advantage of GCC-specific features to enhance performance. gcc is the standard
+  compiler under Linux, OS X, and many other systems.
 
-* If you do not have write access to /tmp, you should set the environment
-  variable TMPDIR to the name of some other temporary directory.
+* If you do not have write access to `/tmp`, you should set the environment
+  variable `TMPDIR` to the name of some other temporary directory.
 
-* Under HP/UX, the GNU C compiler gcc, the GNU assembler gas, and GNU make
-  are all *required*.  The vendor-provided compiler, assembler and make
+* Under HP/UX, the GNU C Compiler (gcc), the GNU Assembler (gas), and GNU Make
+  are all *required*.  The vendor-provided compiler, assembler and make tools
   have major problems.
 
 == INSTALLATION INSTRUCTIONS
@@ -197,15 +196,15 @@ for guidance on how to edit the generated files by hand.
 
         make world
 +
-This builds the OCaml bytecode compiler for the first time.  This
-phase is fairly verbose; consider redirecting the output to a file:
+This builds the OCaml bytecode compiler for the first time.  This phase is
+fairly verbose; consider redirecting the output to a file:
 
         make world > log.world 2>&1     # in sh
         make world >& log.world         # in csh
 
-3. (Optional) To be sure everything works well, you can try to
-bootstrap the system --- that is, to recompile all OCaml sources with
-the newly created compiler. From the top directory, do:
+3. (Optional) To be sure everything works well, you can try to bootstrap the
+   system -- that is, to recompile all OCaml sources with the newly created
+   compiler. From the top directory, do:
 
         make bootstrap
 +
@@ -214,18 +213,17 @@ or, better:
         make bootstrap > log.bootstrap 2>&1     # in sh
         make bootstrap >& log.bootstrap         # in csh
 +
-The "make bootstrap" checks that the bytecode programs compiled with
-the new compiler are identical to the bytecode programs compiled with
-the old compiler. If this is the case, you can be pretty sure the
-system has been correctly compiled. Otherwise, this does not
-necessarily mean something went wrong. The best thing to do is to try
-a second bootstrapping phase: just do "make bootstrap" again.  It will
-either crash almost immediately, or re-re-compile everything correctly
-and reach the fixpoint.
-
-4. If your platform is supported by the native-code compiler (as
-reported during the autoconfiguration), you can now build the
-native-code compiler. From the top directory, do:
+The `make bootstrap` checks that the bytecode programs compiled with the new
+compiler are identical to the bytecode programs compiled with the old compiler.
+If this is the case, you can be pretty sure the system has been correctly
+compiled. Otherwise, this does not necessarily mean something went wrong.  The
+best thing to do is to try a second bootstrapping phase: just do
+`make bootstrap` again.  It will either crash almost immediately, or
+re-re-compile everything correctly and reach the fix-point.
+
+4. If your platform is supported by the native-code compiler (as reported during
+   the auto-configuration), you can now build the native-code compiler.  From
+   the top directory, do:
 
         make opt
 +
@@ -234,62 +232,62 @@ or:
         make opt > log.opt 2>&1     # in sh
         make opt >& log.opt         # in csh
 
-5. anchor:step-5[] Compile fast versions of the OCaml compilers, by
-compiling them with the native-code compiler (you have only compiled
-them to bytecode so far).  Just do:
+5. anchor:step-5[] Compile fast versions of the OCaml compilers, by compiling
+   them with the native-code compiler (you will have only compiled them to
+   bytecode in steps 2-4).  Just do:
 
         make opt.opt
 +
-Later, you can compile your programs to bytecode using ocamlc.opt
-instead of ocamlc, and to native-code using ocamlopt.opt instead of
-ocamlopt.  The ".opt" compilers should run faster than the normal
-compilers, especially on large input files, but they may take longer
-to start due to increased code size.  If compilation times are an issue on
-your programs, try the ".opt" compilers to see if they make a
-significant difference.
+Later, you can compile your programs to bytecode using ocamlc.opt instead of
+ocamlc, and to native-code using ocamlopt.opt instead of ocamlopt.  The ".opt"
+compilers should run faster than the normal compilers, especially on large input
+files, but they may take longer to start due to increased code size.  If
+compilation times are an issue on your programs, try the ".opt" compilers to see
+if they make a significant difference.
 +
 An alternative, and faster approach to steps 2 to 5 is
 
         make world.opt          # to build using native-code compilers
 +
-The result is equivalent to "make world opt opt.opt", but this may
-fail if anything goes wrong in native-code generation.
-
-6. You can now install the OCaml system. This will create the
-following commands (in the binary directory selected during
-autoconfiguration):
-
-        ocamlc           the batch bytecode compiler
-        ocamlopt         the batch native-code compiler (if supported)
-        ocamlrun         the runtime system for the bytecode compiler
-        ocamlyacc        the parser generator
-        ocamllex         the lexer generator
-        ocaml            the interactive, toplevel-based system
-        ocamlmktop       a tool to make toplevel systems that integrate
-                         user-defined C primitives and OCaml code
-        ocamldebug       the source-level replay debugger
-        ocamldep         generator of "make" dependencies for OCaml sources
-        ocamldoc         documentation generator
-        ocamlprof        execution count profiler
-        ocamlcp          the bytecode compiler in profiling mode
-+
-and also, if you built them during <<step-5,step 5>>,
+The result is equivalent to `make world opt opt.opt`, but this may fail if
+anything goes wrong in native-code generation.
 
-        ocamlc.opt       the batch bytecode compiler compiled with ocamlopt
-        ocamlopt.opt     the batch native-code compiler compiled with ocamlopt
-        ocamllex.opt     the lexer generator compiled with ocamlopt
+6. You can now install the OCaml system. This will create the following commands
+   (in the binary directory selected during autoconfiguration):
++
+[width="70%",frame="topbot",cols="25%,75%"]
+|===============================================================================
+| `ocamlc`     | the batch bytecode compiler
+| `ocamlopt`   | the batch native-code compiler (if supported)
+| `ocamlrun`   | the runtime system for the bytecode compiler
+| `ocamlyacc`  | the parser generator
+| `ocamllex`   | the lexer generator
+| `ocaml`      | the interactive, toplevel-based system
+| `ocamlmktop` | a tool to make toplevel systems that integrate user-defined C
+                 primitives and OCaml code
+| `ocamldebug` | the source-level replay debugger
+| `ocamldep`   | generator of "make" dependencies for OCaml sources
+| `ocamldoc`   | the documentation generator
+| `ocamlprof`  | the execution count profiler
+| `ocamlcp`    | the bytecode compiler in profiling mode
+|===============================================================================
++
+and also, if you built them during <<step-5,step 5>>: `ocamlc.opt`,
+`ocamlopt.opt`, `ocamllex.opt`, `ocamldep.opt` and `ocamldoc.opt`
 +
 From the top directory, become superuser and do:
 
         umask 022       # make sure to give read & execute permission to all
         make install
 
-7. Installation is complete. Time to clean up. From the toplevel
-directory, do "make clean".
+7. Installation is complete. Time to clean up. From the toplevel directory,
+   do:
+
+        make clean
 
-8. (Optional) The emacs/ subdirectory contains Emacs-Lisp files for an
-OCaml editing mode and an interface for the debugger.  To install
-these files, change to the emacs/ subdirectory and do
+8. (Optional) The `emacs/` subdirectory contains Emacs-Lisp files for an OCaml
+   editing mode and an interface for the debugger.  To install these files,
+   change to the `emacs/` subdirectory and do:
 
         make EMACSDIR=<directory where to install the files> install
 +
@@ -298,37 +296,35 @@ or
         make install
 +
 In the latter case, the destination directory defaults to the
-"site-lisp" directory of your Emacs installation.
+`site-lisp` directory of your Emacs installation.
 
-9. After installation, do *not* strip the ocamldebug and ocamlbrowser
-executables.  (These are mixed-mode executables, containing both
-compiled C code and OCaml bytecode; stripping erases the bytecode!)
-Other executables such as ocamlrun can safely be stripped.
+9. After installation, do *not* strip the `ocamldebug` and `ocamlbrowser`
+   executables. These are mixed-mode executables (containing both compiled C
+   code and OCaml bytecode) and stripping erases the bytecode!  Other
+   executables such as `ocamlrun` can safely be stripped.
 
 == IF SOMETHING GOES WRONG
 
-Read the "common problems" and "machine-specific hints" section at the
-end of this file.
+Read the "common problems" and "machine-specific hints" section at the end of
+this file.
 
-Check the files m.h and s.h in config/. Wrong endianness or alignment
-constraints in m.h will immediately crash the bytecode interpreter.
+Check the files `m.h` and `s.h` in `config/`. Wrong endian-ness or alignment
+constraints in `m.h` will immediately crash the bytecode interpreter.
 
-If you get a "segmentation violation" signal, check the limits on the
-stack size and data segment size (type "limit" under csh or
-"ulimit -a" under bash). Make sure the limit on the stack size is
-at least 4M.
+If you get a "segmentation violation" signal, check the limits on the stack size
+and data segment size (type `limit` under csh or `ulimit -a` under bash). Make
+sure the limit on the stack size is at least 4M.
 
-Try recompiling the runtime system with optimizations turned off
-(change CFLAGS in byterun/Makefile and asmrun/Makefile).
-The runtime system contains some complex, atypical pieces of C code
-that can uncover bugs in optimizing compilers. Alternatively, try
-another C compiler (e.g. gcc instead of the vendor-supplied cc).
+Try recompiling the runtime system with optimizations turned off (change
+`CFLAGS` in `byterun/Makefile` and `asmrun/Makefile`). The runtime system
+contains some complex, atypical pieces of C code which can uncover bugs in
+optimizing compilers.  Alternatively, try another C compiler (e.g. `gcc` instead
+of the vendor-supplied `cc`).
 
-You can also build a debug version of the runtime system. Go to the
-byterun/ directory and do "make ocamlrund". Then, copy ocamlrund to
-'../boot/ocamlrun', and try again. This version of the runtime system
-contains lots of assertions and sanity checks that could help you
-pinpoint the problem.
+You can also build a debug version of the runtime system. Go to the `byterun/`
+directory and do `make ocamlrund`.  Then, copy `ocamlrund` to
+`../boot/ocamlrun`, and try again.  This version of the runtime system contains
+lots of assertions and sanity checks that could help you pinpoint the problem.
 
 
 == COMMON PROBLEMS
@@ -336,33 +332,32 @@ pinpoint the problem.
 * The Makefiles do not support parallel make (e.g. make -j2).
 Fix: do not pass the -j option to make, and be patient.
 
-* The Makefiles use the "include" directive, which is not supported by
-all versions of make. Use GNU make if this is a problem.
+* The Makefiles use the `include` directive, which is not supported by all
+  versions of make. Use GNU Make if this is a problem.
 
-* Solaris make mishandles a space in our Makefiles, so you have to use GNU
-make to build on Solaris.
+* Solaris make mishandles a space in our Makefiles, so you have to use GNU make
+  to build on Solaris.
 
-* The Makefiles assume that make executes commands by calling /bin/sh. They
-won't work if /bin/csh is called instead. You may have to unset the SHELL
-environment variable, or set it to /bin/sh.
+* The Makefiles assume that make executes commands by calling `/bin/sh`. They
+  won't work if `/bin/csh` is called instead.  You may have to unset the `SHELL`
+  environment variable, or set it to `/bin/sh`.
 
-* On some systems, localization causes build problems.  You should
-try to set the C locale (export LC_ALL=C) before compiling if you have
-strange errors while compiling OCaml.
+* On some systems, localization causes build problems.  You should try to set
+  the C locale (`export LC_ALL=C`) before compiling if you have strange errors
+  while compiling OCaml.
 
-* gcc 2.7.2.1 generates incorrect code for the runtime system in -O mode
-on some Intel x86 platforms (e.g. Linux RedHat 4.1 and 4.2).
-If this causes a problem, the solution is to upgrade to 2.7.2.3 or above.
+* GCC 2.7.2.1 generates incorrect code for the runtime system in `-O` mode on
+  some Intel x86 platforms (e.g. Linux RedHat 4.1 and 4.2). If this causes a
+  problem, the solution is to upgrade to 2.7.2.3 or above.
 
-* Some versions of gcc 2.96 for the Intel x86 (as found in RedHat 7.2,
-Mandrake 8.0 and Mandrake 8.1) generates incorrect code for the runtime
-system.  The "configure" script tries to work around this problem.
+* Some versions of GCC 2.96 for the Intel x86 (as found in RedHat 7.2,
+  Mandrake 8.0 and Mandrake 8.1) generate incorrect code for the runtime system.
+  The `configure` script tries to work around this problem.
 
-* On HP 9000/700 machines under HP/UX 9.  Some versions of cc are
-unable to compile correctly the runtime system (wrong code is
-generated for (x - y) where x is a pointer and y an integer).
-Fix: use gcc.
+* On HP 9000/700 machines under HP/UX 9, some versions of `cc` are unable to
+  compile correctly the runtime system (wrong code is generated for `(x - y)`
+  where `x` is a pointer and `y` an integer). Fix: use `gcc`.
 
-* Under MacOS X 10.6, with XCode 4.0.2, the configure script mistakenly
-detects support for CFI directives in the assembler.
-Fix: give the "-no-cfi" option to configure.
+* Under OS X 10.6, with XCode 4.0.2, the `configure` script mistakenly detects
+  support for CFI directives in the assembler. Fix: give the `-no-cfi` option to
+  `configure`.