Update README

Author: tschaffter

README.md

@@ -2,51 +2,111 @@
 
 [![CircleCI](https://circleci.com/gh/tschaffter/cxx-dev-tools.svg?style=shield)](https://circleci.com/gh/tschaffter/cxx-dev-tools)
 
-Tools to support the development and CI of CXX projects.
+Tools for supporting the development of CXX projects
 
 ## Overview
 
-This repository provides tools and configurations that are meant to be unique
-across many GitHub repositories.
+This repo provides a growing list of tools.
 
-One of the tools provided by this repo is `cmake-format`, which is a CMake
-linter and format validator for CMake files. Developers use this tool to
-garantee that the content of all the CMake files in their project are formatted
-in the same way. In the case of modular projects composed of multiple GitHub
-repos, individual repos would typically import `cmake-format` independently of
-each other with the risk that repos may use different version of `cmake-format`.
-Moreover, `cmake-format` can take as input a confiration file that would be
-typicallly copied to each repo, thus potentially leading to format discrepencies
-across repositories.
+- CMake linter
+- CXX linter
+- Git hooks
 
-To solve the above issues, this repo provides a wrapper that enables
-`cmake-format` to be run from multiple repos while still using a single
-configuration file.
+This tools aim to support best coding practices like linting files, comfiguring
+a Git pre-commit hook, etc.
 
-## How to use this repository
+The main motivation for developing these tools is to address an issue that
+typically affects code bases that are organized into multiple repositories. In
+the example of a CMake linter:
 
-If you want to use the default configurations of the tools, simply add this repo
-as a git submodule to all your CXX projects that should have the same CXX and/or
-CMake formating.
+1. each repository may host a copy of the configuration that the linter must use
+2. each repository may define a different version of the linter
+
+Both elements contribute to introduce discrepencies in the code formatting and
+make the maintenance of the code base across multiple repositories more
+difficult.
+
+The solution proposed is to define both tools and configurations in
+one repository. This reposiutory can then be added as a Git submodule to
+multiple repositories that will then benefit from the same tools and
+configurations.
+
+## Usage
+
+If you want to use the tool versions and configurations defined in this
+repository, simply add it as a git submodule to your projects.
+
+```bash
+git submodule add -b master https://github.com/tschaffter/cxx-dev-tools.git cxx-dev-tools
+```
+
+Run the following command to add the CXX dev tools to the PATH.
 
 ```bash
-git submodule add -b master https://github.com/tschaffter/cxx-dev-tools.git dev-cxx-tools
+cd dev-cxx-tools && . export.sh
 ```
 
-Then, add the CXX dev tools to your PATH.
+If you want to customize the tool versions and configuration, then fork this
+repository before adding it as a submodule to your other projects.
+
+## Tools
+
+### cxxdt-cmake-lint
+
+Check if the format of the specified CXX files is compliant with the CXX style
+configuration defined in this repo.
 
 ```bash
-cd dev-cxx-tools/
-. export.sh
+$ cxxdt-cmake-lint test/cmake-lint/samples/invalid-format.cmake
+test/cmake-lint/samples/invalid-format.cmake
+============================================
+test/cmake-lint/samples/invalid-format.cmake:10,04: [C0305] too many newlines between statements
+
+Summary
+=======
+files scanned: 1
+found lint:
+  Convention: 1
+
+$ echo $?
+1
+
+$ cxxdt-cmake-lint test/cmake-lint/samples/valid-format.cmake
+test/cmake-lint/samples/valid-format.cmake
+==========================================
+
+Summary
+=======
+files scanned: 1
+found lint:
+
+$ echo $?
+0
+```
+
+The exit status returned is 0 if the format of the file is valid.
+
+If no CMake files are specified, `cxxdt-cmake-lint` tries to read a list CMake
+files from `./.cxxdt-cmake-lint` (one file/file expression per line). The
+following command is used in the CI configuration of this repo to check that the
+CMake module `BuildType.cmake` is correctly formatted.
+
 ```
+$ cxxdt-cmake-lint
+cmake/BuildType.cmake
+=====================
+
+Summary
+=======
+files scanned: 1
+found lint:
+
+$ echo $?
+0
+```
+
 
-You can now run `run-cmake-format.sh CMAKE_FILES` to easily format `CMAKE_FILES`
-(e.g. `CMakeLists.txt`, `cmake/MyTool.cmake`, etc.) using the configuration file
-located in `cmake/format/.cmake-format.json`.
 
-In case you want to define your own CXX style, for example, fork this repo and
-modify the CXX format configuration, then add your fork as a submodule to your
-projects.
 
 ## Continuous Integration