mpusz/mp-units
1
0
Fork 1
mirror of https://github.com/mpusz/mp-units.git synced 2025-08-01 03:14:29 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: admonition types usage fine tuned

Browse Source
This commit is contained in:
Mateusz Pusz
2023-08-30 11:33:30 +02:00
parent f1c2c74ab0
commit fa38e4f497
15 changed files with 25 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/getting_started/faq.md
View File

@@ -156,7 +156,7 @@ magnitudes. In that case, you may end up with a really small or a huge floating-
in losing lots of precision. Returning a dimensionless quantity from such cases allows us to benefit from in losing lots of precision. Returning a dimensionless quantity from such cases allows us to benefit from
all the properties of scaled units and is consistent with the rest of the library. all the properties of scaled units and is consistent with the rest of the library.
!!! info !!! note
More information on the current design can be found in More information on the current design can be found in
[the Dimensionless Quantities chapter](../users_guide/framework_basics/dimensionless_quantities.md). [the Dimensionless Quantities chapter](../users_guide/framework_basics/dimensionless_quantities.md).
@@ -171,7 +171,7 @@ standards specify Unicode symbols as the official unit names for some quantities
As **mp-units** library will be proposed for standardization as a part of the C++ Standard Library As **mp-units** library will be proposed for standardization as a part of the C++ Standard Library
we have to obey the rules and be consistent with ISO specifications. we have to obey the rules and be consistent with ISO specifications.
!!! info !!! note
We do understand engineering reality and the constraints of some environments. This is why the library We do understand engineering reality and the constraints of some environments. This is why the library
has the option of ASCII-only Quantity Symbols. has the option of ASCII-only Quantity Symbols.
@@ -210,7 +210,7 @@ This is why our projects have two entry points:
- _./src/CMakeLists.txt_ contains only a pure library definition and should be used by the customers - _./src/CMakeLists.txt_ contains only a pure library definition and should be used by the customers
that prefer to use CMake's `add_subdirectory()` to handle the dependencies. that prefer to use CMake's `add_subdirectory()` to handle the dependencies.
!!! info !!! note
For more details on this please refer to the [CMake + Conan: 3 Years Later - Mateusz Pusz](https://youtu.be/mrSwJBJ-0z8?t=1931) For more details on this please refer to the [CMake + Conan: 3 Years Later - Mateusz Pusz](https://youtu.be/mrSwJBJ-0z8?t=1931)
lecture that Mateusz Pusz provided at the C++Now 2021 conference. lecture that Mateusz Pusz provided at the C++Now 2021 conference.

6
docs/getting_started/installation_and_usage.md
View File

@@ -124,7 +124,7 @@ generators. For example:
tools.cmake.cmaketoolchain:generator="Ninja Multi-Config" tools.cmake.cmaketoolchain:generator="Ninja Multi-Config"
``` ```
!!! note !!! info
_~/.conan2/global.conf_ file may also set `tools.cmake.cmake_layout:build_folder_vars` which _~/.conan2/global.conf_ file may also set `tools.cmake.cmake_layout:build_folder_vars` which
[makes working with several compilers or build configurations easier](https://docs.conan.io/2/reference/tools/cmake/cmake_layout.html#multi-setting-option-cmake-layout). [makes working with several compilers or build configurations easier](https://docs.conan.io/2/reference/tools/cmake/cmake_layout.html#multi-setting-option-cmake-layout).
@@ -222,7 +222,7 @@ cmake .. -G "Ninja Multi-Config" -DCMAKE_TOOLCHAIN_FILE=<path_to_generators_dir>
cmake --build . --config Release cmake --build . --config Release
``` ```
!!! note !!! tip
In case you can't use CMake 3.23 but you have access to CMake 3.20 or later, you can append In case you can't use CMake 3.23 but you have access to CMake 3.20 or later, you can append
`-c tools.cmake.cmaketoolchain.presets:max_schema_version=2` to the `conan install` command `-c tools.cmake.cmaketoolchain.presets:max_schema_version=2` to the `conan install` command
@@ -234,7 +234,7 @@ cmake --build . --config Release
There are many different ways of installing/reusing **mp-units** in your project. Below we mention There are many different ways of installing/reusing **mp-units** in your project. Below we mention
only a few of many options possible. only a few of many options possible.
!!! info !!! important
The easiest and most recommended way to obtain **mp-units** is with the Conan package manager. The easiest and most recommended way to obtain **mp-units** is with the Conan package manager.
See [Conan + CMake (release)](#conan-cmake-release) for a detailed instruction. See [Conan + CMake (release)](#conan-cmake-release) for a detailed instruction.

4
docs/getting_started/introduction.md
View File

@@ -6,7 +6,7 @@ manipulation. The initial versions of the library were inspired by the
but with each release, the interfaces diverged from the original to provide a better user but with each release, the interfaces diverged from the original to provide a better user
experience. experience.
!!! note !!! info
A brief introduction to the library's interfaces and the rationale for changes in the version 2.0 A brief introduction to the library's interfaces and the rationale for changes in the version 2.0
of **mp-units** were provided in detail by [Mateusz Pusz](https://github.com/mpusz) in the of **mp-units** were provided in detail by [Mateusz Pusz](https://github.com/mpusz) in the
@@ -36,7 +36,7 @@ To achieve this goal, several techniques are applied:
- [usage of expression templates to improve the readability of generated types](../users_guide/framework_basics/interface_introduction.md#expression-templates), - [usage of expression templates to improve the readability of generated types](../users_guide/framework_basics/interface_introduction.md#expression-templates),
- limiting the number of template arguments to the bare minimum. - limiting the number of template arguments to the bare minimum.
!!! note !!! important
In many generic C++ libraries compile-time errors do not happen often. It is hard to In many generic C++ libraries compile-time errors do not happen often. It is hard to
break `std::string` or `std::vector` in a way it won't compile with a huge error break `std::string` or `std::vector` in a way it won't compile with a huge error

2
docs/getting_started/quick_start.md
View File

@@ -33,7 +33,7 @@ using namespace mp_units::si::unit_symbols;
quantity q = 42 * m; quantity q = 42 * m;
``` ```
!!! note !!! tip
Unit symbols introduce a lot of short identifiers into the current namespace, and that is Unit symbols introduce a lot of short identifiers into the current namespace, and that is
why they are opt-in. A user has to explicitly "import" them from a dedicated `unit_symbols` why they are opt-in. A user has to explicitly "import" them from a dedicated `unit_symbols`

2
docs/index.md
View File

@@ -7,7 +7,7 @@ performance, and developer experience.
The library source code is hosted on [GitHub](https://github.com/mpusz/mp-units) with a permissive The library source code is hosted on [GitHub](https://github.com/mpusz/mp-units) with a permissive
[MIT license](https://github.com/mpusz/units/blob/master/LICENSE.md). [MIT license](https://github.com/mpusz/units/blob/master/LICENSE.md).
!!! info "Help needed!" !!! important "Help needed!"
The **mp-units** library might be the subject of ISO standardization for C++29. More on this can The **mp-units** library might be the subject of ISO standardization for C++29. More on this can
be found in the ISO C++ proposal [P1935](https://wg21.link/p1935). We are actively looking for be found in the ISO C++ proposal [P1935](https://wg21.link/p1935). We are actively looking for

2
docs/users_guide/examples/tags_index.md
View File

@@ -1,6 +1,6 @@
# Tags Index # Tags Index
!!! note !!! tip
All usage examples in this chapter are categorized with appropriate tags to simplify navigation and All usage examples in this chapter are categorized with appropriate tags to simplify navigation and
search of relevant code. You can either read all the examples one-by-one in the order provided by search of relevant code. You can either read all the examples one-by-one in the order provided by

4
docs/users_guide/framework_basics/basic_concepts.md
View File

@@ -137,7 +137,7 @@ including:
`QuantitySpecOf` concept is satisfied when both arguments satisfy a [`QuantitySpec`](#QuantitySpec) concept `QuantitySpecOf` concept is satisfied when both arguments satisfy a [`QuantitySpec`](#QuantitySpec) concept
and when `T` is implicitly convertible to `V`. and when `T` is implicitly convertible to `V`.
??? note "More details" ??? info "More details"
Additionally: Additionally:
@@ -253,7 +253,7 @@ units can be passed as an argument to a `prefixed_unit` class template.
`UnitOf` concept is satisfied for all units `T` matching an [`AssociatedUnit`](#AssociatedUnit) `UnitOf` concept is satisfied for all units `T` matching an [`AssociatedUnit`](#AssociatedUnit)
concept with an associated quantity type implicitly convertible to `V`. concept with an associated quantity type implicitly convertible to `V`.
??? note "More details" ??? info "More details"
Additionally, the kind of `V` and the kind of quantity type associated with `T` must be the same, Additionally, the kind of `V` and the kind of quantity type associated with `T` must be the same,
or the quantity type associated with `T` may not be derived from the kind of `V`. or the quantity type associated with `T` may not be derived from the kind of `V`.

2
docs/users_guide/framework_basics/dimensionless_quantities.md
View File

@@ -138,7 +138,7 @@ quantities deriving from them.
As we observed above, the most common unit for dimensionless quantities is `one`. It has the As we observed above, the most common unit for dimensionless quantities is `one`. It has the
ratio of `1` and does not output any textual symbol. ratio of `1` and does not output any textual symbol.
!!! note !!! important
A unit `one` is special in the entire type system of units as it is considered to be A unit `one` is special in the entire type system of units as it is considered to be
[an identity operand in the unit expression templates](interface_introduction.md#identities). [an identity operand in the unit expression templates](interface_introduction.md#identities).

4
docs/users_guide/framework_basics/interface_introduction.md
View File

@@ -16,7 +16,7 @@ behind this is that:
- Users always work with objects and never have to spell such a type name. - Users always work with objects and never have to spell such a type name.
- The types appear in the compilation errors and during debugging. - The types appear in the compilation errors and during debugging.
!!! info !!! important
To improve compiler errors' readability and make it easier to correlate them with To improve compiler errors' readability and make it easier to correlate them with
a user's written code, a new idiom in the library is to use the same identifier for a user's written code, a new idiom in the library is to use the same identifier for
@@ -133,7 +133,7 @@ type = class mp_units::quantity<mp_units::derived_unit<metre, mp_units::per<seco
The same type identifier will be visible in the compilation error (in case it happens). The same type identifier will be visible in the compilation error (in case it happens).
!!! info !!! important
Expressions templates are extensively used throughout the library to improve the readability Expressions templates are extensively used throughout the library to improve the readability
of the resulting types. of the resulting types.

2
docs/users_guide/framework_basics/simple_and_typed_quantities.md
View File

@@ -27,7 +27,7 @@ The concept `Reference` is satisfied by either:
- a unit with an associated quantity type (i.e. `si::metre`) - a unit with an associated quantity type (i.e. `si::metre`)
- a reference type explicitly specifying the quantity type and its unit. - a reference type explicitly specifying the quantity type and its unit.
!!! note !!! important
All units in the SI system have an associated quantity type. All units in the SI system have an associated quantity type.

6
docs/users_guide/framework_basics/systems_of_quantities.md
View File

@@ -52,7 +52,7 @@ All of those quantities have the same dimension, namely $\mathsf{T}^{-1}$, but p
is not wise to allow adding, subtracting, or comparing them, as they describe vastly different is not wise to allow adding, subtracting, or comparing them, as they describe vastly different
physical properties. physical properties.
!!! info !!! important
More than one quantity may be defined for the same dimension: More than one quantity may be defined for the same dimension:
@@ -354,7 +354,7 @@ To annotate a quantity to represent its kind (and not just a hierarchy tree's ro
we introduced a `kind_of<>` specifier. For example, to express any quantity of length, we need we introduced a `kind_of<>` specifier. For example, to express any quantity of length, we need
to type `kind_of<isq::length>`. to type `kind_of<isq::length>`.
!!! note !!! important
`isq::length` and `kind_of<isq::length>` are two different things. `isq::length` and `kind_of<isq::length>` are two different things.
@@ -380,7 +380,7 @@ static_assert(!same_type<kind_of<isq::length> / isq::time, kind_of<isq::length /
static_assert(same_type<kind_of<isq::length> / isq::time, isq::length / isq::time>); static_assert(same_type<kind_of<isq::length> / isq::time, isq::length / isq::time>);
``` ```
!!! note !!! info
Only a root quantity from the hierarchy tree or the one marked with `is_kind` specifier Only a root quantity from the hierarchy tree or the one marked with `is_kind` specifier
in the `quantity_spec` definition can be put as a template parameter to the `kind_of` in the `quantity_spec` definition can be put as a template parameter to the `kind_of`

2
docs/users_guide/framework_basics/systems_of_units.md
View File

@@ -29,7 +29,7 @@ previous chapter) with a unit that is used to express it:
inline constexpr struct metre : named_unit<"m", kind_of<isq::length>> {} metre; inline constexpr struct metre : named_unit<"m", kind_of<isq::length>> {} metre;
``` ```
!!! note !!! important
The `kind_of<isq::length>` above states explicitly that this unit has The `kind_of<isq::length>` above states explicitly that this unit has
an associated quantity kind. In other words, `si::metre` (and scaled units based an associated quantity kind. In other words, `si::metre` (and scaled units based

2
docs/users_guide/framework_basics/text_output.md
View File

@@ -37,7 +37,7 @@ The text output will always print the [value of a quantity](../../appendix/gloss
typically followed by a space and then the symbol of a [unit](../../appendix/glossary.md#unit) typically followed by a space and then the symbol of a [unit](../../appendix/glossary.md#unit)
associated with this quantity. associated with this quantity.
!!! note !!! important
Remember that when we deal with a quantity of an "unknown" `auto` type, it is a good practice Remember that when we deal with a quantity of an "unknown" `auto` type, it is a good practice
to always [convert the unit to the expected one](value_conversions.md#value-conversions) to always [convert the unit to the expected one](value_conversions.md#value-conversions)

4
docs/users_guide/framework_basics/the_affine_space.md
View File

@@ -29,7 +29,7 @@ Here are the primary operations one can do in the affine space:
- _vector_ + _point_ -> _point_ - _vector_ + _point_ -> _point_
- _point_ - _vector_ -> _point_ - _point_ - _vector_ -> _point_
!!! note !!! important
It is not possible to: It is not possible to:
@@ -337,7 +337,7 @@ The following operations are not allowed in the affine space:
- How to subtract a point on our trip to CppCon measured relatively to our home location from - How to subtract a point on our trip to CppCon measured relatively to our home location from
a point measured relative to the center of the Solar System? a point measured relative to the center of the Solar System?
!!! note !!! important
The usage of `quantity_point` and affine space types in general, improves expressiveness and The usage of `quantity_point` and affine space types in general, improves expressiveness and
type-safety of the code we write. type-safety of the code we write.

2
docs/users_guide/framework_basics/value_conversions.md
View File

@@ -12,7 +12,7 @@ The second line above converts the current quantity to the one expressed in metr
contents. The third line converts the quantity expressed in kilometres into the one measured contents. The third line converts the quantity expressed in kilometres into the one measured
in metres. in metres.
!!! note !!! important
It is always assumed that one can convert a quantity into another one with a unit of a higher It is always assumed that one can convert a quantity into another one with a unit of a higher
resolution. There is no protection against overflow of the representation type. In case the target resolution. There is no protection against overflow of the representation type. In case the target