docs: mention quantity_point where appropriate

docs/framework/basic_concepts.rst

@@ -3,8 +3,8 @@
 Basic Concepts
 ==============
 
-The most important concepts in the library are `Unit`, `Dimension`, and
+The most important concepts in the library are `Unit`, `Dimension`,
-`Quantity`:
+`Quantity` and `QuantityPoint`:
 
 .. image:: /_static/img/concepts.png
     :align: center
@@ -37,3 +37,5 @@ derived dimensions.
 
 `Quantity` is a concrete amount of a unit for a specified dimension with a
 specific representation.
+
+`QuantityPoint` is an absolute `Quantity` with respect to some origin.

docs/framework/conversions_and_casting.rst

@@ -55,8 +55,9 @@ Implicit conversions are allowed only across quantities of the same dimension:
 Explicit
 --------
 
-Explicit conversions are available with a `quantity_cast` function template. They
+Explicit conversions are available with
-are especially useful to force a truncating conversion across quantities of the same
+the `quantity_cast` and `quantity_point_cast` function templates.
+They are especially useful to force a truncating conversion across quantities of the same
 dimension for integral representation types and ratios that may cause precision loss::
 
     si::length<si::kilometre, int> d1 = quantity_cast<kilometre>(1km + 1m);    // OK
@@ -88,6 +89,12 @@ once and leave the rest intact:
 - line #2 forces only a specific destination unit type,
 - line #3 sets only a representation type to the type provided by the user.
 
+`quantity_point_cast` takes anything that works for `quantity_point`
+or a specific target `quantity_point`:
+
+    std::cout << "Point: " << quantity_point_cast<decltype(quantity_point{0q_m})>(d)
+              << '\n';
+
 .. seealso::
 
     For more information on conversion and casting and on how to extend the above "integral"

docs/framework/dimensions.rst

@@ -61,6 +61,37 @@ dimension, than we will end up with just a scalar type:
     Scalar auto v1 = dur1 / dur2;    // 5
     Scalar auto v2 = dur1 * fr1;     // 50
 
+Quantity points have a more restricted set of operations.
+Quantity points can't be added together,
+but can be added to or subtracted from quantities.
+The result will always be a quantity point of the same dimension:
+
+.. code-block::
+    :emphasize-lines: 3-4
+
+    Length auto dist1 = 2q_m;
+    Length auto dist2 = 1q_m;
+    QuantityPoint auto res1 = quantity_point{dist1} + dist2;
+    QuantityPoint auto res2 = dist1 + quantity_point{dist2};
+    QuantityPoint auto res3 = quantity_point{dist1} - dist2;
+
+.. note::
+
+    You can't subtract a quantity from a quantity point:
+
+    .. code-block::
+        Length auto dist1 = 2q_m;
+        Length auto dist2 = 1q_m;
+        auto res1 = dist1 - quantity_point{dist2};  // ERROR
+
+We can also substract two quantity points.
+The result is a relative quantity of the same dimension:
+
+    Length auto dist1 = 2q_m;
+    Length auto dist2 = 1q_m;
+    Length auto res1 = quantity_point{dist1} - quantity_point{dist2};
+
+That's it! You can't multiply nor divide quantity points with anything else.
 
 Base Dimensions
 ---------------

docs/framework/quantity_points.rst

@@ -36,3 +36,5 @@ Unlike `quantity`, the library provides
 - no UDLs for quantity points,
 - no dimension-specific concepts, such as `LengthPoint`
   (there's the dimension-agnostic `QuantityPoint`),
+- a more limited set of operations on quantity points
+  (see the :ref:`Conversions and Casting` chapter)

docs/framework/text_output.rst

@@ -6,6 +6,10 @@ Text Output
 Beside providing dimensional analysis and units conversions, the library
 also tries really hard to print any quantity in the most user friendly way.
 
+.. note::
+
+    The library provides no text output for quantity points.
+
 Output Streams
 --------------
 

docs/use_cases/legacy_interfaces.rst

@@ -4,8 +4,9 @@ Working with Legacy Interfaces
 ==============================
 
 In case we are working with a legacy/unsafe interface we may be forced to
-extract a :term:`value of a quantity` with :func:`quantity::count()` and
+extract the :term:`value of a quantity` with :func:`quantity::count()` or to
-pass it to the library's output:
+extract the :term:`value of a quantity_point` with :func:`quantity_point::relative()`
+and pass it to the library's output:
 
 .. code-block::
     :caption: legacy.h
@@ -13,6 +14,7 @@ pass it to the library's output:
     namespace legacy {
 
     void print_eta(double speed_in_mps);
+    void set_path_position(double meter);
 
     } // namespace legacy
 
@@ -20,6 +22,7 @@ pass it to the library's output:
 
     #include "legacy.h"
     #include <units/physical/si/speed.h>
+    #include <units/quantity_point.h>
 
     using namespace units::physical;
 
@@ -34,6 +37,13 @@ pass it to the library's output:
       legacy::print_eta(quantity_cast<si::metre_per_second>(v).count());
     }
 
+    template <QuantityPoint QP>
+      requires Length<typename QP::quantity_type>
+    void set_path_position(QP p)
+    {
+      legacy::set_path_position(quantity_point_cast<si::metre>(p).relative().count());
+    }
+
 .. important::
 
     When dealing with a quantity of an unknown ``auto`` type please remember