From 381337357ecba858b05c4e681a6f583cf0409cbd Mon Sep 17 00:00:00 2001
From: Thomas Nagy <tnagy@waf.io>
Date: Sun, 13 Mar 2016 09:17:09 +0100
Subject: [PATCH] docs

---
 README    | 43 -------------------------------------------
 README.md | 46 +++++++++++++++++++++++++++++++++++++++++++++-
 TODO      |  1 -
 3 files changed, 45 insertions(+), 45 deletions(-)
 delete mode 100644 README

diff --git a/README b/README
deleted file mode 100644
index 8e6f365a..00000000
--- a/README
+++ /dev/null
@@ -1,43 +0,0 @@
-WHAT YOU WILL FIND HERE
------------------------
-
-Waf 1.8 - Recently moved to https://github.com/waf-project/waf
-
-For the manual: https://waf.io/book/
-For the API documentation: https://waf.io/apidocs/
-For the examples: see the folder demos/ and the folder playground/
-
-HOW TO CREATE THE WAF SCRIPT
-----------------------------
-
-Python 2.6, 2.7, 3.0, 3.1, 3.2, 3.3 or 3.4 is required to generate the waf script. The waf script is then the version that can run on Python 2.5.
-Just execute:
-$ ./waf-light configure build
-Or, if you have several python versions installed:
-$ python3 ./waf-light configure build
-
-The Waf tools in waflib/extras are not added to the waf script. To add
-some of them, use the --tools switch:
-$ ./waf-light --tools=compat15,swig
-
-To add a tool that does not exist in the folder extras, pass an absolute path, and
-to customize the initialization, pass the parameter 'prelude'. Here is for example
-how to create a waf file using the compat15 module:
-$ ./waf-light --tools=compat15 --prelude=$'\tfrom waflib.extras import compat15\n'
-
-Any kind of initialization is possible, though one may prefer the build system kit (folder build_system_kit):
-$ ./waf-light --make-waf --tools=compat15,/comp/waf/aba.py --prelude=$'\tfrom waflib.extras import compat15\n\tprint("ok")'
-
-Or if you do not want to regenerate the waf file all the time, set the WAFDIR environment variable to the directory containing "waflib".
-
-HOW TO TRY THE EXAMPLES
------------------------
-
-Try this:
-$ cp waf demos/c/
-$ cd demos/c/
-$ ./waf configure build
-
----------------------------
-Thomas Nagy, 2014-2015 (ita)
-
diff --git a/README.md b/README.md
index 458f358b..653ec8c0 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,5 @@
+## ABOUT WAF
+
 Waf is a Python-based framework for configuring, compiling and installing applications. Here are perhaps the most important features of Waf:
 
   * *Automatic build order*: the build order is computed from input and output files, among others
@@ -13,4 +15,46 @@ Waf is used in particular by innovative companies such as [Avalanche Studios](ht
 
 For researchers and build system writers, Waf also provides a framework for creating [custom build systems](https://github.com/waf-project/waf/tree/master/build_system_kit) and [package distribution systems](https://github.com/waf-project/waf/tree/master/playground/distnet/README.rst).
 
-Download the project from our page on [waf.io](https://waf.io/) or from the mirror on [freehackers.org](http://www.freehackers.org/~tnagy/release/).
+Download the project from our page on [waf.io](https://waf.io/) or from the mirror on [freehackers.org](http://www.freehackers.org/~tnagy/release/), consult the [manual](https://waf.io/book/), the [API documentation](https://waf.io/apidocs/) and the [showcases](https://github.com/waf-project/waf/tree/master/demos) and [experiments](https://github.com/waf-project/waf/tree/master/playground).
+
+## HOW TO CREATE THE WAF SCRIPT
+
+Python >= 2.6 3.4 is required to generate the waf script, and the resulting file can then run on Python 2.5.
+Just execute:
+```sh
+$ ./waf-light configure build
+```
+Or, if you have several python versions installed:
+```sh
+$ python3 ./waf-light configure build
+```
+
+The Waf tools in waflib/extras are not added to the waf script. To add
+some of them, use the --tools switch:
+```sh
+$ ./waf-light --tools=compat15,swig
+```
+
+To add a tool that does not exist in the folder extras, pass an absolute path, and
+to customize the initialization, pass the parameter 'prelude'. Here is for example
+how to create a waf file using the compat15 module:
+```sh
+$ ./waf-light --tools=compat15 --prelude=$'\tfrom waflib.extras import compat15\n'
+```
+
+Any kind of initialization is possible, though one may prefer the build system kit (folder build\_system\_kit):
+```sh
+$ ./waf-light --make-waf --tools=compat15,/comp/waf/aba.py --prelude=$'\tfrom waflib.extras import compat15\n\tprint("ok")'
+```
+
+Or, to avoid regenerating the waf file all the time, just set the `WAFDIR` environment variable to the directory containing "waflib".
+
+## HOW TO TRY THE EXAMPLES
+
+Try this:
+```sh
+cp waf demos/c/
+cd demos/c/
+./waf configure build
+```
+
diff --git a/TODO b/TODO
index 57bd099d..2b2cb07c 100644
--- a/TODO
+++ b/TODO
@@ -7,6 +7,5 @@ Waf 1.9
 * Rework qt5
 * Use relative paths in apply_incpaths (and absolute ones when paths cross drives)
 * Provide a more efficient ConfigSet implementation
-* Ensure _cache.py are valid python files
 * Other issues listed on https://github.com/waf-project/waf/issues