docs: various small documentation fixes

docs/design/downcasting.rst

@@ -20,7 +20,7 @@ quantity. Other libraries will do it in the following way::
                                                            exponent<si::dim_time, 4>>;
 
 The above solution does provide a good developer's experience but a really poor one for the end
-user. If we will get a compilation error message containing `dim_capacitance` in most cases
+user. If we will get a compilation error message containing ``dim_capacitance`` in most cases
 the compiler will print the following type instead of the alias::
 
     units::detail::derived_dimension_base<units::exponent<units::physical::si::dim_electric_current, 2, 1>,
@@ -29,12 +29,12 @@ the compiler will print the following type instead of the alias::
 
 You can notice that in case of **mp-units** even this long syntax was carefully selected to
 provide quite good user experience (some other units libraries produce a type that cannot easily
-fit on one slide) but it is not questionable less readable than just `dim_capacitance`.
+fit on one slide) but it is not questionable less readable than just ``dim_capacitance``.
 
 .. note::
 
     To better understand how the framework works and not clutter the text and graphs with
-    long types in the following examples we will switch from `dim_capacitance` to `dim_area`.
+    long types in the following examples we will switch from ``dim_capacitance`` to ``dim_area``.
     The latter one has much shorter definition but the end result for both will be exactly the same -
     user-friendly, short name printed by the compiler and the debugger.
 
@@ -52,7 +52,7 @@ to use inheritance:
 
 This gives us a nice looking strong type when directly used by the user. However, we just got
 ourselves into problems. The library's framework does not know how to switch from a long
-instantiation of a `derived_dimension_base` class template that was generated as a result
+instantiation of a ``derived_dimension_base`` class template that was generated as a result
 of dimensional calculation to a nicely named child class assigned by the user for this
 instantiation.
 
@@ -87,7 +87,7 @@ In the above example:
 
 - ``dim_area`` is a downcasting target (child class)
 
-- `detail::derived_dimension_base` class template instantiation is a downcasting source (base class)
+- ``detail::derived_dimension_base`` class template instantiation is a downcasting source (base class)
 
 - `downcast_base` is a class that implements :abbr:`CRTP (Curiously Recurring Template Pattern)`
   idiom, stores the base of a downcasting operation in a ``downcast_base_type`` member type,
@@ -137,10 +137,10 @@ Until now we scoped on how we define the base and target of a downcasting operat
 perform the actual downcasting operation a dedicated alias template is provided::
 
     template<Downcastable T>
-    using downcast = decltype(detail::downcast_target_impl<T>());
+    using downcast = decltype(detail::downcast_impl<T>());
 
 `downcast` is used to obtain the target type of the downcasting operation registered for a
-given instantiation in a base type. `detail::downcast_target_impl` checks if a downcasting
+given instantiation in a base type. ``detail::downcast_impl`` checks if a downcasting
 target is registered for the specific base class. If yes, it returns the registered type,
 otherwise it works like a regular identity type trait returning a provided base class::
 
@@ -150,7 +150,7 @@ otherwise it works like a regular identity type trait returning a provided base
       concept has_downcast_guide = requires(T t) { downcast_guide(t); };
 
       template<typename T>
-      constexpr auto downcast_target_impl()
+      constexpr auto downcast_impl()
       {
         if constexpr(has_downcast_guide<T>)
           return decltype(downcast_guide(std::declval<downcast_base<T>>()))();

docs/faq.rst

@@ -30,12 +30,12 @@ different dimensions (i.e. height, width, and depth) all of them will just be
 measured in meters.
 
 
-Why other systems are defined in the `si` namespace?
+Why other systems are defined in the `physical::si` namespace?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-All systems defined in the `si` namespace are defined in terms of base units
+All systems defined in the `physical::si` namespace are defined in terms of
-that are convertible to the :term:`SI` units. This enables conversions of
+base units that are convertible to the :term:`SI` units. This enables conversions
-units of the same physical dimension between different systems.
+of units of the same physical dimension between different systems.
 
 .. seealso::
 
@@ -126,4 +126,4 @@ error: reference to ‘time’ is ambiguous
 Unfortunately, if `using-directives <https://en.cppreference.com/w/cpp/language/namespace#Using-directives>`_
 (i.e. ``using namespace units::physical::si``) are being used, `units::physical::si::time` will
 collide with C `time <https://en.cppreference.com/w/c/chrono/time>`_ function. In such a case the library's
-`time` function needs to be prefixed with at least one (or all) namespace names.
+``time`` function needs to be prefixed with at least one (or all) namespace names.

docs/framework/quantities.rst

@@ -7,9 +7,10 @@ A :term:`quantity` is a concrete amount of a unit for a specified dimension
 with a specific representation and is represented in the library with a
 `quantity` class template.
 
+.. _quantity-construction:
 
-Quantity Construction
+Construction
----------------------
+------------
 
 To create the quantity object from a :term:`scalable number` we just have to pass
 the value to the `quantity` class template explicit constructor::
@@ -189,7 +190,7 @@ are provided::
 
 There are two special units provided for usage with such a quantity:
 
-- `one` which is the :ref:`coherent unit` of dimensionless quantity and does not
+- `one` which is the :term:`coherent derived unit` of dimensionless quantity and does not
   provide any textual symbol (according to the ISO definition "the measurement units and
   values of quantities of dimension one are numbers"),
 - `percent` which has the symbol ``%`` and ``ratio(1, 100)`` of the `one` unit.

docs/framework/quantity_points.rst

@@ -3,13 +3,15 @@
 Quantity Points
 ===============
 
-A `quantity point` is an absolute quantity with respect to zero
+A quantity point is an absolute quantity with respect to zero
 (which represents some origin) and is represented in the library with a
 `quantity_point` class template.
 
 
-Quantity Point Construction
+.. _quantity-point-construction:
----------------------------
+
+Construction
+------------
 
 To create the quantity point object from a `quantity` we just have to pass
 the value to the `quantity_point` class template explicit constructor::

docs/framework/units.rst

@@ -24,7 +24,7 @@ Base Units
 ``m`` (meter) is a base unit of length, ``s`` (second) is a base unit of
 time. In each :term:`coherent system of units`, there is only one base
 unit for each base quantity. This is why a base unit type is required by
-the `base_dimension` definition in this library. For example `si::dim_length`
+the `base_dimension` definition in this library. For example ``si::dim_length``
 can be defined in the following way::
 
     namespace si {
@@ -33,7 +33,7 @@ can be defined in the following way::
 
     }
 
-where `si::metre` is defined as::
+where ``si::metre`` is defined as::
 
     namespace si {
 
@@ -43,8 +43,8 @@ where `si::metre` is defined as::
 
 In the above definition ``"m"`` is the unit symbol to be used in the text
 output, and ``si::prefix`` specifies that the library should allow
-definitions of prefixed units using `si::metre` as a reference (i.e.
+definitions of prefixed units using ``si::metre`` as a reference (i.e.
-`si::centimetre`).
+``si::centimetre``).
 
 .. seealso::
 
@@ -81,10 +81,10 @@ The fact that both base dimensions use the same identifier ``"L"`` tells
 the library that both definitions refer to the same physical dimension of
 length. The only difference is the measurement unit used to define their
 base dimensions. Thanks to using the unit that is defined in terms of the
-the same reference unit as the one provided to `si::dim_length` definition
+the same reference unit as the one provided to ``si::dim_length`` definition
-(namely `si::centimetre` which is ``1/100`` of `si::metre`) we also enabled
+(namely ``si::centimetre`` which is ``1/100`` of ``si::metre``) we also enabled
 the ability to easily convert between those 2 base dimensions (as the library
-knows how to convert `si::metre` to `si::centimetre` and vice versa).
+knows how to convert ``si::metre`` to ``si::centimetre`` and vice versa).
 
 .. seealso::
 
@@ -145,7 +145,7 @@ where ``kilogram_metre_per_second`` is defined as::
     struct kilogram_metre_per_second : unit<kilogram_metre_per_second> {};
 
 However, the easiest way to define momentum is just to use the
-`si::speed` derived dimension in the recipe:
+``si::speed`` derived dimension in the recipe:
 
 .. code-block::
     :emphasize-lines: 3
@@ -217,8 +217,8 @@ and define units like::
 
 Finally, the last of the `named_scaled_unit` class template parameters
 provide a reference unit for scaling. Please note that it can be a dimension's
-base/coherent unit (like `si::second`) or any other unit (i.e. `si::minute`,
+base/coherent unit (like ``si::second``) or any other unit (i.e. ``si::minute``,
-`si::hour`) that is a scaled version of the dimension's base/coherent unit.
+``si::hour``) that is a scaled version of the dimension's base/coherent unit.
 
 
 Prefixed Unit
@@ -272,7 +272,7 @@ domain::
     }
 
 With the definitions like above we can easily define prefixed unit. For
-example we can define `si::kilometre` as::
+example we can define ``si::kilometre`` as::
 
     namespace si {
 
@@ -303,7 +303,7 @@ ratio in reference to "metre per second":
 Whichever, we choose there will always be someone not happy with our choice.
 
 Thanks to a `deduced_unit` class template provided by the library this problem
-does not exist at all. With it `si::kilometre_per_hour` can be defined as::
+does not exist at all. With it ``si::kilometre_per_hour`` can be defined as::
 
     namespace si {
 
@@ -392,12 +392,12 @@ unknown/undefined unit type like in the below example::
     Length auto l = 100_q_km_per_h * 10_q_s;
 
 The type of ``l`` above will be
-:expr:`si::length<scaled_unit<ratio(1, 36, 1), si::metre>, long double>`. This is caused
+``si::length<scaled_unit<ratio(1, 36, 1), si::metre>, long double>``. This is caused
 by the fact that the library does not define a unit of a length quantity that has the
-ratio ``10/36`` of a `si::metre`. If such a unit was predefined we would see its concrete
+ratio ``10/36`` of a ``si::metre``. If such a unit was predefined we would see its concrete
 type here instead.
 
 .. seealso::
 
     To learn more about unknown units please refer to
-    :ref:`Working with Unknown Units and Dimensions` chapter.
+    :ref:`Working with Unknown Dimensions and Their Units` chapter.

docs/glossary.rst

@@ -44,21 +44,21 @@ ISO 80000 [1]_ definitions
         the Imperial System, etc.
 
     base quantity
-      - `Quantity` in a conventionally chosen subset of a given `system of quantities`, where
+      - `Quantity <quantity>` in a conventionally chosen subset of a given `system of quantities`,
-        no `quantity` in the subset can be expressed in terms of the other `quantities <quantity>`
+        where no `quantity` in the subset can be expressed in terms of the other
-        within that subset.
+        `quantities <quantity>` within that subset.
       - Base quantities are referred to as being mutually independent since a base quantity
         cannot be expressed as a product of powers of the other base quantities.
 
     derived quantity
-      - `Quantity`, in a `system of quantities`, defined in terms of the base quantities of
+      - `Quantity <quantity>`, in a `system of quantities`, defined in terms of the base
-        that system.
+        quantities of that system.
 
     International System of Quantities
     ISQ
-      - `System of quantities` based on the seven `base quantities <base quantity>`:
+      - `System of quantities <system of quantities>` based on the seven
-        length, mass, time, electric current, thermodynamic temperature, amount of substance,
+        `base quantities <base quantity>`: length, mass, time, electric current, thermodynamic
-        and luminous intensity.
+        temperature, amount of substance, and luminous intensity.
       - The International System of Units (SI) is based on the ISQ.
 
     dimension of a quantity
@@ -130,9 +130,9 @@ ISO 80000 [1]_ definitions
       - For example, in the `ISQ` Newton, Pascal, and katal are derived units.
 
     coherent derived unit
-      - `Derived unit` that, for a given `system of quantities` and for a chosen set of
+      - `Derived unit <derived unit>` that, for a given `system of quantities` and for a chosen
-        `base units <base unit>`, is a product of powers of `base units <base unit>` with no
+        set of `base units <base unit>`, is a product of powers of `base units <base unit>` with
-        other proportionality factor than one.
+        no other proportionality factor than one.
       - A power of a `base unit` is the `base unit` raised to an exponent.
       - Coherence can be determined only with respect to a particular `system of quantities`
         and a given set of `base units <base unit>`. That is, if the metre and the second are
@@ -145,23 +145,24 @@ ISO 80000 [1]_ definitions
 
     coherent system of units
 
-      - `System of units`, based on a given `system of quantities`, in which the measurement
+      - `System of units <system of units>`, based on a given `system of quantities`, in which
-        unit for each `derived quantity` is a `coherent derived unit`.
+        the measurement unit for each `derived quantity` is a `coherent derived unit`.
       - A `system of units` can be coherent only with respect to a `system of quantities` and
         the adopted `base units <base unit>`.
 
     off-system measurement unit
     off-system unit
-      - `Measurement unit` that does not belong to a given `system of units`. For example, the
+      - `Measurement unit <measurement unit>` that does not belong to a given `system of units`.
-        electronvolt (:math:`≈ 1,602 18 × 10^{–19} J`) is an off-system measurement unit of energy with
+        For example, the electronvolt (:math:`≈ 1,602 18 × 10^{–19} J`) is an off-system measurement
-        respect to the `SI` or day, hour, minute are off-system measurement units of time with
+        unit of energy with respect to the `SI` or day, hour, minute are off-system measurement
-        respect to the `SI`.
+        units of time with respect to the `SI`.
 
     International System of Units
     SI
-      - `System of units`, based on the `International System of Quantities`, their names and
+      - `System of units <system of units>`, based on the `International System of Quantities`,
-        symbols, including a series of prefixes and their names and symbols, together with rules
+        their names and symbols, including a series of prefixes and their names and symbols,
-        for their use, adopted by the General Conference on Weights and Measures (CGPM)
+        together with rules for their use, adopted by the General Conference on Weights and
+        Measures (CGPM)
 
     quantity value
     value of a quantity

docs/reference/core/concepts.rst

@@ -32,7 +32,7 @@ Concepts
 .. concept:: template<typename T> DerivedDimension
 
     A concept matching all derived dimensions in the library. Satisfied by all dimension
-    types derived from the instantiation of :class:`detail::derived_dimension_base`.
+    types derived from the instantiation of ``detail::derived_dimension_base``.
 
 .. concept:: template<typename T> Dimension
 
@@ -48,7 +48,7 @@ Concepts
 
     A concept matching only units of a specified dimension. Satisfied by all unit types that
     satisfy :expr:`Unit<U>`, :expr:`Dimension<D>`, and for which :expr:`U::reference` and
-    :expr:`dimension_unit<D>::reference` denote the same unit type.
+    ``dimension_unit<D>::reference`` denote the same unit type.
 
     :tparam U: Type to verify against concept constraints.
     :tparam D: Dimension type to use for verification.
@@ -61,7 +61,7 @@ Concepts
 
     A concept matching types that wrap quantity objects. Satisfied by all wrapper types that
     satisfy :expr:`Quantity<typename T::value_type>` recursively
-    (i.e. :expr:`std::optional<si::length<si::metre>>`).
+    (i.e. ``std::optional<si::length<si::metre>>``).
 
 .. concept:: template<typename T> ScalableNumber
 
@@ -79,17 +79,17 @@ Concepts
     A concept matching all quantity points in the library. Satisfied by all instantiations of
     :class:`quantity_point`.
 
-.. concept:: template<typename Dim, template<typename...> typename DimTemplate> concept DimensionOfT
+.. concept:: template<typename Dim, template<typename...> typename DimTemplate> DimensionOfT
 
     A concept matching all dimensions being the instantiations derived from the provided dimension
     class template.
 
-.. concept:: template<typename Q, template<typename...> typename DimTemplate> concept QuantityOfT
+.. concept:: template<typename Q, template<typename...> typename DimTemplate> QuantityOfT
 
     A concept matching all quantities with a dimension being the instantiation derived from
     the provided dimension class template.
 
-.. concept:: template<typename T, typename Dim> concept QuantityOf
+.. concept:: template<typename T, typename Dim> QuantityOf
 
     A concept matching all quantities with a dimension being the instantiation derived from
     the provided dimension type.

docs/use_cases/extensions.rst

@@ -57,7 +57,7 @@ Enabling a Unit for Prefixing
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In case I decide it is reasonable to express my desks with SI prefixes the only thing I have
-to change in the above code is to replace `no_prefix` with `si_prefix`::
+to change in the above code is to replace `no_prefix` with `physical::si::prefix`::
 
     struct desk : named_scaled_unit<desk, "desk", si::prefix, ratio(3, 10), si::square_metre> {};