In diesem Repository wird die Spezifikation zum OParl-Standard gepflegt.
Der OParl-Standard definiert eine einheitliche Schnittstelle zum Abruf von maschinenlesbaren Informationen aus Ratsinformationssystemen.
Änderungsvorschläge können über Pull Requests eingebracht werden. Hilfe im Umgang mit GitHub findest du hier.
Die Spezifikation kann in verschiedenen Formaten heruntergeladen werden.
Da OParl international einzigartig ist würden wir die Spezifikation gerne auf Englisch oder auch in weitere Sprachen übersetzen. Dazu benötigen wir Helfer mit guten Sprachkenntnissen, die uns bei der Übersetzung helfen.
Zum Übersetzen werden, wie auch bei der sonstigen Textbearbeitung keine technischen Fachkenntnisse benötigt. Sowohl die OParl-Spezifikation (dieses Repository), als auch die Entwicklerwebseite und liboparl werden über Transifex lokalisiert. Um daran mitzuarbeiten wird nur ein Account benötigt, dann kann den verschiedenen Projekten über die Projektliste beigetreten werden.
Vorang bei der Übersetzung hat vor allem die Spezifikation an sich, da alles weitere von der mehrsprachigen Verfügbarkeit des Spezifikationstextes abhängt.
Der Übersetzungsfortschritt wird in regelmäßigen Abständen von Transifex wieder zurück in das Repository übertragen, dies passiert derzeit von Hand und kann bei Bedarf z.B. durch ein Ticket hier auf GitHub angefragt werden.
Es gibt zwei Möglichkeiten, die Dokumente zu erstellen: Direkt mit build.py
oder über eine Docker-Container.
build.py
Für das Erstellen der Spezifikation ist folgende Software erforderlich:
Zur Erstellung der Archive außerdem:
Unter Ubuntu können alle benötigten Pakete mit einem Befehl installiert werden:
sudo apt install etoolbox ghostscript lmodern graphviz make pandoc pandoc-citeproc texlive-fonts-recommended \
texlive-generic-recommended texlive-humanities texlive-lang-german texlive-latex-recommended texlive-luatex \
texlive-xetex librsvg2-bin python3 python3-yaml
Das eigentliche Bauen der Dokumente ist dann nur noch ein einziger Befehl:
python3 build.py
Die fertigen Dokumente finden sich dann sich in build/
.
Ein einzelnes Ausgabeformat kann mit python3 build.py <format>
erstellt werden, mit python3 build.py archives
können
Archive mit allen Ausgabeformaten gepackt werden. Dazu müssen allerdings
die enstprechenden Archivierungsprogramme vorhanden sein.
Für den geneigten Containerfreund gibt es ein Container, der alle Tools enthält. Auch hier ein Ausgabeformat an den Aufruf angehängt werden kann:
docker run -u $UID:$GID --rm -v $(pwd):$(pwd) -w $(pwd) oparl/specbuilder:latest
Die Dateien, aus denen die Spezifikation erstellt wird, sind auf mehrere Ordner aufgeteilt:
src/
: Enthält den gesamten Fließtext als Markdown-Dateien.schema/
: Enthält das Datenmodell, d.h. den Aufbau der von OParl genutzten json-Objekte, als json-Dateien in einem
auf JSON Schema aufbauenden Format.examples/
: Die im Text eingebundenen Beispielescripts/
: Enthält Skripte, die u.a. die json-Dateien in Markdown umwandeln und die Beispiele validieren