1 files changed, 35 insertions, 17 deletions
diff --git a/Documentation/building.md b/Documentation/building.md
index 6283851..f198c77 100644
--- a/Documentation/building.md
+++ b/Documentation/building.md
@@ -1,26 +1,44 @@
-# Building from source
+# Building from Source
 A complete build of flow involves two parts
 
- 1. building scala sources (the front-end)
- 2. building native sources (the back-end)
+1. Building Scala sources (the front-end), resulting in a platform independent artifact (i.e. a jar file).
 
-As any java or scala project, the first part results in a platform independent artifact. However, the second part yields a binary that may only be used on systems resembling the platform for which it was compiled. Both steps are independent, their only interaction being the header files generated by javah (see `sbt javah` for details), and may therefore be built in part and in any order.
+2. Building C sources (the back-end), yielding a native library that may only be used on systems resembling the platform for which it was compiled
 
-## Compiling and packaging java/scala sources
-Run `sbt main/packageBin` in the base directory. This simply compiles any scala and java sources as with any standard sbt project and produces a jar ready for being used.
+Both steps are independent, their only interaction being a header file generated by the JDK utility `javah` (see `sbt javah` for details), and may therefore be built in any order.
 
-## Compiling and linking native sources
-The back-end is managed by GNU Autotools and all relevant files are contained in 'flow-native'. The first time, run `./bootstrap`, then `./configure && make` to compile the back-end. After completing this step, native libraries for the different platforms are available to be copied and included in end-user applications or installed on the system. To copy the binaries to a local directory, run ```DESTDIR=`pwd`/<directory> make install```. To install them system-wide, simply run `make install` as an administrator.
+## Building Scala Sources
+Run `sbt flow/packageBin` in the base directory. This simply compiles Scala sources as with any standard SBT project and packages the resulting class-files in a jar.
 
-## Creating a fat jar
-The native binaries produced in the previous step may be bundled in a "fat" jar so that they can be included in sbt projects through its regular dependency mechanisms. In this process, sbt basically acts as a wrapper script around autotools, calling the native build process and packaging generated binaries. Running `sbt native/packageBin` in the base directory produces the fat jar in 'flow-native-sbt/target'.
+## Building Native Sources
+The back-end is managed by GNU Autotools and all relevant files are contained in `flow-native`.
 
-Note: an important feature of fat jars is to include binaries for several platforms. To copy binaries compiled on other platforms to the fat jar, place them in a subfolder of 'flow-native-sbt/lib_native'. The subfolder should have the name `$(os.name)-$(os.arch)`, where `os.name` and `os.arch` are the java system properties of the respective platforms.
+Several steps are involved in producing the native library:
 
-# Note about versioning
-A versioning quirk to be aware of is when building native sources. In this case, the project and package versions follow a sematic pattern: `M.m.p`, where
- - `M` is the major version, representing backwards incompatible changes
- - `m` is the minor version, indicating backwards compatible changes such as new feature additions
- - `p` is the patch number, representing internal modifications such as bug-fixes
+1. When compiling for the first time, initialize Autotools by running the script `./bootstrap`.
+
+2. Once initialized, `./configure && make` will build the back-end.
+
+3. The native library is now ready and can be:
+
+	- copied to a local directory: `DESTDIR=$(pwd)/<directory> make install`
+
+    - installed system-wide: `make install`
+
+    - put into a "fat" jar, useful for dependency management with SBT (see next section)
+
+### Creating a Fat Jar
+The native library produced in the previous step may be bundled into a "fat" jar so that it can be included in SBT projects through its regular dependency mechanisms. In this process, SBT basically acts as a wrapper script around Autotools, calling the native build process and packaging generated libraries. Running `sbt flow-native/packageBin` in the base directory produces the fat jar in `flow-native-sbt/target`.
+
+Note: an important feature of fat jars is to include native libraries for several platforms. To copy binaries compiled on other platforms to the fat jar, place them in a subfolder of `flow-native-sbt/lib_native`. The subfolder should have the name `$(os.name)-$(os.arch)`, where `os.name` and `os.arch` are the Java system properties of the respective platforms.
+
+### Note About Versioning
+The project and package versions follow a sematic pattern: `M.m.p`, where
+
+- `M` is the major version, representing backwards incompatible changes
+
+- `m` is the minor version, indicating backwards compatible changes such as new feature additions
+
+- `p` is the patch number, representing internal modifications such as bug-fixes
  
-Usually (following most linux distribution's conventions), shared libraries produced by a project `name` of version `M.m.p` are named `libname.M.m.p`. However, since when accessing shared libraries through the JVM, only the `name` can be specified and no particular version, the convention adopted by flow is to append `M` to the library name and always keep the major version at zero. E.g. `libflow.3.1.2` becomes `libflow3.0.1.2`.
+Usually (following most Linux distribution's conventions), shared libraries produced by a project `name` of version `M.m.p` are named `libname.so.M.m.p`. However, since when accessing shared libraries through the JVM, only the `name` can be specified and no particular version, the convention adopted by flow is to append `M` to the library name and always keep the major version at zero. E.g. `libflow.so.3.1.2` becomes `libflow3.so.0.1.2`.