xo-unit: streamline unit spec + docs

docs/CMakeLists.txt

@@ -3,7 +3,7 @@
 xo_doxygen_collect_deps()
 xo_docdir_doxygen_config()
 xo_docdir_sphinx_config(
-    index.rst examples.rst glossary.rst install.rst implementation.rst
+    index.rst examples.rst glossary.rst install.rst implementation.rst development.rst
     quantity-reference.rst quantity-class.rst quantity-factoryfunctions.rst quantity-unitvars.rst
     unit-reference.rst unit-concept.rst unit-quantities.rst basis-unit-reference.rst
     basis-unit-class.rst basis-unit-constants.rst

docs/development.rst

@@ -0,0 +1,18 @@
+.. _development:
+
+Miscellaneous development notes for *xo-unit*.
+
+How To...
+=========
+
+Add Basis Unit
+--------------
+
+To add a basis unit for an existing dimension:
+
+#. add unit definition to the ``xo::qty::bu`` namespace in ``include/xo/unit/basis_unit.hpp``
+#. add call to ``bu_store::bu_establish_abbrev()`` from  ``bu_store::bu_store``.
+#. add ``natural_unit`` definition to ``xo::qty::nu`` namespace in ``include/xo/unit/natural_unit.hpp``
+#. add ``scaled_unit`` definition to ``xo::qty::u`` namespace in ``include/xo/unit/scaled_unit.hpp``.
+#. add unit quantity to ``xo::qty::qty`` namespace in ``include/xo/unit/quantity.hpp``
+#. add factory function to ``xo::qty::qty`` namespace in ``include/xo/unit/quantity.hpp``

docs/implementation.rst

@@ -15,7 +15,9 @@ Abstraction tower for *xo-unit* components.
     |     natural_unit      |
     +-----------------------+
     |          bpu          |
-    +-----------------------+
+    +-----------+           |
+    |  bu_store |           |
+    +-----------+-----------+
     |       basis_unit      |
     +-----------------------+
     |       dimension       |
@@ -50,6 +52,12 @@ Abstraction tower for *xo-unit* components.
 
   A power of a basis unit. Has a single dimension.
 
+- bu_store:
+
+  Associates basis units with abbreviations.
+
+  For example ``bu::kilogram`` => ``"kg"``
+
 - basis_unit: see :doc:`basis-unit-reference`.
 
   A unit with a single dimension and scale.
@@ -184,11 +192,15 @@ Worked example using :cpp:class:`xo::qty::quantity`
 .. code-block:: cpp
     :linenos:
 
-    namespace su = xo::qty::su;
+    namespace u = xo::qty::u;
 
     // (123*7.55) ng.km.min^-2  ==>  2.57958e-10kg.m.s^-2
 
-    quantity qty3b = qty3.rescale_ext<su::kilogram * su::meter / (su::second * su::second)>();
+    constexpr auto newton = u::kilogram * u::meter / (u::second * u::second);
+
+    quantity<newton> qty3b = qty3;
+
+    // quantity qty3b = qty3.rescale_ext<newton>();
 
 .. uml::
     :caption: quantity 928.65 ng.km.min^-2

docs/index.rst

@@ -33,6 +33,7 @@ runtime (since we can't construct new c++ types at runtime).
    install
    examples
    implementation
+   development
    unit-quantities
    quantity-reference
    unit-reference