docs: add reference documentations

.cmake-format.yaml

@@ -1,3 +1,4 @@
+include: ["cmake/.cmake-format-additional_commands-jegp.cmake_modules.yaml"]
 parse:
   additional_commands:
     add_mp_units_module:

.gitignore

@@ -46,3 +46,7 @@ CMakeUserPresets.json
 # Conan
 *.pyc
 /test_package/build/
+
+# cxxdraft-htmlgen
+docs/api_reference/src/source/
+docs/api_reference/gen/

cmake/.cmake-format-additional_commands-jegp.cmake_modules.yaml

@@ -0,0 +1,82 @@
+parse:
+  additional_commands:
+    _jegp_common_yaml_anchors:
+      kwargs:
+        PUBLIC_INTERFACE_PRIVATE: &public_interface_private
+          kwargs:
+            PUBLIC: +
+            INTERFACE: +
+            PRIVATE: +
+    jegp_add_standardese_sources:
+      pargs:
+        nargs: 1
+        flags:
+        - EXCLUDE_FROM_ALL
+      kwargs:
+        LIBRARIES: +
+        APPENDICES: +
+        EXTENSIONS: +
+        CHECKED: 1
+        PDF: &standardese_pdf
+          pargs:
+            flags:
+            - EXCLUDE_FROM_MAIN
+          kwargs:
+            PATH: 1
+        HTML:
+          <<: *standardese_pdf
+          kwargs:
+            SECTION_FILE_STYLE: 1
+            LATEX_REGEX_REPLACE: +
+            HTML_REGEX_REPLACE: +
+    jegp_add_module:
+      pargs: &jegp_add_module_pargs
+        nargs: 1
+        flags:
+        - IMPORTABLE_HEADER
+      kwargs:
+        SOURCES: +
+        COMPILE_OPTIONS: *public_interface_private
+        LINK_LIBRARIES: *public_interface_private
+    jegp_cpp_module:
+      pargs: *jegp_add_module_pargs
+    jegp_target_link_header_units:
+      pargs:
+        nargs: 1+
+    jegp_cpp2_target_sources:
+      pargs:
+        nargs: 1
+      kwargs:
+        JEGP_FILE_SET_KWARGS: &file_set
+          kwargs:
+            FILE_SET: 1
+            TYPE: 1
+            BASE_DIRS: +
+            FILES: +
+        PUBLIC: *file_set
+        INTERFACE: *file_set
+        PRIVATE: *file_set
+    jegp_add_headers_test:
+      pargs:
+        nargs: 1+
+      kwargs:
+        PRIVATE_REGEXES: +
+    jegp_add_test:
+      pargs:
+        nargs: 1+
+        flags:
+        - COMPILE_ONLY
+      kwargs:
+        TYPE: 1
+        SOURCES: +
+        COMPILE_OPTIONS: +
+        LINK_LIBRARIES: +
+    jegp_add_build_error:
+      pargs:
+        nargs: 1+
+      kwargs:
+        AS: 1
+        TYPE: 1
+        SOURCE: 1
+        COMPILE_OPTIONS: +
+        LINK_LIBRARIES: +

docs/api_reference/src/CMakeLists.txt

@@ -0,0 +1,41 @@
+cmake_minimum_required(VERSION 3.24.0)
+project(mp-units_reference_documentations LANGUAGES NONE)
+
+include(JEGPAddStandardeseSources)
+
+set(pdf_title "mp-units Library")
+set(page_license "MIT License")
+set(first_library_chapter "qties")
+set(last_library_chapter "qties")
+set(cover_title "mp-units Library Reference Documentations")
+set(reply_to "\\href{${PROJECT_HOMEPAGE_URL}/discussions}{Discussions}, \\href{${PROJECT_HOMEPAGE_URL}/issues}{issues}")
+jegp_add_standardese_sources(
+    mp-units_reference_documentations
+    LIBRARIES intro quantities
+    EXTENSIONS macros_extensions
+    CHECKED TRUE
+#    PDF PATH "mp-units.pdf" #[[EXCLUDE_FROM_MAIN]]
+    HTML PATH "mp-units.html" #[[EXCLUDE_FROM_MAIN]]
+         SECTION_FILE_STYLE "WithExtension"
+         LATEX_REGEX_REPLACE
+             # Latex commands.
+             [[\\href{([^}]+)}{([^}]+)};HREF(\1)(\2)]]
+             # Macros extensions.
+             [[\\refcpp{([^}]+)};REFCPP(\1)]]
+             [[\\irefcpp{([^}]+)};~(REFCPP(\1))]]
+             [[\\refcppx{([^}]+)}{([^}]+)};REFCPPX(\1)(\2)]]
+             [[\\irefcppx{([^}]+)}{([^}]+)};~(REFCPPX(\1)(\2))]]
+             [[\\refiev{([^}]+)};REFIEV(\1)]]
+             [[\\irefiev{([^}]+)};~(REFIEV(\1))]]
+             # Main matter and annexes.
+             [[\\\"{o};ö]]
+         HTML_REGEX_REPLACE
+             # Latex commands.
+             [[HREF\(([^)]+)\)\(([^)]+)\);<a href="\1">\2</a>]]
+             # Macros extensions.
+             [[REFCPP\(([^)]+)\);<a href="https://wg21.link/\1">ISOCPP, [\1]</a>]]
+             [[REFCPPX\(([^)]+)\)\(([^)]+)\);<a href="https://wg21.link/\1\2">ISOCPP, [\1]</a>]] #
+             [[ISOCPP;N4971]]
+             [[REFIEV\(([^)]+)\);<a href="https://www.electropedia.org/iev/iev.nsf/display?openform&ievref=\1">IEC 60050, \1</a>]]
+             # Main matter and annexes.
+)

docs/api_reference/src/intro.tex

@@ -0,0 +1,134 @@
+%!TEX root = std.tex
+
+
+\rSec0[scope]{Scope}
+
+\pnum
+\indextext{scope|(}%
+This document describes the contents of the \defn{mp-units library}.
+\indextext{scope|)}
+
+
+\rSec0[refs]{References}
+
+\pnum
+\indextext{references|(}%
+The following documents are referred to in the text
+in such a way that some or all of their content
+constitutes requirements of this document.
+For dated references, only the edition cited applies.
+For undated references,
+the latest edition of the referenced document
+(including any amendments) applies.
+\begin{itemize}
+\item
+IEC 60050-102:2007/AMD3:2021,
+\doccite{Amendment 3 --- International Electrotechnical Vocabulary (IEV) ---
+Part 102: Mathematics --- General concepts and linear algebra}
+\item
+IEC 60050-112:2010/AMD2:2020,
+\doccite{Amendment 2 --- International Electrotechnical Vocabulary (IEV) ---
+Part 112: Quantities and units}
+\item
+ISO 80000 (all parts), \doccite{Quantities and units}
+\item
+The \Cpp{} Standards Committee.
+\IsoCpp{}: \doccite{Working Draft, Standard for Programming Language \Cpp{}}.
+Edited by Thomas K\"{o}ppe.
+Available from: \url{https://wg21.link/\IsoCpp{}}
+\item
+The \Cpp{} Standards Committee.
+SD-8: \doccite{Standard Library Compatibility}.
+Edited by Bryce Lelbach.
+Available from: \url{https://wg21.link/SD8}
+\end{itemize}
+\indextext{references|)}
+
+
+\rSec0[defs]{Terms and definitions}
+
+\pnum
+\indextext{definitions|(}%
+For the purposes of this document,
+the terms and definitions given in
+IEC 60050-102:2007/AMD3:2021,
+IEC 60050-112:2010/AMD2:2020,
+ISO 80000-2:2019,
+and
+\IsoCpp{},
+and the following apply.
+
+\pnum
+ISO and IEC maintain terminology databases
+for use in standardization
+at the following addresses:
+\begin{itemize}
+\item ISO Online browsing platform: available at \url{https://www.iso.org/obp}
+\item IEC Electropedia: available at \url{http://www.electropedia.org}
+\end{itemize}
+\indextext{definitions|)}
+
+
+\rSec0[spec]{Specification}
+
+\rSec1[spec.ext]{External}
+
+\pnum
+The specification of the mp-units library subsumes
+\refcpp{description}, \refcpp{requirements}, \refcpp{concepts.equality}, and SD-8,
+all assumingly amended for the context of this library.
+\begin{note}
+This means that, non exhaustively,
+\begin{itemize}
+\item \tcode{::mp_units2} is a reserved namespace, and
+\item
+\tcode{std::vector<mp_units::\placeholdernc{type}>}
+is a program-defined specialization and a library-defined specialization
+from the point of view of the \Cpp{} standard library and the mp-units library, respectively.
+\end{itemize}
+\end{note}
+
+\pnum
+The mp-units library is not part of the \Cpp{} implementation.
+
+\rSec1[spec.cats]{Categories}
+
+\pnum
+Detailed specifications for each of the components in the library are in
+\ref{\firstlibchapter}--\ref{\lastlibchapter},
+as shown in \tref{lib.cats}.
+
+\begin{floattable}{Library categories}{lib.cats}
+{ll}
+\topline
+\hdstyle{Clause}        & \hdstyle{Category}                              \\ \capsep
+\ref{qties}             & Quantities library                              \\
+\end{floattable}
+
+\pnum
+The quantities library\iref{qties}
+describes components for dealing with quantities.
+
+\rSec1[spec.mods]{Modules}
+
+\pnum
+The mp-units library provides the
+\defnx{mp-units modules}{module!mp-units},
+shown in \tref{modules}.
+
+\begin{multicolfloattable}{mp-units modules}{modules}
+{lll}
+\tcode{mp_units}                      \\
+\columnbreak
+\tcode{mp_units.core}                 \\
+\columnbreak
+\tcode{mp_units.systems}              \\
+\end{multicolfloattable}
+
+\rSec1[spec.reqs]{Library-wide requirements}
+
+\rSec2[spec.res.names]{Reserved names}
+
+\pnum
+The mp-units library reserves macro names that start with
+\tcode{MP_UNITS\opt{\gterm{digit-sequence}}_}.

docs/api_reference/src/macros_extensions.tex

@@ -0,0 +1,11 @@
+\newcommand{\IsoCpp}{N4971}
+
+%% Inline non-parenthesized C++ reference
+\newcommand{\refcpp}[1]{\href{https://wg21.link/#1}{\IsoCpp{}, [#1]}}
+\newcommand{\irefcpp}[1]{\nolinebreak[3] (\refcpp{#1})}
+\newcommand{\refcppx}[2]{\href{https://wg21.link/#1\##2}{\IsoCpp{}, [#1]}}
+\newcommand{\irefcppx}[2]{\nolinebreak[3] (\refcppx{#1}{#2})}
+
+%% Inline IEV reference
+\newcommand{\refiev}[1]{\href{https://www.electropedia.org/iev/iev.nsf/display?openform&ievref=#1}{IEC 60050, #1}}
+\newcommand{\irefiev}[1]{\nolinebreak[3] (\refiev{#1})}