readme bijgewerkt voor verdwaalde zielen

1 files changed, 91 insertions, 3 deletions

diff --git a/readme.md b/readme.md
index df907a5..cf32813 100644
--- a/readme.md
+++ b/readme.md
@@ -1,5 +1,93 @@
-# huiswerk dab
+# databases huiswerk
 
-ik geef hier de opdrachten vrij omdat het er naar mijn mening te veel zijn.
-gelieve dit als naslagwerk te gebruiken.
+ik geef hier de opdrachten vrij omdat het er naar [mijn
+mening](#een-stukje-feedback-voor-de-opleiding) te veel zijn. gelieve dit als
+naslagwerk te gebruiken.
+
+hier is nog wat documentatie omdat deze repo iets vlug is gegroeid de afgelopen
+2 weken.
+
+## gebruikte tools en bestandsstructuur
+
+> (de open vragen van de huiswerkopdrachten had ik gemaakt voor dat ik dit
+> zooitje had ingesteld, dus deze bevatten gekopiëerde fragmenten uit de mysql
+> interactieve cli)
+
+`q*.sql` zijn query's, `t*.sql` zijn tests (hiervan wordt de output opgeslagen
+in `t*.md`). `b*.sql` wordt zelden gebruikt maar betekent dat de query nog
+aangevuld wordt om naar een `q*.sql` te gaan (b staat voor base).
+
+in de sfeer van geoptimaliseerde luiheid is bijna alle documentformatting
+geautomatiseerd. de practica's en eindopdracht gebruiken m4 om de sql query's
+en hun resultaten in markdown bestanden te zetten. een makefile zorgt er voor
+dat alle sql query's uitgevoerd worden in volgorde, dit zijn de bestanden die
+er uit zien als `q*.sql`.
+
+hier is een lijstje macro's die gedefinieerd worden uit common.m4 (`n` staat
+voor een willekeurig getal):
+
+|aanroep|beschrijving|
+|-|-|
+|`q_norm(n)`|maakt een opdracht hoofdstuk met code block die de inhoud van q\*.sql bevat.|
+|`q_with_output(n)`|doet het zelfde als `q_norm`, maar met de inhoud van t\*.sql, met daaronder de output van de query als HTML tabel.|
+|`q_with_test(n)`|doet het zelfde als `q_norm` met daaronder `q_with_output`, maar zonder gedupliceerde opdracht header|
+|`include_sql(file)`|maakt een code block met de inhoud van `file`|
+
+een map kan ook een bestand genaamd `reset.sql` bevatten, deze wordt vóór alle
+q\*.sql query's uitgevoerd, dus hier staan meestal `drop table` statements in
+om de database te \*resetten\*. de makefile gebruikt de standaard mysql
+command-line client, en eventuele opties zoals een alternatieve gebruikersnaam
+en/of wachtwoord kunnen in common.mk aangepast worden. de standaardconfiguratie
+gaat uit van een database die met dezelfde gebruikersnaam als de gebruiker
+waarmee je `make` draait toeganklijk is, en zonder wachtwoord.
+
+## de eindopdracht
+
+de eindopdracht heb ik in een middag geschreven, in python, met scripts in
+nodejs omdat ik deze af aan het raffelen was. deze code is niet gemaakt om
+onderhoudbaar te zijn, maar als het werkt voor de assessment is het goed
+genoeg. u zijt gewaarschuwd.
+
+voor de rest is dit een standaard python project met een virtual environment,
+dus setup ziet er zo uit:
+
+```shell
+# (in eindopdracht submap)
+python3 -m venv venv
+source venv/bin/activate
+pip3 install -r requirements.txt
+```
+
+de afbeeldingen van de merken zitten niet in deze repository omdat ik geen
+auteursrechtelijke rechten voor ze heb. in de eindopdracht submap zit een losse
+makefile die een imgs.sql query maakt, deze voegt links naar de (verwachte)
+bestanden in de eindopdracht/img/ map. deze query moet handmatig uitgevoerd
+worden. een lijst met bestandsnamen van deze afbeeldingen staat wel in de
+makefile.
+
+## over de makefiles
+
+`common.mk` bevat instructies om een m4 template document te renderen en sql
+query's uit te voeren. als je markdown output voldoende vindt is dit genoeg.
+deze makefile verwacht dat de `TARGET` variabele ingesteld is op de basename
+van je m4 template.
+
+`pdf.mk` bevat instructies om de markdown output te renderen als pdf met behulp
+van `latexmk`. ook wordt inkscape op de achtergrond gebruikt om svg diagrammen
+om te zetten naar pdf's, zodat latex deze kan lezen. om deze makefile te
+gebruiken moet je uiteraard ook een werkende latex distributie geïnstalleerd
+hebben. ook wordt `pandoc` gebruikt om de markdown om te zetten naar een .tex
+bestand. deze makefile verwacht dat de `MD2LATEX` variabele is ingesteld op het
+pad naar het `md2latex` script in de rootmap van deze repo.
+
+## een stukje feedback voor de opleiding
+
+*en* een waslijst huiswerkopdrachten, *en* 2 practica's, *en* een eindopdracht,
+*en* een tentamen is te veel werk voor 2 studiepunten. hier is een lijstje
+suggesties:
+
+- schrap het tentamen net als hoe de practica's werkte bij microcontrollers 2
+- minder huiswerkopdrachten geven
+- de practica's aanpassen zodat het niet vermomde huiswerkopdrachten zijn
+- de eindopdracht laten vervallen