doc: Write section 'Versioning'

This section is important to communicate how to interpret version
numbers in the context of this device repository.

4 files changed, 265 insertions, 4 deletions

diff --git a/README.md b/README.md
index 54efd20..8b83ec3 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,7 @@ required:
 - GNU coreutils
 - GNU make
 - pdflatex
+- Inkscape
 - OpenSCAD
 - Prusa Slicer
 
diff --git a/doc/diagrams/device-semver.svg b/doc/diagrams/device-semver.svg
new file mode 100644
index 0000000..8a68362
--- /dev/null
+++ b/doc/diagrams/device-semver.svg
@@ -0,0 +1,223 @@
+<?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.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="1.9638901"
+     inkscape:cx="240.08472"
+     inkscape:cy="127.80756"
+     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.1325"
+       y="30.1325" />
+    <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="65"
+       height="45"
+       x="15"
+       y="5" />
+    <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="116.39834"
+       y="38.57132"
+       id="text13"><tspan
+         sodipodi:role="line"
+         id="tspan13"
+         style="stroke-width:0.264583"
+         x="116.39834"
+         y="38.57132">User</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="107.72183"
+       y="48.361324"
+       id="text14"><tspan
+         sodipodi:role="line"
+         id="tspan14"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="107.72183"
+         y="48.361324">'API' as defined by</tspan><tspan
+         sodipodi:role="line"
+         style="text-align:center;text-anchor:middle;stroke-width:0.264583"
+         x="107.72183"
+         y="51.183556"
+         id="tspan15">Semantic Versioning</tspan></text>
+    <path
+       style="fill:none;stroke:#000000;stroke-width:0.264583;stroke-linecap:butt;stroke-linejoin:miter;stroke-dasharray:none;stroke-opacity:1"
+       d="M 91.000001,47.999998 80.874998,39.875"
+       id="path15"
+       sodipodi:nodetypes="cc" />
+  </g>
+</svg>
diff --git a/doc/doc.mk b/doc/doc.mk
index 8c56847..351cd48 100644
--- a/doc/doc.mk
+++ b/doc/doc.mk
@@ -1,11 +1,19 @@
 DOC_BUILD_DIR := $(BUILD_DIR)/doc
 DOCS := documentation
-PDF := $(DOCS:%=$(DOC_BUILD_DIR)/%.pdf)
+DOCUMENTS := $(DOCS:%=$(DOC_BUILD_DIR)/%.pdf)
+
+DIAGRAMS_BUILD_DIR := $(DOC_BUILD_DIR)/diagrams
+DIAGRAMS := device-semver
+IMAGES := $(DIAGRAMS:%=$(DIAGRAMS_BUILD_DIR)/%.pdf)
 
 .PHONY: doc
-doc: $(PDF)
+doc: $(DOCUMENTS)
 
-$(BUILD_DIR)/%.pdf: %.tex
+$(DOC_BUILD_DIR)/%.pdf: doc/%.tex $(IMAGES)
 	mkdir -p $(dir $@)
 	pdflatex -halt-on-error -output-directory $(DOC_BUILD_DIR) $<
 	pdflatex -halt-on-error -output-directory $(DOC_BUILD_DIR) $<
+
+$(DIAGRAMS_BUILD_DIR)/%.pdf: doc/diagrams/%.svg
+	mkdir -p $(dir $@)
+	inkscape -o $@ $<
diff --git a/doc/documentation.tex b/doc/documentation.tex
index 14cf828..f7c0fee 100644
--- a/doc/documentation.tex
+++ b/doc/documentation.tex
@@ -2,6 +2,12 @@
 \author{xengineering}
 \title{soundbox documentation}
 
+\usepackage{graphicx}
+\graphicspath{ {./diagrams/} }
+\usepackage{hyperref}
+
+\setlength\parindent{0pt}
+
 \begin{document}
 
 \maketitle
@@ -10,11 +16,34 @@
 \tableofcontents
 \newpage
 
+\listoffigures
+\newpage
+
 \chapter{Introduction}
 
 \texttt{soundbox} is a device to connect classic audio systems to the network.
 
-%\section{Versioning}
+\section{Versioning}
+
+This device is versioned with Semantic
+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}.
+
+\begin{figure}[h]
+	\centering
+	\includegraphics[width=\textwidth]{device-semver.pdf}
+	\caption{API for a device versioned with Semantic Versioning}
+	\label{diagram:device-semver}
+\end{figure}
+
+This versioning makes sure that users do not have to care about the device
+internals at all. Devices can be seen as atomic from a user's perspective. This
+level of granularity is choosen because users are not expected to disassemble
+devices or to care about the software internals.
+
 %\section{Licensing}
 
 %\chapter{User guide}