Remove architecture doc, distribute info

Put many small READMEs and comments, facilitates exploration and is easier to maintain

.gitattributes

@@ -1,3 +1,6 @@
+# This file tells platforms like GitLab how to treat certain files, e.g.
+# for syntax highlighting.
+
 # GitLab uses the Rouge Ruby gem; for available languages, see:
 # https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers
 

.gitignore

@@ -1,3 +1,6 @@
+# This file tells git what files *not* to track in its version control.
+# Specific files, general suffixes, whole directories etc. can be specified.
+
 # ======================================================================================
 # Python (https://raw.githubusercontent.com/github/gitignore/master/Python.gitignore)
 # ======================================================================================

.gitlab-ci.yml

@@ -1,3 +1,8 @@
+# This file configures the GitLab Continuous Integration system,
+# and as such has little to do with core git, the version control system.
+# See also here: https://docs.gitlab.com/ee/ci/quick_start/#create-a-gitlab-ciyml-file
+# It relies heavily on the Makefile, also part of this repository.
+
 # ======================================================================================
 # ======================================================================================
 # Global defaults, overwritable in each job

.latexmkrc

@@ -1,6 +1,31 @@
 #!/bin/env perl
 
-# Shebang is only to get syntax highlighting right across GitLab, GitHub and IDEs.
+# This file contains instructions and configurations for the `latexmk` program.
+# That program is somewhat like `make`, but tailored to LaTeX.
+# LaTeX has a distinct characteristic of regularly requiring *multiple runs* of
+# the same program (e.g. `lualatex`) before the build is finished.
+# It's a *multi-pass* system.
+# In the intermediary runs, latex generates auxiliary files responsible for resolving
+# references, links, tables of content etc.
+
+# `latexmk` knows about these dependencies (otherwise we tell it in this very config
+# file, see below), detects these and runs latex (and other, outside programs)
+# accordingly.
+
+# Now, why do we need *both* `latexmk` and `make`?
+# Both automate builds.
+
+# `latexmk` is not powerful enough to cover all use cases.
+# `make` is more general and more suitable to be integrated in CI.
+# For our latex needs, `make` basically only delegates to `latexmk`.
+# We **do not** call e.g. `lualatex` multiple times manually from `make`:
+# this logic is left to `latexmk` and `.latexmkrc`.
+# However, `make` can also do much more, e.g. cover `pandoc`, clean-up operations etc.
+# Therefore, `make` and `latexmkrc` *together* are just super powerful and useful.
+
+
+# The shebang at the top is only to get syntax highlighting right across GitLab,
+# GitHub and IDEs.
 # This file is not meant to be run, but read by `latexmk`.
 
 # ======================================================================================

Makefile

@@ -1,3 +1,25 @@
+# This file contains instructions for the GNU `make` program: https://www.gnu.org/software/make/
+#
+# The program is quite old, very stable, ubiquitous and widely used.
+# It is a staple in the Linux world.
+# There are ways to get it to run on Windows, but I haven't tried any.
+# Use WSL (https://docs.microsoft.com/en-us/windows/wsl/install-win10) instead and
+# save yourself the headaches.
+
+# `make` runs steps according to this very `Makefile` in order to arrive at a target,
+# like a PDF compiled with latex.
+# It checks all the dependencies automatically and only updates the target if changes
+# in the sources are detected.
+
+# The idea is that this project's PDFs can be compiled by simply calling e.g.
+# `make file.pdf` *both locally and in CI*.
+# Without make, we would otherwise have very different build steps in local and CI
+# environments.
+# Additionally, using `make`, the CI instructions (.gitlab-ci.yml) can be simplified
+# considerably, leading to decoupling.
+# Moving CI systems then becomes much easier.
+
+
 # =====================================================================================
 # =====================================================================================
 # Prerequisites

bib/README.md

@@ -0,0 +1,8 @@
+# **Bib**liographical data
+
+This directory contains:
+
+1. The [bibliography itself](bibliography.bib).
+ This is auto-generated using [Zotero](https://www.zotero.org/).
+ Using citation management software (any will do) will help you out greatly in managing larger literature collections.
+1. All sorts of [glossaries](glossaries/), which thanks to [`bib2gls`](https://ctan.org/pkg/bib2gls) now also come in `bib` format.

chapters/README.md

@@ -0,0 +1,5 @@
+# Content files
+
+This directory contains all the source `tex` files with the document content.
+Splitting up files, putting them here and then running `\import` or `\subimport` on them is a good way of modularisation.
+It allows to compile only what is needed by commenting out unneeded `\(sub)import` statements, greatly speeding up compilation times.

data/README.md

@@ -0,0 +1,4 @@
+# (Raw) data
+
+This directory contains data used inside the main document, e.g. CSV data for `pgfplots`.
+You can put all sorts of things here.

lib/README.md

@@ -0,0 +1,10 @@
+# Library code
+
+This directory might contain, for example:
+
+- Lua files for usage alongside `lualatex`.
+ Embedding Lua for `lualatex` to consume is quite powerful and neat, and we are gladly making use of it.
+ However, embedding Lua verbatim into `\directlua` is a bit ugly [and has annoying issues with escaping](https://web.archive.org/web/20210208133949if_/https://www.overleaf.com/learn/latex/Articles/An_Introduction_to_LuaTeX_(Part_2):_Understanding_%5Cdirectlua).
+ Therefore, prefer to load external, proper Lua files using `\dofile`.
+ These files might live in here, if required.
+- Outsourced LaTeX source code that is better off modularized, like custom packages.

pandoc/README.md

@@ -0,0 +1,5 @@
+# Pandoc
+
+`pandoc` is a tool almost completely separate from LaTeX, but goes hand-in-hand with it.
+It is not relevant to the main project and used here only as an interesting showcase on how to convert Markdown READMEs to PDF (which uses LaTeX in the background).
+This directory contains configuration files for `pandoc`.