readme documentation

README → README.md

@@ -1,20 +1,16 @@
-1 Intro
-2 Paxos Essentials
-3 Compile/Execute/Link
-4 Feedback
+LibPaxos2
+============
 
-====================== ***       Intro          *** ======================
+Intro
+---------
 
-LibPaxos2 is a complete rewrite of LibPaxos[1] on top of LibEvent 1.4 [2].
+LibPaxos2 is a complete rewrite of [LibPaxos](http://libpaxos.sourceforge.net) on top of [LibEvent 1.4](http://monkey.org/~provos/libevent/)
 
 Although this code has been extensively tested and benchmarked, it's comes as-it-is, it may contain bugs and should not be used where true reliability/fault tolerance is required.
 
-For more details and informations on the performances of this library, refer to [3]
+For more details and informations on the performances of this library, refer to:
 
-
-[1] http://libpaxos.sourceforge.net
-[2] http://monkey.org/~provos/libevent/
-[3] @mastersthesis{paxos-made-code,
+    @mastersthesis{paxos-made-code,
 		Title = {Paxos Made Code: Implementing a high throughput Atomic Broadcast},
 		Year = {2009}
 		Author = {Marco Primi},
@@ -23,9 +19,11 @@ For more details and informations on the performances of this library, refer to
 	}
 
 
-====================== ***   Paxos Essentials   *** ======================
+Paxos Essentials
+-------------------
+
+LibPaxos2 supplies the Atomic Broadcast primitive to a set of application processes.
 
-LibPaxos2 supplies the Atomic Broadcast[4] primitive to a set of application processes.
 A Paxos network is composed of the following actors:
 
  - Clients: application processes that want to send (ABroadcast) and/or receive (ADeliver) the Atomic Broadcast messages.
@@ -47,45 +45,61 @@ A Paxos network is composed of the following actors:
    The oracle in tests/example_oracle.c is not a really good example since it requires human intervention to pick a new leader (it ignores heartbeats) but it can be easily extended.
 
 
-Some practical details:
-- Each client process should initialize a single submit_handle.
-- Submitted values are (for the moment) sent to the proposer through UDP. Therefore they may be lost. The client must timeout on it's own if the case and retry to submit them.
-- Because (i) submit is unreliable and (ii) proposer-leader may crash, the broadcast is NOT FIFO, not even respect to a single client.
+**Some practical details**
+
+ - Each client process should initialize a single submit_handle.
+
+ - Submitted values are (for the moment) sent to the proposer through UDP. Therefore they may be lost. The client must timeout on 
+   it's own if the case and retry to submit them.
+
+ - Because (i) submit is unreliable and (ii) proposer-leader may crash, the broadcast is NOT FIFO, not even respect to a single client.
 
 
-====================== *** Compile/Execute/Link *** ======================
+Setup
+---------
 
 Before compiling LibPaxos, you need to have compiled both Berkeley DB and Libevent.
 
 Download BDB source code from http://www.oracle.com/technology/software/products/berkeley-db/db/index.html
-Extract it to some folder (i.e. ~/bdb) and follow the instructions included to compile (i.e. on unix-like: cd ~/bdb && ../dist/configure && make).
-~/bdb/build_unix/ should now contain the file libdb.a
+
+Extract it to some folder (i.e. ~/bdb) and follow the instructions included to compile, i.e., on unix-like: 
+
+    cd ~/bdb && ../dist/configure && make
+
+`~/bdb/build_unix/` should now contain the file `libdb.a`
 
 Download Libevent source from http://monkey.org/~provos/libevent-1.4.12-stable.tar.gz
-Extract it to some folder (i.e. ~/libevent) and follow the instructions included to compile (i.e. on unix-like: cd ~/libevent && ./configure && make).
-~/libevent/ should now contain the file libevent.a
+
+Extract it to some folder (i.e. ~/libevent) and follow the instructions included to compile, i.e., on unix-like: 
+
+    cd ~/libevent && ./configure && make
+
+`~/libevent/` should now contain the file `libevent.a`
 
 Update Makefile.inc in the main libpaxos directory to reflect the location of the library and header files for the two libraries.
 For example:
-BDB_DIR		= $(HOME)/bdb/build_unix
-LEV_DIR		= $(HOME)/libevent
+
+    BDB_DIR		= $(HOME)/bdb/build_unix
+    LEV_DIR		= $(HOME)/libevent
 
 Take a look at paxos_config.h to see if the default configuration fits your needs.
 You can now compile libpaxos with:
-cd libpaxos && make
+
+    cd libpaxos && make
+
+To see LibPaxos in action, you can launch an example script that starts all the required actors plus a simple client. (Requires the `xterm` command to open different windows!)
 
-To see LibPaxos in action, you can launch an example script that starts all the required actors plus a simple client. (Requires the xterm command to open different windows!)
+Edit the first variable of `scripts/local/run_example.sh` to reflect the placement of the LibPaxos tests/ directory on your filesystem. Example:
 
-Edit the first variable of scripts/local/run_example.sh to reflect the placement of the LibPaxos tests/ directory on your filesystem. Example:
-PROJ_DIR="/Users/bridge/Desktop/libpaxos/trunk/libpaxos2/tests" 
+    PROJ_DIR="/Users/bridge/Desktop/libpaxos/trunk/libpaxos2/tests" 
 
-To link your own program with LibPaxos, you can copy the compiler flags used for the test programs (i.e. look at tests/Makefile)
+To link your own program with LibPaxos, you can copy the compiler flags used for the test programs (i.e. look at `tests/Makefile`)
 
 
-====================== ***       Feedback       *** ======================
+Feedback
+-------------
 
-http://libpaxos.sourceforge.net/
+Any suggestion, comment, or question is welcome via SourceForge [mailing list](https://lists.sourceforge.net/lists/listinfo/libpaxos-general)
+or by contacting us directly.
 
-Any suggestion, comment, or question is welcome via SourceForge mailing list [1] or by contacting us directly.
 
-[1] https://lists.sourceforge.net/lists/listinfo/libpaxos-general