User:RailML Coord Documentation/Autodoku

🗒️ This page is mirrored from page RailML3_Wiki:Autodoku in The railML® 3 wiki.

Unterstützung der railML^®-Dokumentation durch Skripte

Motivation

Es ist beabsichtigt, die Wiki-Dokumentation von railML^®3 teilweise zu automatisieren. Informationen, die aus dem Schema ableitbar sind, sollen ausgewertet und automatisch in das Wiki eingepflegt werden. Dies betrifft zwei Phasen:

1. Erstellung eines Grundstockes: Für jedes railML^®-Element soll eine Seite mit den Eckdaten erstellt werden, die händisch als Text weitergepflegt wird. Hierbei wird die Seite mit einem Vorlagenaufruf analog zu Template:elementDocu gefüllt, mit den Parameterwerten, die das jeweilige Element repräsentieren. Dazu dient User:Ferri Leberl/Template:Grundstock. Sie können als Handseiten bezeichnet werden.
2. Laufende Präsentation des aktuellen Standes: In jede Elementseite soll eine Vorlage eingebunden sein, die in Tabellenform die Eckdaten der jeweils aktuellen Version darlegt. Damit auch Benutzer älterer Versionen diese Informationen zur Verfügung haben, sollen diese Seiten für jede Version einzeln bestehen bleiben. Als Namensschema ist <subschema><Elementname>/<Version> gedacht. Zu Seite CO:railml gäbe es dann eine Seite CO:railml/3.1, CO:railml/3.2 etc. Diese Seiten sind nicht zur händischen Bearbeitung gedacht, wir nennen sie Roboterseiten. Sie rufen eine Vorlage wie User:Ferri Leberl/Template:Schemaexport auf. Die Darstellung der Daten soll ergo erst im Wiki erfolgen. Es ist vorgesehen, die aktuelle version in die Handseite einzubinden und die älteren Versionen über ein Navi ansteuerbar zu machen – doch das geschieht dann wikiseitig über die Vorlage.

Wie wir es uns vorstellen, können Sie unter https://wikitest.railml.org sehen.

Aus dem Schema ableitbare daten sind:

• Elementname
• Multiplicity
• Dokumentation (das zum Element gehörige <documentation>-Tag)
• Subschema
• Parent(s) (identische Namen sollen konsolidiert werden)
• Children
• Attribute
• Sind Attribute verpflichtend?
• Attributdokumentationen (das zum Attribut gehörige <documentation>-Tag)
• railML^®-Version
• Gibt es ein gleichnamiges railML^®-2-Attribut? — verworfen

Workflow

Für eine Vereinfachung des Workflows wären wir dankbar.

Derzeit stellen wir uns folgenden Workflow vor:

Ausgangspunkt ist das Schema in Form von .xsd-Dateien. Dieses wird entchoicet (mehr dazu später). Aus dem entchoiceten Schema wird mit Eclipse eine Beispiel-XML-Datei generiert, die, der Idee nach, sämtliche Elemente und Attribute enthalten soll. Die Datei wird mit xsl-Skript und einem Bash-Skript ausgewertet bzw. nachbereitet, sodass am Ende eine Meediawiki-Importdatei vorhanden ist, die für jedes Element eine Seite enthält – je nach Betriebsmodus mit der Vorlage Grundstock im Artikelraum oder mit der Vorlage Schemaexport im Versions-Unterraum.

Informationen, die im Beispiel-XML nicht enthalten sind, sind

• Multiplicity
• Elementdoku
• Pflichtattribut?
• Attributdoku

Die Überlegung war, diese Informationen mittels xs3p zu bekommen.

Wir könnten uns vorstellen, dass die Auswertung auch direkt über xs3p möglich wäre, ohne den fragilen Zwischenschritt eine vor- und nachbearbeiteten Beispieldatei.

Entchioceung

Da das Schema an einigen Stellen Choices enthält kann Eclipse keine konforme Beispieldatei erzeugen, die sämtliche Elemente enthält. Darum wird mit dem Bashskript xsd_sequence sämtliche choice-Tags durch sequence-Tags ersetzt. Das ist zugegeben ein schmutziger Trick, da das entstehende Schema en anderes als das ursprüngliche ist, doch er erfüllt den Zweck.

Die Vorgangsweise ist, Kopien der .xsd in einem neuen Verzeichnis zu erstellen. Unter Linux kann man in der Bash, wenn man im Verzeichnis der zu ändernden XSDs ist, mit dem Befehl for file in *.xsd; do xsd_sequence "$file"; done alle Dateien auf einmal putzen.

Da es Elemente mit einer Mindesthäufigkeit >1 geben kann, muss analog die Multiplicity manipuliert werden, damit die Beispieldatei nicht mehrereInstanzen desselben Elementes enthalten kann.

Eclipse

In Eclipse soll eine Beispiel-XML-Datei erzeugt werden. Dies gliedert sich in zwei Phasen:

Import

File→New→Dynamic Web Project→Project name eintragen und Finish

File→Import→File System→From Directory eintragen/suchen und im betreffenden Verzeichnis Select all und Finish

Generieren

Im Projekt die Masterdatei ansteuern→sekundärer Mausklick→Generate→XML File→Namen der Beispieldatei wählen und Next→Root element: railml; create optional attributes; create optional elements; Elementtiefe nicht limitieren; Finish

für das aktuelle railML^®2.3 stellt sich bei mir das Ergebnis railML.xml ein.

Auswertung

Die Auswertung erfolgte mit einem XSL-Skript, das ich vorerst nur code.xsl nenne:

saxonb-xslt railML.xml code.xsl>liste_rml23

Die Ergebnisdatei musste noch mit dem Bashskript tabkopf geputzt werden:

tabkopf liste_rml23

Ergebnis war eine tabulatorgetrennte Liste (.tsv) mit, in unserem Beispiel, dem Dateinamen liste_rml23, deren Kopfzeile die Tabelle recht gut erklärt:

Name↹Kommentar↹Subschema↹Parent↹Children↹Attribute↹Attributkommentare↹Pflichtelement↹Pflichtattribute

Die Spalten Children, Attribute, Attributkommentare und Pflichtattribute können mehrere Einträge enthalten (wenn ein Element mehrere Kinder und/oder mehrere Attribute hat). Diese Einträge werden durch Strichpunkte (;) getrennt. Wenn in einem späteren Schritt identisch lautende Elemente konsolidiert werden, können auch die Spalten Parent und Subschema verschiedene Einträge erhalten, vielleicht sogar alle außer Name (wäre zu klären).

Diese Liste wertete ich mit einem GNU-Skript aus, wobei dieses Skript so beschaffen ist, dass es sich an der Benennung der Spalten in der Kopfzeile orientiert (hier toleriert es keine Fehler), während und die Reihenfolge der Spalten gleichgültig ist.

DI Wunsch generierte die XML-Datei, die ins Wiki importiert werden soll, direkt mit XSL und reicherte sie mittels xs3p an.

GNU R: Erstellung der Wikiseiten

🗒️ Dieser Teil wurde verworfen, da die Importdatei direkt mit XSL (und xs3p) erzeugt werden kann.

Im GNU-R-Skript sollen nun folgende Schritte geschehen:

• Konsolidierung mehrfacher Elementnamen (noch nicht implementiert)
• Ggf konsolidierung der zweiten Liste mit den Doku-Tags (nicht implementiert)
• Ggf Zusammenführung der beiden Listen (micht implementiert)
• Ableitung der in Mediawiki importfähigen Dateien, die für jedes Element eine Seite mit den Eckdaten haben

Das Skript trägt derzeit den Namen c_roboterseiten.R. Dato muss im Skript folgendes hinterlegt werden:

• Der Name der Importdatei muss dato im Skript unter der variablen import hinterlegt werden.
• Der Name der Exportdatei muss in der Variable datei hinterlegt werden
• Je nachdem, ob die Variable modus den Wert 0 oder 1 trägt, werden die Seiten entweder für den Grundstock (Handseiten) oder für die aktuelle Einbindung (Roboterseiten) angelegt.

Mit

• modus<-0
• import<-"liste_rml23"
• datei<-"dump2wiki.xml"

erhalte ich durch den Aufruf R CMD BATCH c_roboterseiten.R die Datei dump2wiki.xml.

Konsolidierung

Eine Skriptvariante, die die Elementnamen konsolidiert (also je Elementname nur eine Seite liefert, findet sich unter User:Ferri Leberl/c_roboterseiten_konsolidierend.R.

Import

Der Import kann durch einen berechtigten User aus Special:Import durchgeführt werden. Weil bei so einer großen Sache Fehler passieren können, denen man lange hinterherläuft, empfiehlt sich ein Probelauf in einem lokalen Wiki.

Die beiden Vorlagen habe ich in der Datei Vorlagen.xml importfertig angelegt.

Spezifikationen

Spezifikationen

Skript

Die Anwendung des Skriptes wird unter
User:Ferri Leberl/Autodoku/Skriptdokumentation
erklärt.

Versionen

Beispiel: User:Ferri Leberl/Demoelement

Die unterschiedlichen Versionen werden folgend zur Verfügung gestellt:

• Die Roboterseiten werden unter user:robot/<versionsnummer>/<elementname> abgelegt
• Die aktuelle Versionsnummer ist schon derzeit in Template:Current hinterlegt — sie wird mit jeder neuen Version händisch angepasst.
• Template:docBase bindet den Schemaexport mittels {{<!-- NEVER expand this template!!! -->User:Robot/{{current}}/{{{element}}}}} ein.
• die Roboterseite ruft Template:Schemaexport auf und diese wieder Template:Versionsleiste, mit dem Elementnamen als Parameter.
• Template:Versionsleiste produziert die Navi für das betreffende Element. Derzeit wird für die laufende Version die Handseite aufgerufen, die den aktuellen Export einbindet, und für die älteren Versiuonen nur der jeweilig Export. Dies lässt sich aber unterschiedlich einrichten. Template:Versionsleiste muss bei jeder Veröffentlichung um die zusätzliche Version ergänzt werden.

Mediawiki-Installation

Mediawiki-Installation

Skizze

• Motivation
• Pipeline
  • Schema
  • entchoicen
  • Eclipe: Beispiel-XML — mit welchen Einstellungen? Wie anlegen?
  • Auswerten mit code.xsl
  • putzen mit tabkopf
  • R-Skript
    • Doppelte Elemente zusammenführen
    • Doku-Tags dazuführen
• Pipelineteilung
  • Grundstock
  • Aktueller Stand
• Einpflegen in das Wiki
  • Vorlagen
• Was sieses System nicht kann
  • Neue Elemente müssen händisch eingepflegt werden, ihre Roboterseite meldet sich nicht'.
  • Verworfene Elemente werden nicht automatisch ausgepflegt. ihre Roboterseite wird nicht gelöscht sondern bleibt mit veraltetem Stand erhalten
  • Bislang können unsere Lösungen nicht mit any-Elementen sowie any-Attributen umgehen

Testwiki

https://wikitest.railml.org/index.php?title=Common:railML