Skip to content
/ spec Public

Spezifikation für eine offene Schnittstelle für Ratsinformationssysteme

License

Notifications You must be signed in to change notification settings

OParl/spec

Repository files navigation

OParl Wortmarke

Build Status

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 herunterladen

Die Spezifikation kann in verschiedenen Formaten heruntergeladen werden.

Version 1.1

Version 1.0

Aktuelle Entwicklungsversion

Übersetzen

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.

Übersetzungsprojekte

Erstellen der Dokumente

Es gibt zwei Möglichkeiten, die Dokumente zu erstellen: Direkt mit build.py oder über eine Docker-Container.

Mit 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.

Docker

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

Aufbau des Repositories

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 Beispiele
  • scripts/: Enthält Skripte, die u.a. die json-Dateien in Markdown umwandeln und die Beispiele validieren