README: elaborate

3 files changed, 93 insertions, 42 deletions

diff --git a/README.md b/README.md
index a3473ca..ab2e623 100644
--- a/README.md
+++ b/README.md
@@ -4,34 +4,109 @@ cmake-common
 [![Travis (.com) branch](https://img.shields.io/travis/com/egor-tensin/cmake-common/master?label=Travis)](https://travis-ci.com/egor-tensin/cmake-common)
 [![AppVeyor branch](https://img.shields.io/appveyor/ci/egor-tensin/cmake-common/master?label=AppVeyor)](https://ci.appveyor.com/project/egor-tensin/cmake-common/branch/master)
 
-Various utility files to build my CMake projects, as those seem to overlap
-between different projects quite a bit.
-
-This repository is intended to be included as a submodule.
-Git submodules are relatively hard to use though, but there's [an excellent
-guide] to help you through.
-
-[an excellent guide]: https://medium.com/@porteneuve/mastering-git-submodules-34c65e940407
+Various utilities to help develop C++/CMake projects.
 
 Usage
 -----
 
-Using the scripts in this project, you can build
+### common.cmake
+
+Use in a project by putting
+
+    include(path/to/common.cmake)
+
+in CMakeLists.txt.
+
+This file aids in quick-and-dirty development by
+
+* linking everything (including the runtime) statically by default,
+* setting some useful compilation options (enables warnings, defines useful
+Windows-specific macros, strips debug symbols in release builds, etc.).
+
+Everything is optional (use the `CC_*` CMake options to opt out).
+
+### Bootstrap Boost
+
+Download & build the Boost libraries in a cross-platform way.
+
+    $ python3 -m project.boost.download 1.72.0
+    ...
+
+    $ python3 -m project.boost.build -- boost_1_72_0/ --with-filesystem --with-program_options
+    ...
+
+Pass the `--help` flag to view detailed usage information.
+
+    $ python3 -m project.boost.download --help
+    $ python3 -m project.boost.build --help
+
+### Build CMake project
+
+Build (and optionally, install) a CMake project.
+
+    $ python3 -m project.cmake.build --configuration Release --install path/to/somewhere -- examples/simple
+    ...
+
+    $ ./path/to/somewhere/bin/foo
+    foo
+
+Pass the `--help` flag to view detailed usage information.
+
+    $ python3 -m project.cmake.build --help
+
+### CI
+
+One of the goals was to merge my Travis & AppVeyor build scripts.
+They have nearly identical interfaces now.
+Internally, they call the generic scripts from above, auto-filling some
+parameters from environment variables.
+
+Pass the `--help` flag to a script to view detailed usage information.
+
+#### Travis
+
+Bootstrap Boost:
+
+    $ python3 -m project.ci.travis.boost -- --with-test
+
+Build a CMake project:
+
+    $ python3 -m project.ci.travis.cmake --install "$HOME/install"
+
+Environment variables:
+
+* `platform`,
+* `configuration`,
+* `boost_version`.
+
+#### AppVeyor
+
+Bootstrap Boost (seldom used, since AppVeyor pre-builds many Boost versions):
+
+    > C:\Python36-x64\python.exe -m project.ci.appveyor.boost -- --with-test
+
+Build a CMake project:
+
+    > C:\Python36-x64\python.exe -m project.ci.appveyor.cmake --install C:\projects\install
+
+Environment variables:
 
-* [Boost],
-* a [CMake project].
+* `PLATFORM`,
+* `CONFIGURATION`,
+* `boost_version`.
 
-All in a relatively cross-platform way.
+### clang-format.py
 
-It's used in a bunch of projects of mine, namely in
+`clang-format` all C/C++ files in a project.
 
-* [aes-tools],
-* [math-server]
+    $ cd project/
+    $ python3 path/to/tools/clang-format.py      # Prints a diff
+    $ python3 path/to/tools/clang-format.py -i   # Edits files in-place
 
-and a few others.
+Examples
+--------
 
-[Boost]: project/boost/README.md
-[CMake project]: project/cmake/README.md
+I use this in all of my C++/CMake projects, e.g. [aes-tools] and [math-server].
 
 [aes-tools]: https://github.com/egor-tensin/aes-tools
 [math-server]: https://github.com/egor-tensin/math-server
diff --git a/project/boost/README.md b/project/boost/README.md
deleted file mode 100644
index 5c8240c..0000000
--- a/project/boost/README.md
+++ /dev/null
@@ -1,12 +0,0 @@
-Boost
-=====
-
-Download & build the Boost libraries in a cross-platform way.
-
-A simple usage example to download and build Boost 1.72.0:
-
-    $ python3 -m project.boost.download 1.72.0
-    ...
-
-    $ python3 -m project.boost.build -- boost_1_72_0/ --with-filesystem --with-program_options
-    ...
diff --git a/project/cmake/README.md b/project/cmake/README.md
deleted file mode 100644
index 7a488d9..0000000
--- a/project/cmake/README.md
+++ /dev/null
@@ -1,12 +0,0 @@
-CMake
-=====
-
-Build a CMake project.
-
-A simple usage example:
-
-    $ python3 -m project.cmake.build --configuration Release --install path/to/somewhere -- examples/simple
-    ...
-
-    $ ./path/to/somewhere/bin/foo
-    foo