User:RailML Coord Documentation/Autodoku

From railML 2 Wiki
Jump to navigation Jump to search
đŸ—’ïž 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