WIP: doc: Add API structure from developer perspectivesemver

4 files changed, 251 insertions, 5 deletions

diff --git a/doc/diagrams/device-semver-developer.svg b/doc/diagrams/device-semver-developer.svg
new file mode 100644
index 0000000..fd5b38a
--- /dev/null
+++ b/doc/diagrams/device-semver-developer.svg
@@ -0,0 +1,239 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="150mm"
+   height="55mm"
+   viewBox="0 0 150 55"
+   version="1.1"
+   id="svg1"
+   inkscape:version="1.3.2 (091e20ef0f, 2023-11-25, custom)"
+   sodipodi:docname="device-semver-developer.svg"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg">
+  <sodipodi:namedview
+     id="namedview1"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:showpageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="0"
+     inkscape:deskcolor="#d1d1d1"
+     inkscape:document-units="mm"
+     showgrid="true"
+     inkscape:zoom="2.0588333"
+     inkscape:cx="285.8415"
+     inkscape:cy="67.999678"
+     inkscape:window-width="1916"
+     inkscape:window-height="1028"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="0"
+     inkscape:current-layer="layer1">
+    <inkscape:grid
+       id="grid1"
+       units="mm"
+       originx="0"
+       originy="0"
+       spacingx="0.99999999"
+       spacingy="0.99999999"
+       empcolor="#0099e5"
+       empopacity="0.30196078"
+       color="#0099e5"
+       opacity="0.14901961"
+       empspacing="5"
+       dotted="false"
+       gridanglex="30"
+       gridanglez="30"
+       visible="true" />
+  </sodipodi:namedview>
+  <defs
+     id="defs1" />
+  <g
+     inkscape:label="Ebene 1"
+     inkscape:groupmode="layer"
+     id="layer1">
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="35.146614"
+       y="34.455166"
+       id="text1"><tspan
+         sodipodi:role="line"
+         id="tspan1"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="35.146614"
+         y="34.455166">Mechanical</tspan><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="35.146614"
+         y="37.277397"
+         id="tspan2">parts</tspan></text>
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.265;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
+       id="rect1"
+       width="20"
+       height="10"
+       x="25"
+       y="29.999998" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="60.014114"
+       y="34.322666"
+       id="text1-3"><tspan
+         sodipodi:role="line"
+         id="tspan1-5"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="60.014114"
+         y="34.322666">Electronic</tspan><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="60.014114"
+         y="37.144897"
+         id="tspan2-6">parts</tspan></text>
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.265;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
+       id="rect1-2"
+       width="20"
+       height="10"
+       x="50"
+       y="30" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="34.950615"
+       y="21.058338"
+       id="text1-3-0"><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="34.950615"
+         y="21.058338"
+         id="tspan2-6-3">Firmware</tspan></text>
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.265;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
+       id="rect1-2-6"
+       width="20"
+       height="10"
+       x="25"
+       y="15" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="59.950615"
+       y="21.058338"
+       id="text1-3-0-1"><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="59.950615"
+         y="21.058338"
+         id="tspan2-6-3-8">Software</tspan></text>
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-opacity:1"
+       id="rect1-2-6-7"
+       width="20"
+       height="10"
+       x="50"
+       y="15" />
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none"
+       id="rect3"
+       width="55"
+       height="35"
+       x="20"
+       y="10" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="20.802444"
+       y="43.971779"
+       id="text3"><tspan
+         sodipodi:role="line"
+         id="tspan3"
+         style="stroke-width:0.264583"
+         x="20.802444"
+         y="43.971779">Device</tspan></text>
+    <rect
+       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:0.5, 1;stroke-dashoffset:0"
+       id="rect5"
+       width="22"
+       height="12"
+       x="24"
+       y="13.999999" />
+    <rect
+       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:0.5, 1;stroke-dashoffset:0"
+       id="rect5-5"
+       width="22"
+       height="12"
+       x="49"
+       y="13.999999" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="M 119.875,29.875 V 21.884426"
+       id="path9"
+       sodipodi:nodetypes="cc" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 119.875,29.874999 3,5"
+       id="path10" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 119.875,29.874999 -3,5"
+       id="path11" />
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264583px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1"
+       d="m 116.875,24.875001 h 6"
+       id="path12" />
+    <ellipse
+       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:none;stroke-dashoffset:0"
+       id="path13"
+       cx="119.875"
+       cy="19.384426"
+       rx="2.531951"
+       ry="2.5" />
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="112.69416"
+       y="38.57132"
+       id="text13"><tspan
+         sodipodi:role="line"
+         id="tspan13"
+         style="stroke-width:0.264583"
+         x="112.69416"
+         y="38.57132">Developer</tspan></text>
+    <text
+       xml:space="preserve"
+       style="font-size:2.82223px;line-height:1;font-family:Monospace;-inkscape-font-specification:Monospace;stroke-width:0.264583"
+       x="100.84268"
+       y="46.773823"
+       id="text14"><tspan
+         sodipodi:role="line"
+         id="tspan14"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="100.84268"
+         y="46.773823">multipe 'API's as defined</tspan><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="100.84268"
+         y="49.596054"
+         id="tspan15">by Semantic Versioning</tspan></text>
+    <rect
+       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:0.5, 1;stroke-dashoffset:0"
+       id="rect5-2"
+       width="22"
+       height="12"
+       x="24"
+       y="28.999998" />
+    <rect
+       style="fill:none;fill-opacity:1;stroke:#000000;stroke-width:0.25;stroke-linecap:square;stroke-linejoin:bevel;stroke-miterlimit:0;stroke-dasharray:0.5, 1;stroke-dashoffset:0"
+       id="rect5-7"
+       width="22"
+       height="12"
+       x="49"
+       y="28.999998" />
+  </g>
+</svg>
diff --git a/doc/diagrams/device-semver.svg b/doc/diagrams/device-semver-user.svg
index 8a68362..8a68362 100644
--- a/doc/diagrams/device-semver.svg
+++ b/doc/diagrams/device-semver-user.svg
diff --git a/doc/doc.mk b/doc/doc.mk
index 351cd48..d1e4a1b 100644
--- a/doc/doc.mk
+++ b/doc/doc.mk
@@ -3,7 +3,7 @@ DOCS := documentation
 DOCUMENTS := $(DOCS:%=$(DOC_BUILD_DIR)/%.pdf)
 
 DIAGRAMS_BUILD_DIR := $(DOC_BUILD_DIR)/diagrams
-DIAGRAMS := device-semver
+DIAGRAMS := device-semver-user device-semver-developer
 IMAGES := $(DIAGRAMS:%=$(DIAGRAMS_BUILD_DIR)/%.pdf)
 
 .PHONY: doc
diff --git a/doc/documentation.tex b/doc/documentation.tex
index 91ff8e5..5713b3c 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -30,13 +30,20 @@ Versioning\footnote{\href{https://semver.org}{https://semver.org}}. The
 resulting version numbers have the format \texttt{<major>.<minor>.<patch>} like
 e.g. \texttt{2.0.3}. While Semantic Versioning is usually targeted at software
 only it is here used for the whole device. This includes mechanical, electronic
-and software aspects as shown in figure \ref{diagram:device-semver}.
+and software aspects as shown in figure \ref{diagram:device-semver-user}.
 
 \begin{figure}[h]
 	\centering
-	\includegraphics[width=\textwidth]{device-semver.pdf}
-	\caption{API for a device versioned with Semantic Versioning}
-	\label{diagram:device-semver}
+	\includegraphics[width=\textwidth]{device-semver-user.pdf}
+	\caption{API for a device versioned with Semantic Versioning from a user perspective}
+	\label{diagram:device-semver-user}
+\end{figure}
+
+\begin{figure}[h]
+	\centering
+	\includegraphics[width=\textwidth]{device-semver-developer.pdf}
+	\caption{API for a device versioned with Semantic Versioning from a developer perspective}
+	\label{diagram:device-semver-developer}
 \end{figure}
 
 This versioning makes sure that users do not have to care about the device