Initialer Commit

doc/allgemein.md

@@ -0,0 +1,35 @@
+# Konfiguration der Ausgabe (allgemeiner Teil)
+
+Neben der Festlegungen für jede Lerngruppe sind einige allgemeine Festlegungen zu treffen, die am einfachsten zu Beginn der Datei ``input.ini`` beschrieben werden (vgl. Markierung ``Allgemein`` im Beispiel):
+
+```
+[Allgemein]
+
+# Bezeichnung des Schuljahrs (Startjahr angeben - Beispiel: 2025 für 2025/26)
+schuljahr = 2025
+
+# Halbjahr: 1, 2
+halbjahr = 1
+
+# Kalenderwochen des Halbjahres für die Übersichtsseite
+kw_start = 35
+kw_ende = 6
+
+# Startseite: Binde den Stundenplan aus der angegebenen Datei ein (leer: kein Stundenplan)
+stundenplandatei = stundenplan.md
+
+# Trenner der Spalten in den CSV-Eingabedateien
+csvtrenner = ;
+
+# Ausgabegerät: rm2, paperpro, a4
+device = rm2
+```
+
+Die Parameter sind zwar selbsterklärend, werden hier aber dennoch einmal kurz erläutert:
+
+- Als Schuljahr ist das Jahr einzutragen, in dem das Schuljahr beginnt.
+- Für das Halbjahr ist eine 1 oder 2 einzutragen.
+- Für die Übersichtsseite des Habjahrs sind die Kalenderwoche des Beginns und die Kalenderwoche des Endes anzugeben. (Es liegt in der Natur der Sache, dass die beiden Zahlen nicht aufsteigend sein müssen, wenn ein Halbjahr zwei Kalenderjahre umfasst. Das Skript berücksichtigt dies automatisch.)
+- Soll die Startseite des Zieldokuments einen Stundenplan enthalten, so ist dieser im Eingabeverzeichnis als Markdown Dokument anzugeben (vgl. auch nächster Abschnitt). Der Dateiname wird hier festgelegt. Fehlt der Dateiname, so wird der Stundenplan automatisch weggelassen.
+- Für die CSV Dateien kann hier das Symbol zum Trennen der Spalte (voreingestellt Semikolon) bei Bedarf angepasst werden.
+- Zum Schluss kommt die wichtigste Festlegung, das Zielgerät. Hier kann aktuell zwischen ``rm2`` (reMarkable 2), ``paperpro`` (reMarkable Paper Pro) und ``a4`` (DIN A4) gewählt werden.

doc/basiskonfiguration.md

@@ -0,0 +1,23 @@
+# Basiskonfiguration
+
+Die Basiskonfiguration ist in der Datei ``lehrerpdf.ini`` zu finden, die im gleichenVerzeichnis wie das Python-Skript ``lehrerpdf.py`` liegt (vgl. Verzeichnis [src/](../src/)).
+
+Aktuell wird in der Basiskonfiguration nur das Verzeichnis der Eingabedateien des Benutzers festgelegt. Als Standard ist das Unterverzeichnis ``data/`` eingetragen:
+
+```
+[Allgemein]
+
+# Pfad (relativ oder absolut zu den Eingabedateien)
+pfad = data/
+```
+
+Da im Unterverzeichnis ``data/`` (fiktive) Beispieldateien abgelegt sind, die als Ausgangspunkt zum Experimentieren mit dem Tool sicherlich hilfreich sind, empfiehlt es sich nicht die eigenen Dateien in diesem Verzeichnis abzulegen. Stattdessen sollten die Dateien separat abgelegt werden und das zugehörige Verzeichnis in der Basiskonfiguration angepasst werden.
+
+Da ein Update des Tools eine Veränderung der Datei ``lehrerpdf.ini`` wieder überschreiben würde, wird folgende Vorgehensweise empfohlen: Legen Sie im gleichen Verzeichnis die Datei ``mylehrerpdf.ini`` an und passen Sie dort das Eingabeverzeichnis an. Die Datei ``mylehrerpdf.ini`` wird der Datei ``lehrerpdf.ini`` gegenüber durch das Skript bevorzugt.
+
+Sie können wahlweise einen relativen Pfad oder einen absoluten Pfad angeben. Bitte beachten Sie, dass unter Windows die Backslashs \ zum Trennen der Verzeichnisse jeweils doppelt angegeben werden müssen:
+
+```
+/Users/username/Desktop/MeineDaten
+c:\\Dokumente\\Desktop\\MeineDaten
+```

doc/csv.md

@@ -0,0 +1,21 @@
+# CSV-Datei jede Lerngruppe
+
+Für jede Lerngruppe ist eine Namensliste als CSV-Datei im Eingabeverzeichnis abzulegen. Als Spalten sind (in dieser Reihenfolge) der Nachname, der Vorname und das Geburtsdatum der Schülerin bzw. des Schülers anzugeben. 
+
+Evtl. weitere Spalten werden ignoriert. Fehlt das Geburtsdatum, so wird bei der Erzeugung der Ausgabe die Geburtstagsliste automatisch weggelassen. 
+
+Die Kopfzeile mit den Namen der Spalten wird vorausgesetzt und beim Einlesen übersprungen. Fehlt bei Ihrem Dokument die Kopfzeile, so fügen Sie sie bitte nachträglich ein.
+
+Das folgende Listing zeigt einen Ausschnitt aus der Datei [klasse-5a.csv](../src/data/klasse-5a.csv) aus den Beispieldaten.
+
+```csv
+Name;Vorname;Geburtsdatum
+Bauer;Felix;11.6.2014
+Bauer;Lukas;7.2.2014
+Bauer;Marie;6.11.2014
+Bauer;Sophia;8.3.2015
+Fischer;Sophia;17.11.2014
+Hoffmann;Marie;20.4.2015
+```
+
+Der Dateiname ist für die Verarbeitung von zentraler Bedeutung. Zum einen richtet sich danach die Sortierung der Lerngruppen bei der Anordnung im Zieldokument. Zum anderen wird der Name (ohne die Endung .csv) als ID für die Konfiguration der Ausgabe für die zugehörige Lerngruppe benötigt.

doc/erzeugung.md

@@ -0,0 +1,41 @@
+# Erzeugung des PDF-Ausgabedokuments
+
+Zu diesem Zeitpunkt sollte die Konfiguration abgeschlossen sein. Das PDF-Zieldokument kann nun erzeugt werden. Dazu muss das Python-Skript ``lehrerpdf.py``gestartet werden.
+
+
+### Voraussetzungen
+
+Hierzu sind einige Voraussetzungen zu erfüllen:
+
+1. Auf dem eingesetzten Rechner muss [Python](https://www.python.org) auf der Kommandozeile installiert sein. (Das vorliegende Skript wurde unter Python 3.13 entwickelt und getestet. Es sollte aber auch mit älteren Python Versionen lauffähig sein.) Da Python plattformunabhängig ist, ist auch das vorliegende Projekt plattformunabhängig.
+
+2. Die beiden Python-Module ``xhtml2pdf`` und ``markdown`` müssen installiert sein.
+
+```python
+pip3 install xhtml2pdf
+pip3 install markdown
+```
+
+
+### Starten des Skripts
+
+Nun kann das Skript gestartet werden:
+
+```
+python3 lehrerpdf.py
+```
+
+Auf der Konsole werden die Verarbeitungsschritte dokumentiert und auch evtl. Fehler bei der Verarbeitung angezeigt:
+
+```
+Verarbeite das Verzeichnis: data/
+Verarbeite Datei: data/klasse-5a.csv
+Verarbeite Datei: data/klasse-6b.csv
+Verarbeite Datei: data/kurs-if-9.csv
+Verarbeite Datei: data/kurs-if-ef.csv
+Erzeuge PDF-Datei: rm2.pdf
+Fertig!
+```
+
+Die Ausgabedatei, dessen Namen das Zielgerät angibt (im obigen Beispiel ``rm2.pdf``
+ für das Ziel Gerät reMarkable 2), wird dabei im Verzeichnis der Eingabedateien abgelegt.

doc/konfiguration.md

@@ -0,0 +1,24 @@
+# Konfiguration
+
+Die Konfiguration gliedert sich in zwei Teile.
+
+
+### 1. Basiskonfiguration
+
+Die Eingabe des Python-Skripts besteht aus mehreren Dateien, die im nachfolgenden Abschnitt genauer beschrieben werden. Der Pfad zu diesen Eingabedateien wird in der Basiskonfiguration festgelegt.
+
+- [Basiskonfiguration](basiskonfiguration.md) (Datei ``lehrerpdf.ini``)
+
+
+### 2. Konfiguration der PDF-Ausgabe
+
+Für die Erzeugung der PDF-Ausgabe ist pro Lerngruppe eine CSV-Datei mit den Namen der SchülerInnen erforderlich. Zusätzlich können für jede Lerngruppe diverse Parameter zur Darstellung der Ausgabe konfiguriert werden. Einige allgemeine Parameter wie das aktuelle Halbjahr gelten dabei für alle Lerngruppen. Der optionale Stundenplan wird auf der Startseite dargestellt.
+
+- [CSV-Datei jede Lerngruppe](csv.md)
+
+- Konfiguration der Ausgabe (Datei ``input.ini``)
+	- [allgemeiner Teil](allgemein.md)
+	- [Teil für jede Lerngruppe](lerngruppe.md)
+	
+- [Stundenplan-Datei](stundenplan.md)
+

doc/lerngruppe.md

@@ -0,0 +1,46 @@
+# Konfiguration der Ausgabe (für jede Lerngruppe)
+
+In der Datei ``input.ini`` im Eingabeverzeichnis wird für neben einigen allgemeinen Festlegungen für jede Lerngruppe die gewünschte Ausgabe konfiguriert. Dabei wird die ID aus dem Dateinamen als Bereichsmarkierung (vgl. ``klasse-5a`` im Beispiel) benötigt.
+
+```python
+[klasse-5a]
+
+# Bezeichnung der Lerngruppe
+bezeichnung = Mathe 5a
+
+# Kurzbezeichnung der Lerngruppe
+kurzbezeichnung = Mathe 5a
+
+# Anzahl Arbeiten oder Klausuren: 0, 1, 2, ... (0=keine Arbeiten/Klausuren)
+schriftlich_anzahl = 3
+
+# Bezeichnung Arbeit oder Klausur o.ä.
+schriftlich_bez = Arbeit
+
+# Anzahl der Quartale bei der SoMi-Erfassung: 1 (gemeinsames) oder 2 (getrennte)
+somi_quartale = 2
+
+# Anzahl der Zeilen pro Schüler in einem SoMi-Bogen: 1, 2, ...
+somi_zeilen = 2
+
+# Spalte für Halbjahresnote im 2. Hj. in Übersicht einblenden: ja, nein
+halbjahresnote = ja
+
+# Anzahl der Zeilen pro Schüler in einem HA-Bogen: 0, 1, 2, ... (0=kein HA-Bogen)
+ha_zeilen = 1
+
+# Anzahl der Seiten mit Checkliste: 1, 2, ...
+checkliste_seiten = 2
+```
+
+Die Parameter sind zwar selbsterklärend, werden hier aber dennoch einmal kurz erläutert:
+
+- Die Bezeichnung der Lerngruppe wird als Überschrift überall dort verwendet, wo genügend Platz zur Verfügung steht.
+- Ist nur wenig Platz vorhanden (z.B. im Stundenplan oder in der Navigationsleiste), kommt die Kurzbeschreibung der Lerngruppe zum Einsatz.
+- Die Anzahl der schriftlichen Lernerfolgskontrollen gibt an, wie viele Korrekturbögen erzeugt werden. Die Anzahl 0 sorgt dafür, dass diese automatisch weggelassen werden.
+- Die Bezeichnung der Lernerfolgskontrolle passt sich dem Sprachgebrauch an, z.B. Arbeit oder Kursarbeit oder Klausur.
+- Bei der Erfassung von Notizen zur Sonstigen Mitarbeit (SoMi) wird angegeben, ob eine durchlaufende Liste für beide Quartale oder zwei getrennte Listen für die beiden Quartale generiert werden sollen.
+- Zudem können eine oder mehrere Zeilen pro SchülerIn erzeugt werden.
+- In der Notenübersicht des zweiten Halbjahres kann optional eine Spalte für die Note des ersten Halbjahres angelegt werden.
+- Bei der Erfassung von Hausaufgaben bzw. deren Nichterledigung können eine oder mehrere Zeilen pro SchülerIn angelegt werden. Die Anzahl 0 sorgt dafür, dass Hausaufgabenlisten ganz weggelassen werden.
+- Abschließend kann die Anzahl der Checklisten für diese Lerngruppe festgelegt werden. Hier empfiehlt es sich lieber zu viele Listen zu konfigurieren, da das Einfügen zusätzlicher Seiten die Verweise (Links) im PDF Zieldokument unbrauchbar macht.

doc/stundenplan.md

@@ -0,0 +1,26 @@
+# Stundenplan
+
+Wird ein Stundenplan auf der Startseite gewünscht, so wird die im allgemeinen Teil der Ausgabekonfiguration angegebene Markdown-Datei eingelesen und aufbereitet.
+
+Die Beispieldatei ``stundenplan.md`` kann dabei als Ausgangspunkt verwendet werden:
+
+```md
+
+|    St.   | Montag       | Dienstag     | Mittwoch     | Donnerstag   | Freitag      |
+| :------: | :----------: | :----------: | :----------: | :----------: | :----------: |
+| 1.<br>2. | [klasse-5a]  | [klasse-6b]  |              |              |              |
+| 3.<br>4. | [klasse-6b]  | [kurs-if-ef] | [klasse-5a]  |              |              |
+| 5.<br>6. | [kurs-if-9]  |              | [kurs-if-ef] |              |              |
+|    7.    |              |              |              |              |              |
+| 8.<br>9. |              | [kurs-if-9]  |              |              |              | 
+```
+
+Dabei ist zu beachten:
+
+- Durch ``<br>`` kann ein Zeilenumbruch in einer Zelle erzwungen werden kann.
+- Die Spalten der Tabelle werden durch ``|`` voneinander abgetrennt.
+- Wird die ID einer Lerngruppe in eckige Klammern gesetzt (z.B. ``[klasse-5a]``), so wird die Aufbereitung automatisch einen Verweis auf die Seite generieren, auf der die Informationen zur zugehörigen Lerngruppe beginnen.
+- Die Aufteilung der sechs Spalten (Stunde, Montag, ...) sollte möglichst beibehalten werden. Bei der Aufbereitung wird die erste Spalte enger dargestellt, alle übrigen Spalten werden gleich breit formatiert.
+
+Fehlt die Datei für den Stundenplan (bewusst oder versehentlich), so wird automatisch auf die Berücksichtigung eines Stundenplans auf der Startseite verzichtet.
+