Merge remote-tracking branch 'origin/jaro/project-plan' into max/project-plan

16 files changed, 759 insertions, 40 deletions

diff --git a/.gitignore b/.gitignore
index efdebb8..efae07a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,6 +25,7 @@
 *.d
 *.nav
 *.snm
+*-SAVE-ERROR
 
 # output files
 *.pdf
diff --git a/.vscode/extensions.json b/.vscode/extensions.json
new file mode 100644
index 0000000..e2e2139
--- /dev/null
+++ b/.vscode/extensions.json
@@ -0,0 +1,5 @@
+{
+	"recommendations": [
+		"EditorConfig.EditorConfig"
+	]
+}
diff --git a/.vscode/settings.json b/.vscode/settings.json
index 72f0e6b..25effcc 100644
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -1,4 +1,8 @@
 {
+	"editor.wordWrap": "wordWrapColumn",
+	"editor.wrappingIndent": "same",
+	"editor.wordWrapColumn": 85,
+	"files.trimTrailingWhitespace": true,
 	"latex-workshop.latex.recipe.default": "latexmk",
 	"latex-workshop.latex.tools": [
 		{
diff --git a/comparison.sty b/comparison.sty
new file mode 100644
index 0000000..d10f95f
--- /dev/null
+++ b/comparison.sty
@@ -0,0 +1,80 @@
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesPackage{comparison}[2024-01-19 package comparison]
+
+\RequirePackage{booktabs}
+\RequirePackage{etoolbox}
+\RequirePackage{tabularx}
+\RequirePackage{environ}
+\RequirePackage{enumitem}
+
+% comparison environment, usage:
+%
+% \begin{comparison}
+% 	\pro{reason why thing is good}
+% 	\pro{...}
+% 	\con{reason why thing is bad}
+% 	\con{...}
+% \end{comparison}
+%
+% output:
+%
+% Pros (2)                      Cons (2)
+% ----------------------------------------------------------
+%  - reason why thing is good    - reason why thing is bad
+%  - ...                         - ...
+%
+
+\newcounter{pro-count}
+\newcounter{pro-index}
+\newcounter{con-count}
+\newcounter{con-index}
+\newcounter{cmp-count}
+\newcounter{cmp-index}
+\NewEnviron{comparison}{%
+	\par%
+	\setcounter{pro-count}{0}%
+	\newcommand{\pro}[1]{%
+		\stepcounter{pro-count}%
+		\csdef{pro-\the\value{pro-count}}{##1}%
+	}%
+	\setcounter{con-count}{0}%
+	\newcommand{\con}[1]{%
+		\stepcounter{con-count}%
+		\csdef{con-\the\value{con-count}}{##1}%
+	}%
+	\BODY%
+	\def\spacing{3mm}%
+	\newcommand{\halfbox}[1]{%
+		\begin{minipage}[t]{\dimexpr(\linewidth - \spacing) / 2\relax}%
+			##1%
+		\end{minipage}%
+	}%
+	\begin{minipage}{\linewidth}%
+		\halfbox{\strut\centering\textsc{Benefits}~(\the\value{pro-count})\strut}%
+		\hfill%
+		\halfbox{\strut\centering\textsc{Drawbacks}~(\the\value{con-count})\strut}%
+		\par%
+		\vspace*{\dimexpr-\parskip-0.5\baselineskip\relax}%
+		\noindent\rule{\linewidth}{0.66pt}\par%
+		\vspace*{\dimexpr-\parskip\relax}%
+		\halfbox{%
+			\begin{itemize}[leftmargin=5mm]%
+				\setcounter{pro-index}{0}%
+				\whileboolexpr{test{\ifnumcomp{\value{pro-index}}{<}{\value{pro-count}}}}{%
+					\stepcounter{pro-index}%
+					\item \csuse{pro-\the\value{pro-index}}%
+				}%
+			\end{itemize}%
+		}\hfill\halfbox{%
+			\begin{itemize}[leftmargin=5mm]%
+				\setcounter{con-index}{0}%
+				\whileboolexpr{test{\ifnumcomp{\value{con-index}}{<}{\value{con-count}}}}{%
+					\stepcounter{con-index}%
+					\item \csuse{con-\the\value{con-index}}%
+				}%
+			\end{itemize}%
+		}%
+	\end{minipage}%
+	\par%
+}
+
diff --git a/contributing.md b/contributing.md
index 770d02e..c11c834 100644
--- a/contributing.md
+++ b/contributing.md
@@ -10,12 +10,17 @@ other document.
 
 - Indent using tabs
 - Wrap long lines at column 80
-- Diacritical marks should be represented in ASCII using LaTeX syntax instead
-  of using UTF-8 (i.e. `fa\c{c}ade` instead of `façade`)
+- ASCII only (LaTeX syntax should be used instead of UTF-8, i.e. `fa\c{c}ade`
+  instead of `façade`, `---` instead of `—`)
 - Images should be placed in the img/ folder
 - Labels and bibliography keys should only consist of characters from the
   following set: `[a-z0-9:-]` (lower-case, numbers, colon, dash).
-- Quotes are opened with the tilde (<code>`</code>)
+- Both single and double quotes are opened using backtick(s)
+  (<code>&#96</code>) and closed using single quote(s) (`'`), i.e.
+  <code>&#96&#96like this''</code> or <code>&#96this'</code>
+- Only environments indent the LaTeX source code
+- Insert a non-breaking space (`~`) after (Latin) abbreviations such as "i.e."
+  or "e.g.". Never place a comma after either of these.
 
 # Banned practices
 
@@ -27,7 +32,7 @@ other document.
   command should be used instead.
 - **Using `\href`**
 
-  Add the source in sources.bib and cite this source instead.
+  Add the source in [sources.bib](#sources) and cite this source instead.
 - **Using `\textbf` or `\textit` to emphasize**
 
   Use `\emph`, single quotes or an em dash (`---`) instead.
@@ -51,21 +56,47 @@ Please use prefixes to 'namespace' `\label`s:
 |Sections|`sec:`|
 |List items (i.e. `enumerate`/`itemize`)|`item:`|
 
+These items can be referenced using the `\cref` command.
+
 ## Sources
 
 Bibliography entries work with a similar label system (usually called *keys*).
 Since these exist in a registry separate from `\label` entries, these do not
-need to be prefixed.
+need to be prefixed. All sources are stored in [sources.bib](./sources.bib).
+There is a very helpful [cheat sheet][biblatex-cheat-sheet] online that
+showcases different entry types and their fields.
 
-For consistency, the following format is preferred: `authority:topic`. The
-`authority` part refers to a company, website or author, and `topic` refers to
-a title, chip model number, etc. depending on the type of document being
+For consistency, the following format for keys is preferred: `authority:topic`.
+The `authority` part refers to a company, website or author, and `topic` refers
+to a title, chip model number, etc. depending on the type of document being
 referenced.
 
-<!--
-TODO
-- Cross-references and citations should be handled using cleveref
--->
+## Glossary
+
+Glossary entries are stored in [glossary.bib](./glossary.bib). This file has
+the same structure as the bibliography, but with different key types:
+
+|type|usage|
+|-|-|
+|`@abbreviation`|Abbreviations (long version inserted on first occurrence)|
+|`@acronym`|Acronyms (long version only in glossary)|
+|`@entry`|Generic entries / words|
+
+The keys in the glossary do not have to be prefixed, and should be short as
+they should be inserted frequently. Glossary entries can be used with the
+following commands:
+
+|command|usage|
+|-|-|
+|`\gls{<key>}`|regular|
+|`\glspl{<key>}`|plural|
+|`\Gls{<key>}`|capitalized (at start of sentence)|
+|`\Glspl{<key>}`|capitalized plural|
+
+> [!NOTE]
+> Glossary entries should not be inserted in figure captions or section
+> headings!
 
 [crepe-engine-contrib]: https://github.com/lonkaars/crepe/blob/master/contributing.md
+[biblatex-cheat-sheet]: https://tug.ctan.org/info/biblatex-cheatsheet/biblatex-cheatsheet.pdf
 
diff --git a/example.tex b/example.tex
index 8525973..ce45f6f 100644
--- a/example.tex
+++ b/example.tex
@@ -108,7 +108,7 @@ The \codeinline{blockcode} environment can be used to insert a code block:
 This is all included verbatim: \verb|asdf| \ $%!(*@#&)$
 \end{blockcode}
 
-\subsection{Lists}
+\subsection{Information dumps}
 
 Unordered (bullet) list:
 
@@ -136,9 +136,34 @@ Numbered list:
 
 (See \cref{item:enum-nest-ref})
 
+Description:
+
+\begin{description}
+	\item[Item one] description of item one
+	\item[Item two] description of item two
+	\item[Item three] ...
+\end{description}
+
+\subsection{Comparisons}
+
+\begin{comparison}
+	\pro{Good thing}
+	\con{Bad thing}
+	\pro{Good thing 2}
+	\con{Bad thing 2}
+\end{comparison}
+
 \subsection{Citations}
 
 Citations are inserted using the \codeinline{\autocite} command \autocite{rfc:3339}.
+The bibliography is automatically printed after \codeinline{\end{document}}.
+
+\subsection{Glossary}
+
+Glossary entries can be inserted using the \codeinline{\gls} commands. Example:
+``\Gls{sdl2} handles \glspl{hid} as well!''. In following occurrences of acronyms,
+only their short form is printed: `\gls{sdl2}' and `\gls{hid}'. All of these link to
+the glossary that is automatically printed after \codeinline{\end{document}}.
 
 \end{document}
 
diff --git a/glossary.bib b/glossary.bib
new file mode 100644
index 0000000..4d02e4a
--- /dev/null
+++ b/glossary.bib
@@ -0,0 +1,30 @@
+@abbreviation{ecs,
+	short = {ECS},
+	long = {Entity-Component System},
+}
+
+@abbreviation{hid,
+	short = {HID},
+	long = {Human Interface Device},
+}
+
+@abbreviation{sdl2,
+	short = {SDL2},
+	long = {Simple DirectMedia Layer},
+}
+
+@abbreviation{sfml,
+	short = {SFML},
+	long = {Simple and Fast Multimedia Library},
+}
+
+@entry{opengl,
+	name = {OpenGL},
+	description = {Open-source graphics library},
+}
+
+@entry{d3d,
+	name = {Direct3D},
+	description = {Graphics library developed by \hbox{Microsoft}},
+}
+
diff --git a/latexmkrc b/latexmkrc
index ad6c178..66ed0d1 100644
--- a/latexmkrc
+++ b/latexmkrc
@@ -2,3 +2,48 @@ $pdflatex = "xelatex %O %S";
 $pdf_mode = 1;
 $dvi_mode = 0;
 $postscript_mode = 0;
+
+# https://tex.stackexchange.com/questions/400325/latexmkrc-for-bib2gls
+add_cus_dep('glo', 'gls', 0, 'run_makeglossaries');
+add_cus_dep('acn', 'acr', 0, 'run_makeglossaries');
+add_cus_dep('aux', 'glstex', 0, 'run_bib2gls');
+
+sub run_makeglossaries {
+  if ( $silent ) {
+    system "makeglossaries -q '$_[0]'";
+  } else {
+    system "makeglossaries '$_[0]'";
+  };
+}
+
+sub run_bib2gls {
+  if ( $silent ) {
+    my $ret = system "bib2gls --silent --group '$_[0]'";
+  } else {
+    my $ret = system "bib2gls --group '$_[0]'";
+  };
+  my ($base, $path) = fileparse( $_[0] );
+  if ($path && -e "$base.glstex") {
+    rename "$base.glstex", "$path$base.glstex";
+  }
+  # Analyze log file.
+  local *LOG;
+  $LOG = "$_[0].glg";
+  if (!$ret && -e $LOG) {
+    open LOG, "<$LOG";
+    while (<LOG>) {
+      if (/^Reading (.*\.bib)\s$/) {
+        rdb_ensure_file( $rule, $1 );
+      }
+    }
+    close LOG;
+  }
+  return $ret;
+}
+
+push @file_not_found, '^Package .* No file `([^\\\']*)\\\'';
+push @generated_exts, 'glo', 'gls', 'glg';
+push @generated_exts, 'acn', 'acr', 'alg';
+$clean_ext .= ' %R.ist %R.xdy';
+$clean_ext .= ' bbl run.xml';
+
diff --git a/makefile b/makefile
index 6c234ba..02c583e 100644
--- a/makefile
+++ b/makefile
@@ -12,3 +12,5 @@ LATEXMKFLAGS += -interaction=nonstopmode
 %.tex: %.txt
 	./time2tex.py $< > $@
 
+timerep.pdf: time.tex
+
diff --git a/projdoc.cls b/projdoc.cls
index c6abaca..388f901 100644
--- a/projdoc.cls
+++ b/projdoc.cls
@@ -14,6 +14,18 @@
 \PassOptionsToPackage{nosort}{cleveref}
 \PassOptionsToPackage{nameinlink}{cleveref}
 \PassOptionsToPackage{obeyspaces}{url}
+\PassOptionsToPackage{toc=false}{glossaries}
+\PassOptionsToPackage{record}{glossaries-extra}
+\PassOptionsToPackage{
+	backend=biber,
+	bibencoding=utf8,
+	style=iso-numeric,
+	% Technically, Avans University of Applied Sciences requires that we always use APA
+	% style references, but this often results in ugly citations when working with
+	% technical or online resources. At the end of the day, the bibliography is there
+	% to prove we didn't plagiarize or make shit up, so ISO 690 is *probably* fine.
+	autocite=plain,
+}{biblatex}
 
 % frequently used packages
 \RequirePackage{geometry}
@@ -38,9 +50,14 @@
 \RequirePackage{cleveref}
 \RequirePackage{adjustbox}
 \RequirePackage{xparse}
+\RequirePackage{biblatex}
+\RequirePackage{glossaries}
+\RequirePackage{glossaries-extra}
 \RequirePackage{ifdraft}
 \RequirePackage{enumitem}
 \RequirePackage{subcaption}
+\RequirePackage{multicol}
+\RequirePackage{comparison} % ./comparison.sty
 
 % font style
 \setmainfont{TeX Gyre Schola}
@@ -171,18 +188,14 @@
 \makeatother
 
 % bibliography
-\usepackage[
-	backend=biber,
-	bibencoding=utf8,
-	style=iso-numeric,
-	% Technically, Avans University of Applied Sciences requires that we always use APA
-	% style references, but this often results in ugly citations when working with
-	% technical or online resources. At the end of the day, the bibliography is there
-	% to prove we didn't plagiarize or make shit up, so ISO 690 is *probably* fine.
-	autocite=plain,
-]{biblatex}
 \addbibresource{sources.bib}
 
+% glossary
+\GlsXtrLoadResources[
+	src={./glossary.bib},
+	selection={recorded and deps and see},
+]
+
 % default document header/trailer
 \makeatletter
 \def\projdoc@header{
@@ -196,8 +209,16 @@
 \newbool{projdoc@cited}
 \apptocmd{\abx@aux@cite}{\global\booltrue{projdoc@cited}}{}{}
 \def\projdoc@trailer{
-	% end with bibliography (if citations used)
+	% bibliography (if citations used)
 	\ifbool{projdoc@cited}{\printbibliography}{}%
+	% glossary
+	\ifcsundef{printunsrtglossary}{}{%
+		\section*{Glossary}%
+		\begin{multicols}{2}%
+			\renewcommand{\glossarysection}[2][]{}%
+			\printunsrtglossary%
+		\end{multicols}%
+	}%
 }
 \AtBeginDocument{\projdoc@header}
 \AtEndDocument{\projdoc@trailer}
diff --git a/readme.md b/readme.md
index e8b3784..1375c5e 100644
--- a/readme.md
+++ b/readme.md
@@ -10,9 +10,22 @@ Please see [style.md](./style.md) for writing style and
 - A `latexmkrc` file is provided for copmilation with `latexmk`. The documents
   should also compile under [Visual Studio Code][vscode] using the [LaTeX
   Workshop extension][latexworkshop], as well as [VimTeX][vimtex].
+- A [makefile](./makefile) is used to compile other files (e.g. plantuml
+  diagrams, [time report](#time-report))
 - These documents use fonts loaded using `fontspec`, please see
   [style.md](./style.md) for download links.
-- A `makefile` is provided for compiling other files (e.g. plantuml diagrams)
+
+## Time report
+
+The time report document includes generated LaTeX code which can be compiled
+from [time.txt](./time.txt) using [time2tex.py](./time2tex.py). The
+[makefile](./makefile) includes a rule that does this, so `make timerep.pdf`
+should be used to compile this document specifically.
+
+## Requirements
+
+TODO: how to store + cross-reference requirements w/o extra latex compilation
+runs
 
 [vscode]: https://code.visualstudio.com
 [latexworkshop]: https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop
diff --git a/research.tex b/research.tex
new file mode 100644
index 0000000..ca2afed
--- /dev/null
+++ b/research.tex
@@ -0,0 +1,207 @@
+\documentclass{projdoc}
+\input{meta.tex}
+
+\title{Research document}
+
+\begin{document}
+\tablestables
+\newpage
+
+\section{Introduction}
+
+\section{Game engine}
+
+\subsection{Introduction}
+
+To build a game engine, it must first be understood how it operates. The
+functionalities it requires and how these functionalities work together must be
+determined. In this section, the general functioning of a game engine and the
+different parts required are described.
+
+\subsection{Findings}
+
+A game engine is not the game itself but a platform with which games are built. It
+should provide the functionalities with which the game is constructed. The purpose of
+a game engine is not to create data out of nothing. Instead, data is read, and the
+correlating features and effects are generated. However, the engine is also used to
+create these files, referred to as ``assets.'' The game engine must be able to accept
+a certain format of these assets---whether levels, sprites, or textures---and convert
+them into usable data.
+
+\subsubsection{Layers}
+
+A game engine is composed of multiple layers, each with its own functions. These
+layers are divided into the following categories:\noparbreak
+\begin{description}
+	\item[Resource manager] Responsible for what happens when the engine is launched,
+		including loading data formats.
+	\item[Application] Manages the run loop, time, code execution, and events
+		(e.g.~input events).
+	\item[Window/\glspl{hid}] Handles input and events.
+	\item[Renderer] Responsible for drawing the necessary objects on the screen,
+		usually once per frame.
+	\item[Debugging support] Provides testing for the engine, such as logging or
+		performance profiling.
+	\item[Scripting layer] Runs scripts, such as Lua or Python.
+	\item[Memory systems] Handles and monitors memory usage.
+	\item[\gls{ecs}] Provides a modular way to create game objects, add physics, and
+		define how the engine interacts with objects.
+	\item[Physics] Adds specific physics to objects.
+	\item[Audio] Processes audio.
+	\item[AI] Provides artificial inteligent behavior.
+\end{description}
+
+\subsubsection{ECS}
+
+A game engine must have the ability to keep track and update several game objects. To
+do this most game engines employ an \gls{ecs} model which uses modulair components to
+give entities properties and features. The need for an entity component system arises
+because multiple game objects are required to create a scene in a game. These game
+objects exist within the scene and perform actions, such as a UI display for a score.
+This game object does not need to be rendered; it could be a script running in the
+background. It could also be a player sprite that is controlled. These entities need
+to be aware of other entities, for example, during collisions. For this to function,
+a scene is required to host all game objects. Within this scene, the game objects
+must be stored efficiently, and entities must be provided with the required behavior,
+such as audio, position, or physics. To create diverse entities with specific
+functions: A scene can contain many different kinds of entities, each with different
+properties and functions. But no matter how different each entity is, it remains an
+entity. To assign properties and functions to entities, components are used. Entt is
+an example of an \gls{ecs}.
+% TODO: ref?entt
+
+\subsection{Conclusion}
+
+\section{Third-party Tools}
+
+\subsection{Introduction}
+
+Developing a game engine from scratch requires a significant amount of time, as many
+different features are necessary. Fortunately, some of these features have already
+been developed and can be reused in the form of frameworks and third-party
+tools/libraries. The decision to use third-party libraries, and the selection of
+which ones to use, directly influences the development process of the game engine. In
+this section, several third-party frameworks and tools available for use are
+described.
+
+\subsection{Findings}
+
+\subsubsection{Media Frameworks}
+
+A game engine must have the ability to handle user input, render graphics, and
+process audio. Several large frameworks are available that provide these features and
+are already widely used by other game engines. The two most popular and
+best-supported options are \gls{sdl2} and \gls{sfml}.
+
+\paragraph{SDL2}
+
+% TODO: ref?sdl2
+According to its official website, \gls{sdl2} is \emph{``a cross-platform development
+library designed to provide low-level access to audio, keyboard, mouse, joystick, and
+graphics hardware via \gls{opengl} and \gls{d3d}. It is used by video playback
+software, emulators, and popular games, including Valve's award-winning catalog and
+many Humble Bundle games.''} \gls{sdl2} is written in the C programming language, and
+therefore, structs and functions are used instead of objects and methods.
+
+The advantages of \gls{sdl2} are:\noparbreak
+\begin{itemize}
+	\item Controller support is provided.
+	\item 2D and 3D rendering are supported.
+	\item Broad multiplatform support is offered, including older consoles such as the
+		Wii.
+	\item Low-level control is available.
+	\item A large community ensures wide usage.
+	\item Extended libraries can be used to add functionalities, such as SDL\_Mixer for
+		sound.
+\end{itemize}
+
+The disadvantages of \gls{sdl2} are:\noparbreak
+\begin{itemize}
+	\item A limited built-in 2D renderer is provided.
+	\item Extended libraries require setup.
+\end{itemize}
+
+\paragraph{SFML}
+
+\gls{sfml} is a simple framework consisting of five modules: audio, graphics,
+network, system, and window. This framework, written in C++, was designed to simplify
+game development.
+
+The advantages of \gls{sfml} are:
+\begin{itemize}
+	\item Object-oriented design is provided since it is written in C++.
+	\item A built-in 2D renderer is available for ease of use.
+	\item A built-in audio system is included.
+	\item Cross-platform support is available for Linux, Windows, and macOS.
+	\item Networking capabilities are provided for multiplayer or networked
+		applications.
+\end{itemize}
+
+The disadvantages of \gls{sfml} are:
+\begin{itemize}
+	\item The 2D rendering engine may experience performance issues in large-scale
+		games.
+	\item The community is smaller compared to \gls{sdl2}.
+	\item No native 3D support is provided.
+	\item Not all image formats are supported.
+\end{itemize}
+
+\subsubsection{Audio}
+
+for audio some options could be: FMOD, Wwise, or iirKlang
+
+\subsection{Conclusion}
+
+\section{Gameloop/resource manager}
+
+\subsection{Introduction}
+
+\subsection{Findings}
+
+\subsection{Conclusion}
+
+\section{Rendering}
+
+\subsection{Introduction}
+
+\subsection{Findings}
+
+\subsection{Conclusion}
+
+\section{Event manager}
+
+\subsection{Introduction}
+
+\subsection{Findings}
+
+\subsection{Conclusion}
+
+\section{Memory/debugging}
+
+\subsection{Introduction}
+
+\subsection{Findings}
+
+\subsection{Conclusion}
+
+\section{Physics/scripting}
+
+\subsection{Introduction}
+
+\subsection{Findings}
+
+\subsection{Conclusion}
+
+\section{Conclusion}
+
+\section{Gameobjects/components}
+
+\subsection{Introduction}
+
+\subsection{Findings}
+
+\subsection{Conclusion}
+
+\section{Conclusion}
+
+\end{document}
diff --git a/style.md b/style.md
index bbddddf..c518e7c 100644
--- a/style.md
+++ b/style.md
@@ -1,3 +1,9 @@
+This document contains requirements for all project documentation. Specific
+LaTeX commands and LaTeX source style requirements are detailed in
+[contributing.md](./contributing.md), and [example.tex](./example.tex) contains
+a number of frequently used snippets that may be used as a cheat-sheet style
+reference.
+
 # Fonts
 
 The documents use the following fonts. All of these are free and open source,
@@ -23,7 +29,9 @@ workshop and VimTeX.
 
 # Spelling
 
-All documentation is written in U.S. English
+- All documentation is written in U.S. English
+- Section headers are in sentence case (i.e. only the first word and proper
+  nouns are capitalized)
 
 # Grammar
 
@@ -51,3 +59,18 @@ converted to PDF (e.g. using `svg2pdf` on linux).
 Raster images should only be used when the source is already in a raster format
 (e.g. for photos) or when otherwise impractical.
 
+# References
+
+- When a library or piece of software is introduced in a document, reference
+  the project homepage using the bibliography.
+- Direct quotations or paraphased text must be cited.
+- Acronyms, abbreviations and jargon reference the glossary.
+- All figures and tables must be referenced in the body text. Don't write
+  paragraphs that 'lead up' to figures, as this forces LaTeX to not break the
+  page between the paragraph and figure.
+
+# Document structure
+
+- Use `\section`, `\subsection`, `\subsubsection` and `\paragraph` to insert
+  headings.
+
diff --git a/time.txt b/time.txt
index c80fabf..4e5f2f6 100644
--- a/time.txt
+++ b/time.txt
@@ -1,13 +1,62 @@
-# <who>: <when> <how long> <what>
+loek: 2024-09-02 1h project meeting :: project kickoff
+loek: 2024-09-02 45m project meeting
 loek: 2024-09-02 1h4m repository scaffolding
 loek: 2024-09-03 25m repository scaffolding
-loek: 2024-09-03 1h30m repository scaffolding / engine repository, unit testing
-loek: 2024-09-04 1h30m repository scaffolding / latex example code
-loek: 2024-09-04 50m poc / dynamic library linking test example
-loek: 2024-09-04 45m repository scaffolding / visual studio code latex configuration
-loek: 2024-09-04 20m repository scaffolding / visual studio code cmake configuration
-loek: 2024-09-05 15m repository scaffolding / additional latex contributing guidelines
+loek: 2024-09-03 1h30m repository scaffolding :: engine repository, unit testing
+loek: 2024-09-04 1h30m repository scaffolding :: latex example code
+loek: 2024-09-04 50m poc :: dynamic library linking test example
+loek: 2024-09-04 45m repository scaffolding :: visual studio code latex configuration
+loek: 2024-09-04 20m repository scaffolding :: visual studio code cmake configuration
+loek: 2024-09-05 15m repository scaffolding :: additional latex contributing guidelines
 loek: 2024-09-05 1h40m project meeting
+loek: 2024-09-05 1h24m time report script
+loek: 2024-09-06 55m time report script
+loek: 2024-09-09 30m feedback :: niels code style guide
+loek: 2024-09-09 45m review :: wouter research PR#5
+loek: 2024-09-09 25m documentation style guide
+loek: 2024-09-10 1h55m project meeting
+loek: 2024-09-10 25m briefing :: watch bob videos
+loek: 2024-09-10 5m docs :: update readme
+loek: 2024-09-10 12m docs :: add comparison package and more example latex code
+loek: 2024-09-10 30m project meeting
 
-# vim:ft=cfg
+max: 2024-09-02 1h project meeting :: project kickoff
+max: 2024-09-02 45m project meeting
+max: 2024-09-04 1h30m installing and configuring latex
+max: 2024-09-04 2h reading project info
+max: 2024-09-05 20m discussing GitHub with Jaro
+max: 2024-09-05 1h30m first group meeting
+
+wouter: 2024-09-02 1h project meeting :: project kickoff
+wouter: 2024-09-02 45m project meeting
+wouter: 2024-09-03 1h reading project info
+wouter: 2024-09-04 1h setting up working environment
+wouter: 2024-09-04 1h30m researching 3rd party tools
+wouter: 2024-09-05 1h30m first group meeting
+wouter: 2024-09-05 20m setting up research document
+wouter: 2024-09-05 1h researching game enigne
+
+niels: 2024-09-02 1h project meeting :: project kickoff
+niels: 2024-09-02 45m project meeting
+niels: 2024-09-03 1h reading project info
+niels: 2024-09-04 30m validation app ideas
+niels: 2024-09-04 2h setting up vimtex on neovim
+niels: 2024-09-04 1h researching different code styles and c++ guidelines
+niels: 2024-09-05 1h30m first group meeting
+niels: 2024-09-06 2h added c++ guidelines in the contributing.md
 
+jaro: 2024-09-02 1h project meeting :: project kickoff
+jaro: 2024-09-02 45m project meeting
+jaro: 2024-09-02 1h45m scrumboard(miro), installing dependencies
+jaro: 2024-09-03 1h project lesson
+jaro: 2024-09-04 4h15m latex environment, code environment and project plan
+jaro: 2024-09-05 2h preparing meeting, project plan, discussing github with max
+jaro: 2024-09-05 1h30m project meeting
+jaro: 2024-09-05 1h documentatie review and improving environment
+jaro: 2024-09-06 30m weekly update
+jaro: 2024-09-09 1h project plan
+jaro: 2024-09-10 1h preparing meeting and project plan
+jaro: 2024-09-10 1h30m project meeting
+jaro: 2024-09-10 1h project disussing research
+
+# vim:ft=cfg
diff --git a/time2tex.py b/time2tex.py
index 3244b8f..fe3091f 100755
--- a/time2tex.py
+++ b/time2tex.py
@@ -1,17 +1,200 @@
 #!/bin/python3
 import sys
+from datetime import datetime, timedelta
 
+def fmt_duration(sec):
+  mins = (sec + 59) // 60 # integer divide, round up
+  out = []
 
-if __name__ == "__main__":
-  if len(sys.argv) != 2:
-    print("usage: time2tex <input>")
-    exit(1)
+  if mins == 0:
+    return "--"
+
+  hour = mins // 60
+  if hour > 0:
+    out.append("%02dh" % (hour, ))
+    mins = mins % 60
+
+  out.append("%02dm" % (mins, ))
+
+  return "\\,".join(out)
+
+def fmt_percentage(fac):
+  return f"{{\\footnotesize\\itshape({round(fac * 100)}\\%)}}"
+
+def fmt_member_overview(times):
+  # calculations
+  out = ""
+  members = {}
+  total_time = 0
+  for time in times:
+    if not time["name"] in members:
+      members[time["name"]] = 0
+    members[time["name"]] += time["duration"]
+    total_time += time["duration"]
+
+  # begin table
+  out += r"\begin{table}\centering"
+  out += r"\begin{tabular}{lr@{~}l}\toprule"
+  out += r"\textbf{Member} & \textbf{Tracked} &\\\midrule{}"
+
+  # member overview
+  for name, tracked in members.items():
+    out += f"{name} & {fmt_duration(tracked)} & {fmt_percentage(tracked / total_time)}\\\\"
+  out += r"\midrule{}"
+
+  # sum
+  out += f"&{fmt_duration(total_time)}&\\\\"
+
+  # end table
+  out += r"\bottomrule\end{tabular}"
+  out += r"\caption{Tracked time per group member}\label{tab:time-member}"
+  out += r"\end{table}"
+
+  return out
+
+def fmt_weekly_overview(times):
+  # calculations
+  out = ""
+  weeks = []
+  member_totals = {}
+  total_time = sum(time["duration"] for time in times)
+  members = list(set(time["name"] for time in times))
+  time_start = min(time["date"] for time in times)
+  time_end = max(time["date"] for time in times)
+  week_start = time_start - timedelta(days=time_start.weekday()) # round down to nearest monday
+  week_end = time_end + timedelta(days=7-time_end.weekday())
+
+  week = week_start
+  week_num = 1
+  while week < week_end:
+    week_times = [time for time in times if time["date"] >= week and time["date"] < (week + timedelta(days=7))]
+
+    week_entry = {
+      "num": week_num,
+      "members": {},
+      "total": sum(time["duration"] for time in week_times)
+    }
+
+    for member in members:
+      week_entry["members"][member] = sum(time["duration"] for time in week_times if time["name"] == member)
+
+    weeks.append(week_entry)
+    week_num += 1
+    week += timedelta(days=7)
+  for member in members:
+    member_totals[member] = sum(time["duration"] for time in times if time["name"] == member)
 
+  # begin table
+  out += r"\begin{table}\centering"
+  out += f"\\begin{{tabular}}{{l{'r@{~}l' * len(members)}@{{\\qquad}}r}}\\toprule"
+  out += r"\textbf{\#}"
+  for member in members:
+    out += f"&\\textbf{{{member}}}&"
+  out += r"&\textbf{Subtotal}\\\midrule{}"
+
+  for entry in weeks:
+    out += f"{entry['num']}"
+    for member in members:
+      out += f"&{fmt_duration(entry['members'][member])}&{fmt_percentage(entry['members'][member] / entry['total'])}"
+    out += f"&{fmt_duration(entry['total'])}\\\\"
+
+  out += r"\midrule{}"
+  for member in members:
+    out += f"&{fmt_duration(member_totals[member])}&{fmt_percentage(member_totals[member] / total_time)}"
+  out += f"&{fmt_duration(total_time)}\\\\"
+
+  # end table
+  out += r"\bottomrule\end{tabular}"
+  out += r"\caption{Tracked time per week}\label{tab:time-weekly}"
+  out += r"\end{table}"
+
+  return out
+
+def duration2secs(duration):
+  out = 0 # output (seconds)
+  cur = 0 # current figure (unknown)
+  for c in duration:
+    if c.isdigit():
+      cur = cur * 10 + int(c)
+      continue
+    if c == "h":
+      out += cur * 3600
+      cur = 0
+      continue
+    if c == "m":
+      out += cur * 60
+      cur = 0
+      continue
+    if c == "s":
+      out += cur * 1
+      cur = 0
+      continue
+
+    raise Exception("invalid duration format")
+  if cur != 0: raise Exception("invalid duration format")
+  return out
+
+def line2data(line):
+  # parse fields from input string
+  data = {}
+  next = line.find(':')
+  data["name"] = line[0:next].strip()
+  line = line[next+1:].strip()
+  next = line.find(' ')
+  data["date"] = line[0:next].strip()
+  line = line[next+1:].strip()
+  next = line.find(' ')
+  data["duration"] = line[0:next].strip()
+  line = line[next+1:].strip()
+  data["description"] = line
+
+  # deserialize parsed fields
+  data["name"] = data["name"].title()
+  data["date"] = datetime.strptime(data["date"], '%Y-%m-%d')
+  data["duration"] = duration2secs(data["duration"])
+  data["description"] = [el.strip() for el in data["description"].split("::")]
+
+  return data
+
+def parse(content):
+  # split content at newlines
+  lines = content.split("\n")
+  out = []
+  for i, line in enumerate(lines):
+    line = line.strip()
+    if line.startswith("#"): continue
+    if len(line) == 0: continue
+
+    try: out.append(line2data(line))
+    except Exception as e: raise Exception(f"line {i+1}: {e}")
+  return out
+
+def fmt(times):
+  # TODO: Task overview
+  print(f"""
+\\section{{Overviews}}\n
+\\subsection{{Members}}\n
+{fmt_member_overview(times)}
+\\subsection{{Weekly}}\n
+{fmt_weekly_overview(times)}
+""")
+
+def main():
   input_file = sys.argv[1]
   content = ""
   with open(input_file, "r") as file:
     content = file.read()
-  parsed = parse(content)
 
+  try: parsed = parse(content)
+  except Exception as e:
+    print(f"{input_file}: {e}")
+    exit(1)
+
+  fmt(parsed)
 
+if __name__ == "__main__":
+  if len(sys.argv) != 2:
+    print("usage: time2tex <input>")
+    exit(1)
+  main()
 
diff --git a/timerep.tex b/timerep.tex
index dfde932..7590217 100644
--- a/timerep.tex
+++ b/timerep.tex
@@ -5,7 +5,7 @@
 
 \begin{document}
 
-AHOIHJSAIDHOISAJDSAJDJAOIS
+\input{time.tex}
 
 \end{document}