doc: Move README to README.md (With formatting update)

The markdown syntax is more web-friendly for the platform
we are currently using as code repository.

README.md

@@ -1,21 +1,19 @@
 
-    The Network Simulator, Version 3
-    --------------------------------
+The Network Simulator, Version 3
+================================
 
-Table of Contents:
-------------------
+## Table of Contents:
 
-1) An overview
-2) Building ns-3
-3) Running ns-3
-4) Getting access to the ns-3 documentation
-5) Working with the development version of ns-3
+1) [An overview](#an-open-source-project)
+2) [Building ns-3](#building-ns-3)
+3) [Running ns-3](#running-ns3)
+4) [Getting access to the ns-3 documentation](#getting-access-to-the-ns-3-documentation)
+5) [Working with the development version of ns-3](#working-with-the-development-version-of-ns-3)
 
 Note:  Much more substantial information about ns-3 can be found at
 http://www.nsnam.org
 
-1) An Open Source project
--------------------------
+## An Open Source project
 
 ns-3 is a free open source project aiming to build a discrete-event
 network simulator targeted for simulation research and education.   
@@ -34,8 +32,7 @@ This README excerpts some details from a more extensive
 tutorial that is maintained at:
 http://www.nsnam.org/documentation/latest/
 
-2) Building ns-3
-----------------
+## Building ns-3
 
 The code for the framework and the default models provided
 by ns-3 is built as a set of libraries. User simulations
@@ -49,35 +46,42 @@ included in the file doc/build.txt
 
 However, the real quick and dirty way to get started is to
 type the command
-  ./waf configure --enable-examples
+```shell
+./waf configure --enable-examples
+```
+
 followed by
-  ./waf 
-in the directory which contains
-this README file. The files built will be copied in the
-build/ directory.
+
+```shell
+./waf
+```
+
+in the directory which contains this README file. The files
+built will be copied in the build/ directory.
 
 The current codebase is expected to build and run on the
-set of platforms listed in the RELEASE_NOTES file.
+set of platforms listed in the [release notes](RELEASE_NOTES)
+file.
 
 Other platforms may or may not work: we welcome patches to 
 improve the portability of the code to these other platforms. 
 
-3) Running ns-3
----------------
+## Running ns-3
 
 On recent Linux systems, once you have built ns-3 (with examples
 enabled), it should be easy to run the sample programs with the
 following command, such as:
 
-  ./waf --run simple-global-routing
+```shell
+./waf --run simple-global-routing
+```
 
-That program should generate a simple-global-routing.tr text 
-trace file and a set of simple-global-routing-xx-xx.pcap binary
-pcap trace files, which can be read by tcpdump -tt -r filename.pcap
+That program should generate a `simple-global-routing.tr` text
+trace file and a set of `simple-global-routing-xx-xx.pcap` binary
+pcap trace files, which can be read by `tcpdump -tt -r filename.pcap`
 The program source can be found in the examples/routing directory.
 
-4) Getting access to the ns-3 documentation
--------------------------------------------
+## Getting access to the ns-3 documentation
 
 Once you have verified that your build of ns-3 works by running
 the simple-point-to-point example as outlined in 3) above, it is
@@ -102,16 +106,18 @@ This documentation includes:
     as introductory text:
     http://www.nsnam.org/doxygen/index.html
 
-5) Working with the development version of ns-3
------------------------------------------------
+## Working with the development version of ns-3
 
 If you want to download and use the development version 
-of ns-3, you need to use the tool 'mercurial'. A quick and
-dirty cheat sheet is included in doc/mercurial.txt but
+of ns-3, you need to use the tool `mercurial`. A quick and
+dirty cheat sheet is included in
+[doc/mercurial.txt](doc/mercurial.txt) but
 reading through the mercurial tutorials included on the
 mercurial website is usually a good idea if you are not
 familiar with it.
 
 If you have successfully installed mercurial, you can get
 a copy of the development version with the following command:
-"hg clone http://code.nsnam.org/ns-3-dev"
+```shell
+hg clone http://code.nsnam.org/ns-3-dev
+```