docs: example apllications documentation updated for modules

docs/users_guide/examples/avg_speed.md

@@ -14,8 +14,8 @@ library features as possible, but we will scope on different interfaces one can
 with the **mp-units**. We will also describe some advantages and disadvantages of presented
 solutions.
 
-First, we include all the necessary header files and import all the identifiers from the
+First, we either import a module or include all the necessary header files and import all
-`mp_units` namespace:
+the identifiers from the `mp_units` namespace:
 
 ```cpp title="avg_speed.cpp" linenums="1"
 --8<-- "example/avg_speed.cpp:28:42"
@@ -52,11 +52,11 @@ Average speed of a car that makes 220 km in 2 h is 110 km/h.
 ```
 
 Please note that in the first two cases, we must convert length from `km` to `m` and
-time from `h` to `s`. The converted values are used to calculate speed in `m / s` which
+time from `h` to `s`. The converted values are used to calculate speed in `m/s` which
-is then again converted to the one in `km / h`. Those conversions not only impact the
+is then again converted to the one in `km/h`. Those conversions not only impact the
-application's runtime performance but may also affect the final result. Such truncation
+application's runtime performance but may also affect the precision of the final result.
-can be easily observed in the first case where we deal with integral representation types
+Such truncation can be easily observed in the first case where we deal with integral
-(the resulting speed is `108 km / h`).
+representation types (the resulting speed is `108 km/h`).
 
 The second scenario is really similar to the previous one, but this time, function arguments
 have floating-point representation types:
@@ -80,7 +80,7 @@ Average speed of a car that makes 220 km in 2 h is 110 km/h.
 ```
 
 Next, let's do the same for integral and floating-point representations, but this time
-using US Customary units:
+using international mile:
 
 ```cpp title="avg_speed.cpp" linenums="65"
 --8<-- "example/avg_speed.cpp:97:129"
@@ -88,17 +88,17 @@ using US Customary units:
 
 One important difference here is the fact that as it is not possible to make a lossless conversion
 of miles to meters on a quantity using an integral representation type, so this time, we need a
-`value_cast<si::metre>` to force it.
+`value_cast<m, int>` to force it.
 
 If we check the text output of the above, we will see the following:
 
 ```text
-US Customary Units with 'int' as representation
+International mile with 'int' as representation
 Average speed of a car that makes 140 mi in 2 h is 111 km/h.
 Average speed of a car that makes 140 mi in 2 h is 112.654 km/h.
 Average speed of a car that makes 140 mi in 2 h is 112 km/h.
 
-US Customary Units with 'double' as representation
+International mile with 'double' as representation
 Average speed of a car that makes 140 mi in 2 h is 111 km/h.
 Average speed of a car that makes 140 mi in 2 h is 112.654 km/h.
 Average speed of a car that makes 140 mi in 2 h is 112.654 km/h.
@@ -108,7 +108,7 @@ Please note how the first and third results get truncated using integral represe
 
 In the end, we repeat the scenario for CGS units:
 
-```cpp title="avg_speed.cpp" linenums="98"
+```cpp title="avg_speed.cpp" linenums="97"
 --8<-- "example/avg_speed.cpp:131:161"
 ```
 
@@ -129,6 +129,6 @@ Average speed of a car that makes 2.2e+07 cm in 7200 s is 110 km/h.
 
 The example file ends with a simple `main()` function:
 
-```cpp title="avg_speed.cpp" linenums="129"
+```cpp title="avg_speed.cpp" linenums="128"
 --8<-- "example/avg_speed.cpp:163:"
 ```

docs/users_guide/examples/hello_units.md

@@ -10,24 +10,24 @@ tags:
 
 This is a really simple example showcasing the features of the **mp-units** library.
 
-First, we include the headers for:
+First, we either import the `mp_units` module or include the headers for:
 
-- a system of quantities (ISQ)
+- an International System of Quantities (ISQ)
-- symbols of SI units
+- an International System of units (SI)
-- symbols of international units
+- units derived from the International Yard and Pound
-- text and stream output support
+- text formatting and stream output support
 
 ```cpp title="hello_units.cpp" linenums="1"
 --8<-- "example/hello_units.cpp:28:39"
 ```
 
-Also, to shorten the definitions, we "import" `mp_units` namespace.
+Also, to shorten the definitions, we "import" all the symbols from the `mp_units` namespace.
 
 ```cpp title="hello_units.cpp" linenums="12"
 --8<-- "example/hello_units.cpp:40:41"
 ```
 
-Next we define a simple function that calculates average speed based on the provided
+Next, we define a simple function that calculates the average speed based on the provided
 arguments of length and time:
 
 ```cpp title="hello_units.cpp" linenums="13"
@@ -35,21 +35,21 @@ arguments of length and time:
 ```
 
 The above function template takes any quantities implicitly convertible to `isq::length`
-and `isq::time` respectively. Those quantities can use any compatible unit and a
+and `isq::time`, respectively. Those quantities can use any compatible unit and a
-representation type. The function returns a result of a really simple equation and ensures
+representation type. The function returns a result of a straightforward equation and ensures
 that its quantity type is implicitly convertible to `isq::speed`.
 
 !!! tip
 
     Besides verifying the type returned from the function, constraining a generic return
-    type is really useful for users of such a function as it provides more information
+    type is beneficial for users of such a function as it provides more information
     of what to expect from a function than just using `auto`.
 
 ```cpp title="hello_units.cpp" linenums="17"
 --8<-- "example/hello_units.cpp:47:50"
 ```
 
-The above lines explicitly opt-in to use unit symbols from two systems of units.
+The above lines explicitly opt into using unit symbols from two systems of units.
 As this introduces a lot of short identifiers into the current scope, it is not done
 implicitly while including a header file.
 
@@ -57,21 +57,21 @@ implicitly while including a header file.
 --8<-- "example/hello_units.cpp:52:58"
 ```
 
-- Lines `16` & `17` create a quantity of kind `isq::length / isq::time` with the numbers
+- Lines `21` & `22` create a quantity of kind `isq::length / isq::time` with the numbers
   and units provided. Such quantities can be converted or assigned to any other quantity
   with a matching kind.
-- Line `18` calls our function template with quantities of kind `isq::length` and
+- Line `23` calls our function template with quantities of kind `isq::length` and
   `isq::time` and number and units provided.
-- Line `19` explicitly provides quantity types of the quantities passed to a function template.
+- Line `24` explicitly provides quantity types of the quantities passed to a function template.
-  This time those will not be quantity kinds anymore and will have
+  This time, those will not be quantity kinds anymore and will have
   [more restrictive conversion rules](../framework_basics/simple_and_typed_quantities.md#quantity_cast-to-force-unsafe-conversions).
-- Line `20` changes the unit of a quantity `v3` to `m / s` in a
+- Line `25` changes the unit of a quantity `v3` to `m / s` in a
   [value-preserving way](../framework_basics/value_conversions.md#value-preserving-conversions)
   (floating-point representations are considered to be value-preserving).
-- Line `21` does a similar operation but this time it would succeed also for
+- Line `26` does a similar operation, but this time, it would also succeed for
   [value-truncating cases](../framework_basics/value_conversions.md#value-truncating-conversions)
-  (if it was the case).
+  (if that was the case).
-- Line `22` does a [value-truncating conversion](../framework_basics/value_conversions.md#value-truncating-conversions)
+- Line `27` does a [value-truncating conversion](../framework_basics/value_conversions.md#value-truncating-conversions)
   of changing the underlying representation type from `double` to `int`.
 
 ```cpp title="hello_units.cpp" linenums="28"
@@ -79,10 +79,10 @@ implicitly while including a header file.
 ```
 
 The above presents [various ways to print a quantity](../framework_basics/text_output.md).
-Both stream insertion operations and `std::format` are supported.
+Both stream insertion operations and `std::format` facilities are supported.
 
 !!! tip
 
-    `MP_UNITS_STD_FMT` is used for compatibility reasons. In case a specific compiler
+    `MP_UNITS_STD_FMT` is used for compatibility reasons. If a specific compiler
-    does not support `std::format` or a user prefers to use `{fmt}` library, this macro
+    does not support `std::format` or a user prefers to use the `{fmt}` library, this macro
-    will resolve to `fmt` namespace. Otherwise, `std` namespace will be used.
+    will resolve to `fmt` namespace. Otherwise, the `std` namespace will be used.

example/avg_speed.cpp

@@ -94,14 +94,14 @@ void example()
     print_result(distance, duration, avg_speed(distance, duration));
   }
 
-  // Customary Units (int)
+  // International mile (int)
   {
     using namespace mp_units::international::unit_symbols;
 
     constexpr auto distance = 140 * mi;
     constexpr auto duration = 2 * h;
 
-    std::cout << "\nUS Customary Units with 'int' as representation\n";
+    std::cout << "\nInternational mile with 'int' as representation\n";
 
     // it is not possible to make a lossless conversion of miles to meters on an integral type
     // (explicit cast needed)
@@ -110,14 +110,14 @@ void example()
     print_result(distance, duration, avg_speed(distance, duration));
   }
 
-  // Customary Units (double)
+  // International mile (double)
   {
     using namespace mp_units::international::unit_symbols;
 
     constexpr auto distance = 140. * mi;
     constexpr auto duration = 2. * h;
 
-    std::cout << "\nUS Customary Units with 'double' as representation\n";
+    std::cout << "\nInternational mile with 'double' as representation\n";
 
     // conversion from a floating-point to an integral type is a truncating one so an explicit cast is needed
     // also it is not possible to make a lossless conversion of miles to meters on an integral type