From bd87b3df46b8ae9cb650c7a1cf6b8038de279e9d Mon Sep 17 00:00:00 2001
From: Michael Stangl <m.stangl@schoenenberger.de>
Date: Thu, 9 Jul 2026 11:09:32 +0200
Subject: [PATCH] Add doc/dateiformate.md file-format reference

Documents tische.ini, bestellung.xml, and the output file formats
using real examples from work/test1 and work/test2.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 doc/dateiformate.md | 205 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 205 insertions(+)
 create mode 100644 doc/dateiformate.md

diff --git a/doc/dateiformate.md b/doc/dateiformate.md
new file mode 100644
index 0000000..90376dc
--- /dev/null
+++ b/doc/dateiformate.md
@@ -0,0 +1,205 @@
+# Dateiformate
+
+Referenz fuer die Eingabe- und Ausgabedateien eines `platz`-Laufs, mit Beispielen aus
+`work/test1/` und `work/test2/`.
+
+## Tischaufstellung: `tische.ini`
+
+Ein INI-File mit einer Sektion pro Tisch. Sektionsname ist die Tisch-Id.
+
+| Schluessel      | Bedeutung                                              |
+|-----------------|---------------------------------------------------------|
+| `Nummer`        | Anzeigenummer des Tisches                              |
+| `Hof`           | Hof/Bereich, in dem der Tisch steht                    |
+| `Plaetze`       | Anzahl der Sitzplaetze am Tisch                        |
+| `Nachbarliste`  | Python-Liste der Ids benachbarter Tische               |
+| `Koordinaten`   | `(x,y)`-Tupel fuer die Position des Tisches             |
+
+Beispiel aus `work/test2/tische.ini` (eine Reihe von fuenf Tischen, jeder mit seinen
+direkten Nachbarn verkettet):
+
+```ini
+[1]
+Nummer=1
+Hof=1
+Plaetze=3
+Nachbarliste=[2]
+Koordinaten=(1,1)
+
+[2]
+Nummer=2
+Hof=1
+Plaetze=5
+Nachbarliste=[1,3]
+Koordinaten=(2,1)
+
+[3]
+Nummer=3
+Hof=1
+Plaetze=3
+Nachbarliste=[2,4]
+Koordinaten=(3,1)
+
+[4]
+Nummer=4
+Hof=1
+Plaetze=4
+Nachbarliste=[3,5]
+Koordinaten=(4,1)
+
+[5]
+Nummer=5
+Hof=1
+Plaetze=4
+Nachbarliste=[4]
+Koordinaten=(5,1)
+```
+
+Werte wie `Nachbarliste` und `Koordinaten` werden mit `eval()` geladen (siehe
+`Tische.laden()` in `libs/Strukturdaten.py`) — es steht also echter Python-Ausdruckscode im
+File, keine reine INI-Syntax.
+
+## Gaesteliste: `bestellung.xml`
+
+Ein `<Bestellung>` mit mehreren `<Gruppe>`-Bloecken. Jede Gruppe enthaelt:
+
+- ein oder mehrere `<Person>`-Elemente mit `<Vorname>`, `<Nachname>` und optionalem
+  `<Titel>`
+- optional `<Anzahl>N</Anzahl>`, um die zuletzt beschriebene Person zu einer Sammelbuchung
+  von `N` (anonymen/gleichnamigen) Personen zu vervielfaeltigen
+- optional `<Tisch>Id</Tisch>`, um die Gruppe als VIP-Gruppe fest an den angegebenen Tisch
+  zu binden (sie wird dann **nicht** vom GA platziert)
+
+XML-Kommentare (`<!-- ... -->`) sind erlaubt und werden beim Parsen ignoriert.
+
+Minimalbeispiel mit Sammelbuchungen, aus `work/test1/bestellung.xml`:
+
+```xml
+<Bestellung>
+
+	<Gruppe>	
+		<Person>	
+			<Vorname>A</Vorname>
+			<Nachname>AA</Nachname>
+			<Titel>Dipl. Ing.</Titel>
+		</Person>	
+		<Anzahl>10</Anzahl>	
+	</Gruppe>
+
+	<Gruppe>	
+		<Person>	
+			<Vorname>B</Vorname>
+			<Nachname>BB</Nachname>
+			<Titel>Prof.</Titel>
+		</Person>	
+		<Anzahl>4</Anzahl>	
+	</Gruppe>
+
+	<Gruppe>	
+		<Person>	
+			<Vorname>C</Vorname>
+			<Nachname>CC</Nachname>
+			<Titel>Dr.</Titel>
+		</Person>	
+		<Anzahl>5</Anzahl>	
+	</Gruppe>
+
+</Bestellung>
+```
+
+Umfangreicheres Beispiel mit benannten Personen und einer VIP-Gruppe, aus
+`work/test2/bestellung.xml`:
+
+```xml
+<Bestellung>
+
+	<!--  einfache Gruppe aus drei Personen
+	      mit festem Wunsch fuer einen Tisch-->
+	<Gruppe>	
+		<Person>	
+			<Vorname>Michael</Vorname>
+			<Nachname>Stangl</Nachname>
+			<Titel>Dipl. Ing.</Titel>
+		</Person>	
+		<Person>	
+			<Vorname>Magnus</Vorname>
+			<Nachname>Mueller</Nachname>
+			<Titel>Professor</Titel>
+		</Person>	
+		<Person>	
+			<Vorname>Bernd Robert</Vorname>
+			<Nachname>Hoehn</Nachname>
+			<Titel>Professor</Titel>
+		</Person>	
+		<Tisch>1</Tisch>
+	</Gruppe>
+
+	<!--  einfache Gruppe aus zwei  Personen -->
+	<Gruppe>
+		<Person>	
+			<Vorname>Heinz</Vorname>
+			<Nachname>Bruegge</Nachname>
+		</Person>	
+		<Person>	
+			<Vorname>Hubert</Vorname>
+			<Nachname>K</Nachname>
+		</Person>	
+	</Gruppe>
+
+	<!--Gruppe aus drei anonymen Personen-->
+	<Gruppe>
+		<Person>	
+			<Vorname>Bestelli</Vorname>
+			<Nachname>Bloedkopf</Nachname>
+		</Person>	
+		<Anzahl>3</Anzahl>	
+	</Gruppe>
+
+</Bestellung>
+```
+
+Die erste Gruppe hier ist per `<Tisch>1</Tisch>` fest an Tisch 1 gebunden (VIP-Gruppe); die
+letzte Gruppe erzeugt ueber `<Anzahl>3</Anzahl>` drei gleichnamige "Bestelli Bloedkopf"
+Buchungen.
+
+## Ausgabe: `TischePersonen.txt`
+
+Eine Sektion pro Tisch (`[Tischid]`), darunter eine Zeile pro Sitzplatz:
+
+```
+[1]
+Dipl. Ing. A AA = Hof 1, Tisch 1, Nummer 1
+Dipl. Ing. A AA = Hof 1, Tisch 1, Nummer 2
+Dipl. Ing. A AA = Hof 1, Tisch 1, Nummer 3
+Dipl. Ing. A AA = Hof 1, Tisch 1, Nummer 4
+Dipl. Ing. A AA = Hof 1, Tisch 1, Nummer 5
+
+[2]
+Dipl. Ing. A AA = Hof 1, Tisch 2, Nummer 1
+...
+```
+
+Format je Zeile: `Titel Vorname Nachname = Hof <Hof>, Tisch <Nummer>, Nummer <Platznummer>`.
+
+## Ausgabe: `PersonenTische.csv`
+
+Dieselben Sitzplatzdaten, aber eine Zeile pro Person statt pro Tisch, alphabetisch nach
+Nachname sortiert:
+
+```
+AA, A, Dipl. Ing. = Hof 1, Tisch 1, Nummer 2
+AA, A, Dipl. Ing. = Hof 1, Tisch 1, Nummer 3
+...
+BB, B, Prof. = Hof 1, Tisch 3, Nummer 2
+...
+CC, C, Dr. = Hof 1, Tisch 4, Nummer 2
+...
+```
+
+Format je Zeile: `Nachname, Vorname, Titel = Hof <Hof>, Tisch <Nummer>, Nummer <Platznummer>`.
+
+## Zyklus- und Strafenkonfiguration
+
+Siehe `cfg/zyklus.cfg` und `cfg/strafen.cfg` sowie die Beschreibung in `CLAUDE.md` /
+`README.md` fuer das Format der GA-Ablaufsteuerung (`Abfolge`/`Anzahl`) und der
+Strafpunkte-Tabelle.