xo-unit: ++ github README

README.md

@@ -11,46 +11,86 @@ Similar to `boost::units`,  but:
 - xo-unit documentation [under construction]: [documentation](https://rconybea.github.io/web/xo-unit/html/index.html)
 - unit test coverage here: [coverage](https://rconybea.github.io/web/xo-unit/ccov/html/index.html)
 
+## Example
+
+```
+#include "xo/unit/quantity.hpp"
+#include "xo/unit/quantity_iostream.hpp"
+
+namespace q = xo::qty::qty;
+namespace u = xo::qty::u;
+
+constexpr auto t = q::minutes(2);
+constexpr auto d = q::kilometers(2.5);
+
+constexpr auto t2 = t*t;   // unit will be min^-2
+constexpr auto a = d / t2; // unit will be km.min^-2
+
+// convert to m.s^-2
+constexpr quantity<u::meter / (u::second * u::second)> a2 = a;
+
+//constexpr quantity<u::meter> a3 = a;  // dimension mismatch, will not compile
+
+// get dimensionless scale value
+double x = a2.scale();
+```
+
 ## Getting Started
 
-### build + install dependencies
+See [full install instructions](https://rconybea.github.io/web/xo-unit/html/install.html) for other installation strategies.
 
-- [github/Rconybea/reflect](https://github.com/Rconybea/reflect)
+### build + install upstream dependencies
+
+- [github/Rconybea/xo-cmake](https://github.com/Rconybea/xo-cmake)
+- [github/Rconybea/xo-flatstring](https://github.com/Rconybea/xo-flatstring)
+- [github/Rconybea/xo-ratio](https://github.com/Rconybea/xo-ratio)
+
+(Below assumes they're installed using some common value for `PREFIX`)
+
+### fetch xo-unit
+```
+$ cd ~/proj
+$ git clone https://github.com/rconybea/xo-unit
+```
 
 ### build + install
 ```
 $ cd xo-unit
-$ mkdir .build
-$ cd .build
 $ PREFIX=/usr/local  # or wherever you prefer
-$ cmake -DCMAKE_MODULE_PATH=${PREFIX}/share/cmake -DCMAKE_PREFIX_PATH=${PREFIX} -DCMAKE_INSTALL_PREFIX=${PREFIX} ..
-$ make
-$ make install
+$ cmake -DCMAKE_INSTALL_PREFIX=${PREFIX} -S . -B .build
+$ cmake --build .build -j
+$ cmake --install .build
 ```
 
 ### build documentation
 ```
 $ cd xo-unit
-$ cmake --build .build -- sphinx
+$ cmake -DCMAKE_INSTALL_PREFIX=${PREFIX}  --build .build -- sphinx
 ```
-When this completes,  point local browser to `xo-unit/.build/docs/sphinx/index.html`.
+When this completes,  can point local browser to `xo-unit/.build/docs/sphinx/index.html`.
 
 ### build for unit test coverage
+
+Note that unit tests involve additional dependencies:
+- [github/Rconybea/xo-indentlog](https://github.com/Rconybea/indentlog)
+- [github/Rconybea/xo-randomgen](https://github.com/Rconybea/randomgen)
+
 ```
 $ cd xo-unit
 $ mkdir .build-ccov
-$ cmake -DCMAKE_BUILD_TYPE=coverage -DCMAKE_PREFIX_PATH=${PREFIX} -B .build-ccov
+$ cmake -DCMAKE_BUILD_TYPE=coverage -DCMAKE_INSTALL_PREFIX=${PREFIX} -DENABLE_TESTING=1 -B .build-ccov
 ```
 
-run coverage-enabled unit tests
+run coverage-enabled unit tests:
 ```
 $ cmake --build .build-ccov -- test
 ```
 
-generate html+text coverage report
+generate html+text coverage report:
 ```
-$cmake --build .build-ccov -- ccov
+$ .build-ccov/gen-ccov
 ```
+To see coverage,  can point local browser to `xo-unit/.build-ccov/ccov/html/index.html`
 
 ### LSP support
 ```

docs/install.rst

@@ -65,7 +65,7 @@ Installing from source
 ----------------------
 
 Install scripts for `xo-unit`, `xo-ratio` and `xo-flatstring` depend on shared cmake macros
-and a bootstrap script `xo-cmake-config` fro `xo-cmake`.
+and a bootstrap script `xo-cmake-config` from `xo-cmake`.
 
 Preamble: