From 06c95e45d258ff2d7a441ef6042612672ab95374 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sun, 9 Oct 2022 21:41:52 +0200 Subject: readme bijgewerkt voor verdwaalde zielen --- readme.md | 94 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file 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 -- cgit v1.2.3