fix source management in asciidoc

8 files changed, 242 insertions, 24 deletions

diff --git a/docs/.gitignore b/docs/.gitignore
index 397e45c..a2f45c2 100644
--- a/docs/.gitignore
+++ b/docs/.gitignore
@@ -1,2 +1,5 @@
 *.pdf
 res
+
+# i know this is bad
+Gemfile.lock
diff --git a/docs/Gemfile b/docs/Gemfile
new file mode 100644
index 0000000..67cd54a
--- /dev/null
+++ b/docs/Gemfile
@@ -0,0 +1,7 @@
+ruby '~> 3.0'
+source 'https://rubygems.org'
+
+gem 'asciidoctor', '~> 2.0'
+gem 'asciidoctor-pdf', '~> 2.3'
+gem 'asciidoctor-bibtex', '~> 0.8.0'
+
diff --git a/docs/makefile b/docs/makefile
index 385ed09..cccc231 100644
--- a/docs/makefile
+++ b/docs/makefile
@@ -1,13 +1,16 @@
 all: plan.pdf
 
-include font.mk
+# include font.mk
 
 # PDFDEPS += $(ALL_FONTS)
 PDFDEPS += ./theme.yml
 
+ASCIIDOCTOR_ARGS += --require asciidoctor-bibtex
+ASCIIDOCTOR_ARGS += --require asciidoctor-pdf
 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)
-	asciidoctor --require asciidoctor-pdf $(ASCIIDOCTOR_ARGS) $<
+	asciidoctor $(ASCIIDOCTOR_ARGS) $<
 
diff --git a/docs/plan.adoc b/docs/plan.adoc
index 778506a..63df9a0 100644
--- a/docs/plan.adoc
+++ b/docs/plan.adoc
@@ -23,7 +23,7 @@ Monday afternoon. The goal is for teams to perform tasks related to electrical
 engineering and computer science programs. The competitive element and
 interaction with other groups are crucial. For the 19-20 introduction, the bomb
 task was created, inspired by the game "Keep Talking and Nobody Explodes." A
-description of the game can be found on the website [1].
+description of the game can be found on the website cite:[Kee23].
 
 Originally, the plan was to create a bomb that needs to be defused and a puzzle
 box generating codes for defusing the bomb. A previous group successfully
@@ -329,9 +329,9 @@ discussed.
 === Version management
 
 All source code developed during this project is kept under version control
-using the Git [2] version control system and is available online at GitHub [3].
-Each software component has a 3-digit version number following semantic
-versioning [4] conventions (major, minor, patch).
+using the Git cite:[gitscm] version control system and is available online at
+GitHub cite:[gitrepo]. Each software component has a 3-digit version number
+following semantic versioning cite:[semver] conventions (major, minor, patch).
 
 This repository also utilizes Git submodules to track the versions of the
 utilized libraries and SDKs. Submodules refer to commits, and can automatically
@@ -339,24 +339,25 @@ be initialized and managed using Git, so are not further specified in this
 document.
 
 All project documentation is realized using Microsoft Office products and is
-therefore stored in a SharePoint folder [5]. These documents use a simple
-2-digit (major, minor) version number system. The documents are published at
-the discretion of the authors, with each new version incrementing the minor
-version number. Major version number 0 is utilized for the document draft
-versions, while 1 is utilized for documents after the project goal is reached.
-A copy of all the documents is kept for each officially published version.
+therefore stored in a SharePoint folder cite:[sharepoint]. These documents use
+a simple 2-digit (major, minor) version number system. The documents are
+published at the discretion of the authors, with each new version incrementing
+the minor version number. Major version number 0 is utilized for the document
+draft versions, while 1 is utilized for documents after the project goal is
+reached. A copy of all the documents is kept for each officially published
+version.
 
 == Planning
 
-This project utilizes GitHub Projects [6] to manage and allocate tasks to team
-members. GitHub Projects supports multiple workflows, but this project only
-follows the Kanban [7] workflow. Since the Kanban workflow does not require
-sprints, the project is divided into milestones. A milestone is considered
-complete once all tasks assigned to it are both marked as ‘complete’ and have
-been reviewed.
+This project utilizes GitHub Projects cite:[githubprojects] to manage and
+allocate tasks to team members. GitHub Projects supports multiple workflows,
+but this project only follows the Kanban cite:[atlassiankanban] workflow. Since
+the Kanban workflow does not require sprints, the project is divided into
+milestones. A milestone is considered complete once all tasks assigned to it
+are both marked as ‘complete’ and have been reviewed.
 
 At the request of the stakeholders, time spent working on the project is
-tracked by each team member using Clockify [8].
+tracked by each team member using Clockify cite:[clockify].
 
 [[fig:planning-condensed]]
 .Condensed Gantt planning
@@ -381,5 +382,5 @@ The qualification phase (<<sec:phase-qualification>>) consists of validating
 the results of the development phase, fixing issues when they are discovered,
 and finalizing all project documentation.
 
-include::share/glossary.adoc[]
+include::share/footer.adoc[]
 
diff --git a/docs/readme.md b/docs/readme.md
index 262cac1..efcf30d 100644
--- a/docs/readme.md
+++ b/docs/readme.md
@@ -1,8 +1,9 @@
 # docs
 
-This folder contains the project documentation in [asciidoc][asciidoc] format.
-A makefile is provided for easily compiling these documents into PDFs for
-submission.
+This folder contains the project documentation in [AsciiDoc][asciidoc] format.
+To compile the documents, make sure you have [Ruby][rubydl] and the
+dependencies installed by running the `bundle` command in this folder. A
+makefile is provided for convenience.
 
 ## TODO
 
@@ -17,7 +18,10 @@ submission.
     - [x] section numbers (headings)
     - [ ] requirements
 - [x] figures
-- [ ] citations
+- [x] citations
 - [ ] glossary
 - [ ] PDF style
 
+[rubydl]: https://www.ruby-lang.org/en/documentation/installation/
+[asciidoc]: https://asciidoc.org/
+
diff --git a/docs/share/footer.adoc b/docs/share/footer.adoc
new file mode 100644
index 0000000..b3edec3
--- /dev/null
+++ b/docs/share/footer.adoc
@@ -0,0 +1,4 @@
+include::references.adoc[]
+
+include::glossary.adoc[]
+
diff --git a/docs/share/references.adoc b/docs/share/references.adoc
new file mode 100644
index 0000000..e475900
--- /dev/null
+++ b/docs/share/references.adoc
@@ -0,0 +1,5 @@
+[references]
+== References
+
+bibliography::[]
+
diff --git a/docs/share/refs.bib b/docs/share/refs.bib
new file mode 100644
index 0000000..f2cb813
--- /dev/null
+++ b/docs/share/refs.bib
@@ -0,0 +1,191 @@
+@online{githubprojects,
+	title = {About Projects - GitHub Docs},
+	url = {https://docs.github.com/en/issues/planning-and-tracking-with-projects/learning-about-projects/about-projects},
+	msbib-accessed = {2024-02-15},
+	year = {2024},
+}
+
+@online{clockify,
+	title = {Clockify - The most popular free time tracker for teams},
+	url = {https://clockify.me/},
+	msbib-accessed = {2024-02-15},
+	year = {2024},
+}
+
+@online{gitscm,
+	title = {Git},
+	url = {https://git-scm.com/},
+	month = feb,
+	msbib-day = {15},
+	year = {2024},
+}
+
+@online{Kee23,
+	title = {Keep talking and nobody explodes - defuse a bomb with your friends.},
+	url = {https://keeptalkinggame.com/},
+	month = oct,
+	msbib-day = {10},
+	year = {2023},
+}
+
+@online{gitrepo,
+	author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas},
+	title = {lonkaars/puzzelbox: Avans Hogeschool project Puzzelbox},
+	url = {https://github.com/lonkaars/puzzelbox},
+	month = feb,
+	msbib-day = {15},
+	year = {2024},
+}
+
+@online{sharepoint,
+	author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas},
+	title = {PROJ-PUZZLE},
+	url = {https://avans-my.sharepoint.com/:f:/r/personal/tv_intanker_student_avans_nl/Documents/PROJ-PUZZLE?csf=1&web=1&e=wbKFig},
+	month = feb,
+	msbib-day = {15},
+	year = {2024},
+}
+
+@online{semver,
+	author = {Preston-Werner, Tom},
+	title = {Semantic Versioning 2.0.0},
+	url = {https://semver.org/},
+	month = jun,
+	msbib-day = {6},
+	year = {2023},
+}
+
+@online{atlassiankanban,
+	author = {Radigan, Dan},
+	title = {Kanban - A brief introduction},
+	url = {https://www.atlassian.com/agile/kanban},
+	msbib-accessed = {2024-02-15},
+	year = {2024},
+}
+
+@techreport{Bek23,
+	author = {Bekema, Frank and Gense, Jasper},
+	title = {Programma van Eisen Puzzel box},
+	year = {2023},
+}
+
+@techreport{styleguide,
+	author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas},
+	title = {Style guide},
+	location = {'s-Hertogenbosch},
+	publisher = {Avans University of Applied Sciences},
+	year = {2024},
+}
+
+@online{Wik22,
+	author = {Wikipedia-contributors},
+	title = {MOSCOW-Methode},
+	url = {https://nl.wikipedia.org/wiki/MoSCoW-methode},
+	month = apr,
+	msbib-day = {5},
+	year = {2022},
+}
+
+@online{rpicpu,
+	url = {https://www.raspberrypi.com/documentation/computers/processors.html},
+}
+
+@online{Ali24,
+	title = {A list of open-source C++ libraries},
+	url = {https://en.cppreference.com/w/cpp/links/libs},
+	msbib-accessed = {2024-02-25},
+}
+
+@online{Boo24,
+	url = {https://www.boost.org/doc/libs/1_75_0/libs/test/doc/html/index.html},
+	msbib-accessed = {2024-02-28},
+}
+
+@online{Git24,
+	title = {GitHub - boostorg/test: The reference C++ unit testing framework (TDD, xUnit, C++03/11/14/17).},
+	url = {https://github.com/boostorg/test},
+	msbib-accessed = {2024-02-28},
+}
+
+@online{Neo,
+	title = {Neotrellis},
+	url = {https://learn.adafruit.com/adafruit-neotrellis/overview},
+}
+
+@techreport{rp2040ds,
+	title = {RP2040 Datasheet},
+	publisher = {Raspberry Pi Ltd},
+	year = {2024},
+}
+
+@online{Cat24,
+	author = {Catchorg},
+	title = {Github - catchorg/Catch2: A modern, C++-native, test framework for unit-tests.},
+	msbib-accessed = {2024-02-25},
+}
+
+@online{Cpp24,
+	author = {Cpputest},
+	title = {Github - cpputest/cpputest: CppUTest unit testing and mocking framework for C/C++.},
+	url = {https://github.com/cpputest/cpputest},
+	msbib-accessed = {2024-02-25},
+}
+
+@online{Doc24,
+	author = {Doctest},
+	title = {Github - doctest/doctest: The fastest feature-rich C++11/14/17/20/23 single-header testing framework.},
+	url = {https://github.com/doctest/doctest},
+	msbib-accessed = {2024-02-25},
+}
+
+@online{goo24,
+	author = {google},
+	title = {GitHub - google/googletest: GoogleTest - Google Testing and Mocking Framework.},
+	url = {https://github.com/google/googletest},
+	msbib-accessed = {2024-02-28},
+}
+
+@online{Joh21,
+	author = {Johnston, P.},
+	title = {Embedded systems testing resources},
+	url = {https://embeddedartistry.com/blog/2018/10/18/embedded-systems-testing-resources/},
+	month = jun,
+	msbib-day = {10},
+	msbib-accessed = {2024-02-25},
+	year = {2021},
+}
+
+@techreport{research,
+	author = {Blansch, Loek Le and Hammer, Elwin and Faase, Lars and in 't Anker, Thomas},
+	title = {Research Document},
+	location = {'s-Hertogenbosch},
+	publisher = {Avans University of Applied Sciences},
+	year = {2024},
+}
+
+@techreport{2021_design,
+	author = {Creemers, Merel and van Wiechen, Joost and Lengowski, Vincent and Maas, Justin},
+	title = {Ontwerpdocument},
+	language = {dutch},
+	location = {'s-Hertogenbosch},
+	publisher = {Avans University of Applied Sciences},
+	year = {2021},
+}
+
+@techreport{2122_handover,
+	author = {van Gastel, Lucas and de Bruin, Julian and Rockx, Toon and van Kuijk, Alex and Baars, Jef},
+	title = {Overdrachtsdocument},
+	language = {dutch},
+	location = {'s-Hertogenbosch},
+	publisher = {Avans University of Applied Sciences},
+	year = {2022},
+}
+
+@techreport{2122_design,
+	author = {van Gastel, Lucas and de Bruin, Julian and Rockx, Toon and van Kuijk, Alex and Baars, Jef},
+	title = {Design document},
+	language = {dutch},
+	location = {'s-Hertogenbosch},
+	publisher = {Avans University of Applied Sciences},
+	year = {2022},
+}