Merge branch 'ng/readme' into ccase/r13b04_dev

* ng/readme:
  Clean up formatting issues in the README

1 files changed, 166 insertions, 194 deletions

diff --git a/README b/README
index 50280169a0..fa430e7aab 100644
--- a/README
+++ b/README
@@ -2,16 +2,14 @@
                           OpenSource Erlang/OTP 
 ===========================================================================
 
-
 Please read the whole file before attempting to build and install Erlang.
-You can find more information about OpenSource Erlang at
+You can find more information about Open Source Erlang at:
 
-  http://www.erlang.org/
+    http://www.erlang.org/
 
-The source code for Erlang/OTP can also be found in a Git
-repository at
+The source code for Erlang/OTP can also be found in a Git repository:
 
-   http://github.com/erlang/otp
+    http://github.com/erlang/otp
 
 %CopyrightBegin%
 
@@ -30,7 +28,6 @@ under the License.
 
 %CopyrightEnd%
 
-
 Portability
 -----------
 
@@ -47,15 +44,14 @@ At Ericsson we have a "Daily Build and Test" that runs on:
     Solaris/Sparc32         8, 9, 10
     Solaris/Sparc64         10
     Solaris/x86             10
-    Linux/Suse x86	    9.4, 10.1
-    Linux/Suse x86_64	    10.0, 10.1, 11.0
+    Linux/Suse x86          9.4, 10.1
+    Linux/Suse x86_64       10.0, 10.1, 11.0
     FreeBSD x86             7.1
     Mac OS X/Intel          10.4.11 (Tiger), 10.5.8 (Leopard)
-    Windows		    XP SP3, 2003, Vista
+    Windows                 XP SP3, 2003, Vista
 
 We have also done some testing on Mac OS 10.6.0 (Snow Leopard).
 
-
 Versions known *not* to work
 -------------------------------------
 
@@ -70,86 +66,66 @@ that will crash immediately. The bug is supposed to be fixed in gcc-4.3.1.
 
 FreeBSD had a bug which caused kqueue/poll/select to fail to detect
 that a writev() on a pipe has been made. This bug should have been fixed
-in FreeBSD 6.3 and FreeBSD 7.0. More information can be found at:
-* http://www.freebsd.org/cgi/cvsweb.cgi/src/sys/kern/sys_pipe.c
-* http://lists.freebsd.org/pipermail/freebsd-arch/2007-September/006790.html
-NetBSD and DragonFlyBSD probably have or have had the same bug.
+in FreeBSD 6.3 and FreeBSD 7.0. NetBSD and DragonFlyBSD probably have or
+have had the same bug. More information can be found at:
+ * http://www.freebsd.org/cgi/cvsweb.cgi/src/sys/kern/sys_pipe.c
+ * http://lists.freebsd.org/pipermail/freebsd-arch/2007-September/006790.html
 
 getcwd() on Solaris 9 can cause an emulator crash. If you have async-threads
 enabled you can increase the stack size of the async-threads as a temporary
 workaround. See the +a command-line argument in the documentation of erl(1).
 Without async-threads the emulator isn't as vulnerable to this bug, but if
 you hit it without async-threads the only workaround available is to enable
-async-threads and increase the stack size of the async-threads.
-Sun has however released patches that fixes the issue:
+async-threads and increase the stack size of the async-threads. Sun has
+however released patches that fixes the issue:
+
 Problem Description: 6448300 large mnttab can cause stack overrun during
-                     Solaris 9 getcwd
-* http://sunsolve.sun.com/search/document.do?assetkey=1-21-112874-40-1&searchclause=6448300
-* http://sunsolve.sun.com/search/document.do?assetkey=1-21-114432-29-1&searchclause=6448300
+Solaris 9 getcwd
+
+More information can be found at:
+ * http://sunsolve.sun.com/search/document.do?assetkey=1-21-112874-40-1&searchclause=6448300
+ * http://sunsolve.sun.com/search/document.do?assetkey=1-21-114432-29-1&searchclause=6448300
 
 Required utilities
 ------------------
 
 These are the tools you will need in order to unpack and build Erlang/OTP.
 
-  Unpacking
-  ---------
-
-  GNU unzip, or a modern uncompress.
-
-  A TAR program that understands the GNU TAR format for long
-  filenames (such as GNU TAR).
-  
-
-  Compiling
-  ---------
-
-  GNU make
-
-  GNU C compiler
-
-  Perl 5
-
-  GNU m4		If hipe (native code) support is enabled.
-
-  ncurses		(Or termcap or termlib.) The development headers and
-                        libraries are needed, often known as ncurses-devel.
-			(Use --without-termcap to build without any of these
-			libraries. Only the old shell (without any line
-			editing) can be used.)
-
-  OpenSSL	        Optional, but needed for building the Erlang/OTP
-                        applications 'ssl' and 'crypto'. You need the
-                        "development package" of OpenSSL, i.e. including
-                        the header files. For building the application 'ssl'
-			the OpenSSL binary command program 'openssl' is also
-			needed. 
-
-			At least version 0.9.7 of OpenSSL is required.
-
-  Sun Java jdk-1.5.0    Or higher. Optional but needed for building
-			the Erlang/OTP application 'jinterface' and parts
-			of 'ic' and 'orber'. We have also tested
-			IBM's JDK 1.5.0.
-
-  X Windows             Optional, but development headers and libraries
-                        are needed to build the Erlang/OTP application 'gs'
-			on Unix/Linux.
-
-  sed			There seem to be some problems with some of the
-			'sed' version on Solaris. Make sure "/bin/sed"
-			or "/usr/bin/sed" is used on the Solaris platform.
-
-  Flex                  Optional, headers and libraries are needed to 
-                        build the flex scanner for the megaco application
-                        on Unix/Linux.
-
-
-  Installing
-  ----------
-
-  An 'install' program that can take multiple file names.
-
+Unpacking
+
+ * GNU unzip, or a modern uncompress.
+ * A TAR program that understands the GNU TAR format for long filenames (such
+as GNU TAR).
+
+Compiling
+
+ * GNU make
+ * GNU C compiler
+ * Perl 5
+ * GNU m4 -- If hipe (native code) support is enabled.
+ * ncurses (or termcap or termlib) -- The development headers and libraries
+   are needed, often known as ncurses-devel. (Use --without-termcap to build
+   without any of these libraries. Only the old shell (without any line
+   editing) can be used.)
+ * OpenSSL -- Optional, but needed for building the Erlang/OTP applications
+   'ssl' and 'crypto'. You need the "development package" of OpenSSL, i.e.
+   including the header files. For building the application 'ssl' the OpenSSL
+   binary command program 'openssl' is also needed. 
+   At least version 0.9.7 of OpenSSL is required.
+ * Sun Java jdk-1.5.0 or higher -- Optional but needed for building the
+   Erlang/OTP application 'jinterface' and parts of 'ic' and 'orber'. We
+   have also tested IBM's JDK 1.5.0.
+ * X Windows -- Optional, but development headers and libraries are needed
+   to build the Erlang/OTP application 'gs' on Unix/Linux.
+ * sed -- There seem to be some problems with some of the 'sed' version on
+   Solaris. Make sure "/bin/sed" or "/usr/bin/sed" is used on the Solaris
+   platform.
+ * Flex -- Optional, headers and libraries are needed to build the flex
+   scanner for the megaco application on Unix/Linux.
+
+Installing
+
+ * An 'install' program that can take multiple file names.
 
 How to build and install Erlang/OTP
 -----------------------------------
@@ -158,31 +134,30 @@ If you are building in a Git reposistory, see
 
   http://wiki.github.com/erlang/otp
 
-The following instructions are for building using the
-source tar ball.
+The following instructions are for building using the source tar ball.
 
-Start by unpacking the Erlang/OTP distribution file with your
-GNU compatible TAR
+Step 1: Start by unpacking the Erlang/OTP distribution file with your GNU
+compatible TAR program.
 
-  1)    gunzip -c otp_src_R13B03.tar.gz | tar xf -
-  1)    zcat otp_src_R13B03.tar.gz | tar xf -
+    $ gunzip -c otp_src_R13B03.tar.gz | tar xf -
+    $ zcat otp_src_R13B03.tar.gz | tar xf -
 
-Now cd into the base directory
+Step 2: Now cd into the base directory.
 
-  2)    cd otp_src_R13B03
+    $ cd otp_src_R13B03
 
-On some platforms Perl may behave strangely if certain locales are set,
-so optionally you may need to set the LANG variable:
+Step 3: On some platforms Perl may behave strangely if certain locales are
+set, so optionally you may need to set the LANG variable:
 
-  3a) LANG=C; export LANG #Bourne shell
+    # Bourne shell
+    $ LANG=C; export LANG
 or
-  3b) setenv LANG C #C-shell
+    # C-Shell
+    $ setenv LANG C
 
-Run the following commands
+Step 4: Run the following commands to configure the build:
 
-  4a)    ./configure  [ options ]
-or
-  4b)    ./configure --prefix=<BaseDir> [ other options ]
+    $ ./configure  [ options ]
 
 By default, Erlang/OTP will be installed in /usr/local/{bin,lib/erlang,man/man1}.
 To instead install in <BaseDir>/{bin,lib/erlang,man/man1}, use the --prefix=<BaseDir>
@@ -192,14 +167,18 @@ If you upgraded the source with some patch you may need to clean up
 from previous builds before the new build. Do a "make clean"; see
 "Caveats" below.
 
-  5)    make
-  6)    make install
+Step 5: Build the Erlang/OTP package.
+
+    $ make
+
+Step 6: Install then Erlang/OTP package
+
+    $ make install
 
 Let's go through them in some detail:
 
-Step 4 runs a configuration script created by the GNU autoconf
-utility, which checks for system specific features and then creates a
-number of makefiles.
+Step 4 runs a configuration script created by the GNU autoconf utility, which
+checks for system specific features and then creates a number of makefiles.
 
 The configure script allows you to customize a number of parameters;
 type "./configure --help" for details.
@@ -221,30 +200,28 @@ located, or alternatively disable the use of SSL and Crypto.
 
 Other options are:
 
-	--enable-smp-support	See the next section.
+    --enable-smp-support    See the next section.
+
+    --disable-smp-support   See the next section.
 
-	--disable-smp-support	See the next section.
+    --disable-threads       Disable support for threaded I/O;
+                            this option also disables building of the SMP
+                            emulator. (See the next section.)
 
-	--disable-threads	Disable support for threaded I/O;
-				this option also disables building
-				of the SMP emulator. (See the next section.)
+    --enable-threads        Enable support for threaded I/O.
+                            (This is the default if SMP support is enabled.
+                            See the next section.)
 
-	--enable-threads	Enable support for threaded I/O.
-				(This is the default if SMP support is enabled.
-				See the next section.)
-				
-	--disable-hipe   	Disable HiPE (High-Performance Erlang).
-				HiPE will automatically be enabled on
-				supported platforms.
-	
+    --disable-hipe          Disable HiPE (High-Performance Erlang).
+                            HiPE will automatically be enabled on supported
+                            platforms.
 
-    Step 5 builds the Erlang/OTP system. On a fast computer,
-this will take about 5 minutes. After completion of this step,
-you should have a working Erlang/OTP system which you can
-try by typing "bin/erl". This should start up Erlang/OTP and give you
-a prompt.
+Step 5 builds the Erlang/OTP system. On a fast computer, this will take about
+5 minutes. After completion of this step, you should have a working
+Erlang/OTP system which you can try by typing "bin/erl". This should start
+up Erlang/OTP and give you a prompt.
 
-    Step 6 is optional. It installs Erlang/OTP (if you change your
+Step 6 is optional. It installs Erlang/OTP (if you change your
 mind about where you wish to install you can rerun step 4, without
 having to do step 5 again).
 
@@ -294,14 +271,14 @@ How to install the Erlang/OTP documentation
 For some graphical tools to find the on-line help you have to install
 the HTML documentation on top of the installed OTP applications, i.e.
 
-        cd <PrefixDir>/lib/erlang
-        gunzip -c otp_html_R<XY>B-<Z>.tar.gz | tar xf -
+    $ cd <PrefixDir>/lib/erlang
+    $ gunzip -c otp_html_R<XY>B-<Z>.tar.gz | tar xf -
 
 For "erl -man <page>" to work the Unix manual pages have to be
 installed in the same way, i.e.
 
-        cd <PrefixDir>/lib/erlang
-        gunzip -c otp_man_R<XY>B-<Z>.tar.gz | tar xf -
+    $ cd <PrefixDir>/lib/erlang
+    $gunzip -c otp_man_R<XY>B-<Z>.tar.gz | tar xf -
 
 
 GS (Graphic System)
@@ -309,110 +286,107 @@ GS (Graphic System)
 
 GS now Tcl/Tk 8.4. It will be searched for when starting GS.
 
-
 Using HiPE
 ----------
 
 HiPE supports the following system configurations:
 
 x86:
-	All 32-bit and 64-bit mode processors should work.
-
-	The following systems are supported:
-
-	Linux:
-		Fedora Core is supported.
-		Both 32-bit and 64-bit modes are supported.
-
-		NPTL glibc is strongly preferred, or a LinuxThreads
-		glibc configured for "floating stacks". Old non-floating
-		stacks glibcs have a fundamental problem that makes HiPE
-		support	and threads support mutually exclusive.
-	Solaris:
-		Solaris 10 (32-bit and 64-bit) and 9 (32-bit) are
-		supported.
-
-		The build requires a version of the GNU C compiler (gcc)
-		that has been configured to use the GNU assembler (gas).
-		Sun's x86 assembler is emphatically /not/ supported.
-	FreeBSD:
-		FreeBSD 6.1 and 6.2 in 32-bit and 64-bit modes should work.
-	MacOSX/Darwin:
-		Darwin 9.8.0 in 32-bit mode should work.
+    All 32-bit and 64-bit mode processors should work.
+
+    Linux:
+        Fedora Core is supported.
+        Both 32-bit and 64-bit modes are supported.
+
+        NPTL glibc is strongly preferred, or a LinuxThreads
+        glibc configured for "floating stacks". Old non-floating
+        stacks glibcs have a fundamental problem that makes HiPE
+        support	and threads support mutually exclusive.
+
+    Solaris:
+        Solaris 10 (32-bit and 64-bit) and 9 (32-bit) are supported.
+
+        The build requires a version of the GNU C compiler (gcc)
+        that has been configured to use the GNU assembler (gas).
+        Sun's x86 assembler is emphatically /not/ supported.
+
+    FreeBSD:
+        FreeBSD 6.1 and 6.2 in 32-bit and 64-bit modes should work.
+
+    MacOSX/Darwin:
+        Darwin 9.8.0 in 32-bit mode should work.
 
 PowerPC:
-	All 32-bit 6xx/7xx(G3)/74xx(G4) processors should work.
-	32-bit mode on 970 (G5) and POWER5 processors should work.
+    All 32-bit 6xx/7xx(G3)/74xx(G4) processors should work. 32-bit mode on
+    970 (G5) and POWER5 processors should work.
 
-	Linux (Yellow Dog) and Mac OSX 10.4 are supported.
+    Linux (Yellow Dog) and Mac OSX 10.4 are supported.
 
 SPARC:
-	All UltraSPARC processors running 32-bit user code should work.
+    All UltraSPARC processors running 32-bit user code should work.
+
+    Solaris 9 and Linux (Aurora) are supported.
 
-	Solaris 9 and Linux (Aurora) are supported.
+    On Solaris the build requires a gcc that has been configured to use Sun's
+    assembler and linker. Using the GNU assembler but Sun's linker has been
+    known to cause problems.
 
-	On Solaris the build requires a gcc that has been configured
-	to use Sun's assembler and linker. Using the GNU assembler but
-	Sun's linker has been known to cause problems.
 ARM:
-	ARMv5TE (i.e. XScale) processors should work.
-	Both big-endian and little-endian modes are supported.
+    ARMv5TE (i.e. XScale) processors should work. Both big-endian and
+    little-endian modes are supported.
 
-	Linux is supported.
+    Linux is supported.
 
 HiPE is automatically enabled on the following systems:
-	x86 in 32-bit mode: Linux, Solaris, FreeBSD
-	x86 in 64-bit mode: Linux, Solaris, FreeBSD
-	PowerPC: Linux, MacOSX
-	SPARC: Linux
-	ARM: Linux
-On other supported systems you need to "./configure --enable-hipe".
+    x86 in 32-bit mode: Linux, Solaris, FreeBSD
+    x86 in 64-bit mode: Linux, Solaris, FreeBSD
+    PowerPC: Linux, MacOSX
+    SPARC: Linux
+    ARM: Linux
 
+On other supported systems you need to "./configure --enable-hipe".
 
-If you are running on a platform supporting HiPE and if
-you have not disabled HiPE, you can compile a module into
-native code like this from the Erlang shell:
+If you are running on a platform supporting HiPE and if you have not disabled
+HiPE, you can compile a module into native code like this from the Erlang
+shell:
 
-	c(Module, native).
+    1> c(Module, native).
 
 or
 
-	c(Module, [native|OtherOptions]).
+    1> c(Module, [native|OtherOptions]).
 
 Using the erlc program, write like this:
 
-	erlc +native Module.erl
+    $ erlc +native Module.erl
 
-The native code will be placed into the beam file and automatically
-loaded when the beam file is loaded.
+The native code will be placed into the beam file and automatically loaded
+when the beam file is loaded.
 
 To add hipe options, write like this from the Erlang shell:
 
-	c(Module, [native,{hipe,HipeOptions}|MoreOptions]).
+    1> c(Module, [native,{hipe,HipeOptions}|MoreOptions]).
 
-Use
-
-	hipe:help_options().
-
-to print out the available options.
+Use hipe:help_options/0 to print out the available options.
 
+    1> hipe:help_options().
 
 Mac OS X (Darwin)
 -----------------
 
-We test Mac OS X 10.4.11 (Tiger) and Mac OS X 10.5.x (Leopard)
-in our daily builds (but only on Intel processors).
+We test Mac OS X 10.4.11 (Tiger) and Mac OS X 10.5.x (Leopard) in our daily
+builds (but only on Intel processors).
 
-Make sure that the command "hostname" returns a valid fully qualified
-host name (this is configured in "/etc/hostconfig").
+Make sure that the command "hostname" returns a valid fully qualified host
+name (this is configured in "/etc/hostconfig").
 
 If you develop linked-in drivers (shared library) you need to link
-using "gcc" and the flags "-bundle -flat_namespace -undefined
-suppress". You also include "-fno-common" in CFLAGS when
+using "gcc" and the flags '-bundle -flat_namespace -undefined
+suppress'. You also include '-fno-common' in CFLAGS when
 compiling. Use ".so" as the library suffix.
 
 Universal 32bit binaries can be built on an Intel Mac using the
---enable-darwin-universal configure option. There still may occur
+'--enable-darwin-universal' configure option. There still may occur
 problems with certain applications using this option, but the base
 system should run smoothly.
 
@@ -420,16 +394,16 @@ When building universal binaries on a PowerPC Mac (at least on Tiger),
 you must point out a suitable SDK that contains universal binaries.
 For instance, to build universal binaries for Tiger (10.4):
 
-CFLAGS="-isysroot /Developer/SDKs/MacOSX10.4u.sdk" LDFLAGS="-isysroot /Developer/SDKs/MacOSX10.4u.sdk" 	./configure --enable-darwin-universal
-
-Also, if you run Leopard, but want to build for Tiger, you must do
+    $ CFLAGS="-isysroot /Developer/SDKs/MacOSX10.4u.sdk" \
+    LDFLAGS="-isysroot /Developer/SDKs/MacOSX10.4u.sdk" \
+    ./configure --enable-darwin-universal
 
-export MACOSX_DEPLOYMENT_TARGET=10.4
+Also, if you run Leopard, but want to build for Tiger, you must do by setting the MACOSX_DEPLOYMENT_TARGET environmental variable.
 
-before running the above configure command.
+    $ export MACOSX_DEPLOYMENT_TARGET=10.4
 
 Experimental support for 64bit x86 darwin binaries can be enabled
-using the --enable-darwin-64bit configure flag. The 64bit binaries are
+using the '--enable-darwin-64bit' configure flag. The 64bit binaries are
 best built and run on Leopard, but most of the system also works on
 Tiger (Tiger's 64bit libraries are, however, limited; therefore e.g. odbc,
 crypto, ssl etc. are not supported in Tiger). 64bit PPC binaries are not
@@ -438,7 +412,6 @@ test on).
 
 Universal binaries and 64bit binaries are mutually exclusive options.
 
-
 Make and the variable "ERL_TOP"
 -------------------------------
 
@@ -453,12 +426,11 @@ before you run make.
 For example, assume your GNU make program is called "make" and you
 want to rebuild the application STDLIB, then you could do:
 
-  cd lib/stdlib; env ERL_TOP=<Dir> make
+    $ cd lib/stdlib; env ERL_TOP=<Dir> make
 
 where <Dir> would be what you find ERL_TOP is set to in the top level
 Makefile.
 
-
 Authors
 -------
 Authors are mostly listed in the application's AUTHORS files,
@@ -469,4 +441,4 @@ not in the individual source files.
 More Information
 ----------------
 
-More information can be found at http://www.erlang.org.
+More information can be found at http://www.erlang.org/.