small refactor + create software design document

6 files changed, 44 insertions, 26 deletions

diff --git a/docs/design.adoc b/docs/design.adoc
new file mode 100644
index 0000000..b653633
--- /dev/null
+++ b/docs/design.adoc
@@ -0,0 +1,5 @@
+:document: Software Design
+include::share/meta.adoc[]
+
+
+include::share/footer.adoc[]
diff --git a/docs/makefile b/docs/makefile
index 496a6e6..1fbb5b4 100644
--- a/docs/makefile
+++ b/docs/makefile
@@ -1,6 +1,7 @@
 all: plan.pdf
-all: requirements.pdf
+all: reqs.pdf
 all: research.pdf
+all: design.pdf
 
 # include font.mk
 
@@ -15,9 +16,6 @@ ASCIIDOCTOR_ARGS += --require asciidoctor-pdf
 # ASCIIDOCTOR_ARGS += --require ./plugin/helloworld
 ASCIIDOCTOR_ARGS += --require asciidoctor-interdoc-reftext
 ASCIIDOCTOR_ARGS += --backend pdf
-ASCIIDOCTOR_ARGS += --attribute pdf-theme=./theme.yml
-# ASCIIDOCTOR_ARGS += --attribute pdf-fontsdir=./res/font
-ASCIIDOCTOR_ARGS += --attribute bibtex-file=./share/refs.bib
 %.pdf: %.adoc $(PDFDEPS)
 	bundle exec asciidoctor $(ASCIIDOCTOR_ARGS) $<
 
diff --git a/docs/plan.adoc b/docs/plan.adoc
index 8825459..e935c86 100644
--- a/docs/plan.adoc
+++ b/docs/plan.adoc
@@ -1,4 +1,4 @@
-= Project Plan: {project}
+:document: Project Plan
 include::share/meta.adoc[]
 
 == Introduction
diff --git a/docs/requirements.adoc b/docs/reqs.adoc
index e3225a5..edddbdd 100644
--- a/docs/requirements.adoc
+++ b/docs/reqs.adoc
@@ -1,4 +1,4 @@
-= Project Requirements: {project}
+:document: Project Requirements
 include::share/meta.adoc[]
 
 == Introduction
diff --git a/docs/research.adoc b/docs/research.adoc
index 7e5b78c..5d4f381 100644
--- a/docs/research.adoc
+++ b/docs/research.adoc
@@ -1,4 +1,4 @@
-= Research: {project}
+:document: Research
 include::share/meta.adoc[]
 
 == Microcontrollers used in the current state.
@@ -124,15 +124,14 @@ controller and controller used in puzzle modules.
 The following criteria were used to compare MCUs that are suitable candidates
 as main controller unit:
 
-* Must have at least 1 I^2^C peripheral
-  (<<requirements.adoc#req:main-i2c-ctrl>>).
+* Must have at least 1 I^2^C peripheral (<<reqs.adoc#req:main-i2c-ctrl>>).
 * Must be able to connect to a standard 802.11b/g/n access point
-  (<<requirements.adoc#req:main-802-11-ap>>).
+  (<<reqs.adoc#req:main-802-11-ap>>).
 * Must be able to serve TCP socket connection(s)
-  (<<requirements.adoc#req:main-tcp-socket>>).
-* Should be power efficient (<<requirements.adoc#req:main-pwr-efficient>>).
+  (<<reqs.adoc#req:main-tcp-socket>>).
+* Should be power efficient (<<reqs.adoc#req:main-pwr-efficient>>).
 * Is available as a development kit from Farnell
-  (<<requirements.adoc#req:main-devkit-supplier>>).
+  (<<reqs.adoc#req:main-devkit-supplier>>).
 
 <<tab:1>> lists the considered MCU options matching the above criteria. This
 list is a compilation of microcontroller offerings from the following
@@ -160,14 +159,13 @@ The Raspberry Pi Pico W board is utilized during development.
 The following criteria were used to compare MCUs that are suitable candidates
 for controlling the puzzle modules:
 
-* Must have at least 1 I^2^C peripheral
-  (<<requirements.adoc#req:pm-i2c-ctrl>>).
+* Must have at least 1 I^2^C peripheral (<<reqs.adoc#req:pm-i2c-ctrl>>).
 * Should has enough I/O ports to directly control moderately complex puzzles
-  (<<requirements.adoc#req:pm-gpio>>).
-* Should be power efficient (<<requirements.adoc#req:pm-pwr-efficient>>).
+  (<<reqs.adoc#req:pm-gpio>>).
+* Should be power efficient (<<reqs.adoc#req:pm-pwr-efficient>>).
 * Is available as a development kit from Farnell
-  (<<requirements.adoc#req:pm-devkit-supplier>>).
-* Has a configurable clock speed (<<requirements.adoc#req:pm-clk-ctrl>>).
+  (<<reqs.adoc#req:pm-devkit-supplier>>).
+* Has a configurable clock speed (<<reqs.adoc#req:pm-clk-ctrl>>).
 
 <<tab:2>> lists the considered MCU options matching the above criteria. This
 list is a compilation of microcontroller offerings from the following
diff --git a/docs/share/meta.adoc b/docs/share/meta.adoc
index 0b6cb78..15d8d18 100644
--- a/docs/share/meta.adoc
+++ b/docs/share/meta.adoc
@@ -1,8 +1,13 @@
-:sectnums:
-:title-page:
-:toc:
-:toclevels: 4
-:pagenums:
+// (these files are included from the parent directory)
+:pdf-theme: ./theme.yml
+// :pdf-fontsdir: ./res/font
+:bibtex-file: ./share/refs.bib
+
+// document / project info
+ifndef::document[]
+:document: DOCUMENT TITLE
+endif::[]
+:project: Project Puzzlebox
 :revnumber: 0.0
 :revdate: 2024-04-01
 :revremark: draft
@@ -10,7 +15,19 @@
 :author_2: Loek Le Blansch
 :author_3: Lars Faase
 :author_4: Elwin Hammer
+
+// numbering / reference styles
+:sectnums:
+:toclevels: 4
+:pagenums:
 :xrefstyle: short
-:project: Project Puzzlebox
 
-// see https://docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes-ref
+// (set and display title)
+= {document}: {project}
+// start each document with a title page
+:title-page:
+// followed by a table of contents
+:toc:
+
+// also https://docs.asciidoctor.org/asciidoc/latest/attributes/document-attributes-ref
+