wegen/sosci2word/_README.txt

sosci2word: Import eines Fragebogens
====================================
:Date: Mai 2023

_Import der Fragebogen-Definition von SoSci Survey in ein MS.Word-Dokument_

In diesem Sommer führt Daniela Zutavern (Nachbarin aus dem 3.Stock) für ihre Bachelor-Arbeit
eine Umfrage durch zur psychischen Belastung von Physiotherapeuten am Arbeitsplatz. Dieser
wird als Online-Fragebogen auf der Plattform https://www.soscisurvey.de/en/index[SoSci Survey]
bereitgestellt -- muß dann aber für die Bachelor-Arbeit im Anhang der dokumentiert werden; da
direkte Screenshots oder Konvertierungen des Online-Fragebogens (via PDF) problematisch sind,
soll hier ein einfaches Python-Skript entwickelt werden, mit dem sich ein XML-Export aus der
Fragebogen-Plattform einlesen und daraus eine Darstellung in ein Wort-Dokument schreiben läßt.
Grundlage ist die Library https://pypi.org/project/python-docx/[Python-docx].

Konzept
-------
Der Fragebogen liegt in strukturierter Form als *XML-Dokument* vor, und Inhalte können daher
leicht mit Python eingelesen werden. Das *Python-docx*-Modul macht ein Word-Dokument neuen
OOXML-Format zugängich als eine Folge von Absätzen, und zwar sowohl lesend, als auch schreibend.
Als Vorbereitung kann im Word-Dokument bereits ein geeignetes Layout angelegt werden, so daß
Inhalte als eine Folge von Absätzen eingefügt werden, und jeweils mit einer fest vereinbarten
Formatvorlage verknüpft. Idealerweise sollten die Auswahlmöglichkeiten der einzelnen Items
jeweils in einer eingebetteten Tabelle dargestellt werden -- sofern das Python-Modul dies
zuläßt. Insgesamt handelt es sich um eine Einmal-Arbeit, die nicht zur Veröffentlichung
vorgesehen ist; eine 80%-Lösung ist bereits mehr als genug.

Format des SoSci-XML
~~~~~~~~~~~~~~~~~~~~

[red]#TODO#

Format der Word-Datei
~~~~~~~~~~~~~~~~~~~~~
Rohformat:: ein Zip-komprimiertes Archiv mit Ressourcen und XML-Dokumenten
+
besonders relevant:
+
- 'document.xml' : eigentlicher Inhalt des Dokuments
- 'style.xml' : Platzhalter bzw konkrete Style-Definitionen (incl. Name-ID)

logisches Format:: Metadaten + verschachtelte Sequenz von _Block_- und _Inline_-Elementen
+
- Block-Elemente sind: Paragraph, Table, Image, Drawing
- Inline-Elemente sind: Run (=Text-Schnipsel mit einheitlichem Format), Table, Image, Frame
+
Sowohl Block-, alsauch Inline-Elemente sind direkt mit einem _Style_ ausgezeichnet.
Dieser kann sowohl _direkte Formatierung_ umfassen, aber auch auf einen _definierten Style_
aus dem Stylesheet (``Formatvorlage'') per Name-ID verweisen.

[yellow-background]#WIP#


Implementierung
---------------
Grundsätzlich ist eine einfache Implementierung möglich, indem das SoSci-XML gelesen, interpretiert
und sofort in Word-Content transformiert wird. Es ergeben sich aber im Detail einige Schwierigkeiten

- die Libarary python-docx kann zwar Wort-Format vollständig lesen und reproduzieren,
  aber nur wenige Basis-Features sind direkt über das API zur Manipulation zugänglich
- zudem bietet python-docx nahezu keine Möglichkeit, ein bestehendes Dokument unbekannter Struktur
  zu analysieren.
- wir brauchen relativ komplexe Tabellen-Formatierungen, die nur _ansatzweise dokumentiert_ sind.
- der Fragebogen ist im SoSci-XML nicht sauber strukturell definiert, sondern nur als ein Template
  zur Darstellung. Lediglich die einzelnen Fragen sind als strukturierte Elemente definiert
- die Referenzierung aus dem Darstellungs-Template erfolgt über interne IDs, welche aber in der
  strukturierten Definition lediglich kontextuell aufgebaut werden. Unser Code muß hier interpolieren.
- das Darstellungs-Template ist ein verschachtelt eingebettetes weiteres XML-Dokument und zudem
  auch noch XML-quoted.
- wir haben mehrere Item-Typen, mit einer jeweils anderen Datenstruktur => Polymorphismus

NOTE: es ist mit den gegebenen Mitteln nicht möglich, das Tabellen-Styling zu steuern.
      Man könnte der ganzen Tabelle einen Style zuweisen, und man kann den Parahgraphs
      in jeder Zelle einen Style zuweisen (oder sie manuell formatieren). Jedoch
      kein Zugriff auf Rahmenarten, Cell-Alignment, Shading

Verarbeitungs-Schema
~~~~~~~~~~~~~~~~~~~~
[yellow-background]#(dies ist der Plan zur Implementierung)#:
Fragebogen-Definitionen können mit https://docs.python.org/3/library/xml.etree.elementtree.html[Elementtree]
aus der Python-Standard-Library gelesen werden, das Word-Dokument mit
https://python-docx.readthedocs.io/en/latest/index.html[python-docx(Documentation)].
Die Verarbeitung untergliedert sich in drei Phasen:

1. SoSci-Definitionen einlesen
   +
   * alle <question>-Elemente aufsammeln
   * per Kontext die vollständige ID ablegen
   * daraus ein polymorphes Python-Objekt generieren
   * dies in eine Map-keyed-by-ID ablegen
   
2. SoSci-Questionaire verarbeiten
   +
   * das nested XML extrahieren und parsen
   * die Seitenstruktur navigieren
   * jedes konkret referenzierte Block-Element aus der Map holen
   * in eine mehrstufige Liste ablegen

3. Word-Content generieren
   +
   * das Word-Dokument öffnen
   * die mehrstufige Liste traversieren
   * auf jedem Block-Element eine polymorphe render(wordDocument)-Funktion aufrufen
   * Word-Dokument unter neuem Namen speichern


[yellow-background]#WIP#