Difference between revisions of "User:Ferri Leberl/Autodoku"

From wiki.railML.org
Jump to: navigation, search
(Testwiki)
(GNU R: Erstellung der Wikiseiten)
 
(5 intermediate revisions by the same user not shown)
Line 3: Line 3:
 
Es ist beabsichtigt, die Wiki-Dokumentation von {{rml}}3 teilweise zu automatisieren. Informationen, die aus dem Schema ableitbar sind, sollen ausgewertet und automatisch in das Wiki eingepflegt werden. Dies betrifft zwei Phasen:
 
Es ist beabsichtigt, die Wiki-Dokumentation von {{rml}}3 teilweise zu automatisieren. Informationen, die aus dem Schema ableitbar sind, sollen ausgewertet und automatisch in das Wiki eingepflegt werden. Dies betrifft zwei Phasen:
 
#Erstellung eines Grundstockes: Für jedes {{rml}}-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.
 
#Erstellung eines Grundstockes: Für jedes {{rml}}-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.
#Laufende Präsentation des aktuellen Standes: In jede Elementseite soll eine Vorlage eingebunden sein, die in Tabellenform die ''Eckdaten'' der jeweils aktuellen Version darlegt. Hierbei ist im Moment die angelegte Vorgangsweise, dass ein ''User:Robot'' angelegt wird, in dessen Benutzernamensraum die Daten geparkt werden. Zu Seite CO:railml gäbe es dann eine Seite ''User:Robot/CO:railml'', die eine Vorlage mit im Prinzip den Werten von #1 aufruft, nur mit dem Stand der jeweils aktuellen Version. Hierfür ist [[User:Ferri Leberl/Template:Schemaexport]] vorgesehen.
+
#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:
 
Aus dem Schema ableitbare daten sind:
 
*Elementname
 
*Elementname
*Pflichtelement? (verworfen)
+
*Multiplicity
 
*Dokumentation (das zum Element gehörige <documentation>-Tag)
 
*Dokumentation (das zum Element gehörige <documentation>-Tag)
 
*Subschema
 
*Subschema
Line 16: Line 18:
 
*Attributdokumentationen (das zum Attribut gehörige <documentation>-Tag)
 
*Attributdokumentationen (das zum Attribut gehörige <documentation>-Tag)
 
*{{rml}}-Version
 
*{{rml}}-Version
*'''Gibt es ein gleichnamiges {{rml}}-2-Attribut?''' — Implementierung noch nicht entschieden, da das Skript komplexer würde
+
*'''Gibt es ein gleichnamiges {{rml}}-2-Attribut?''' — '''verworfen'''
  
 
==Workflow==
 
==Workflow==
Ausgangspunkt ist das Schema in Form von .xsd-Dateien. Dieses wird [[#Entchioceung|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 eine Tabelle entsteht, die von einem GNU-R-Skript zu einer Meediawiki-Importdatei aufbereitet, die für jedes Element eine Seite enthält – je nach Betriebsmodus mit der Vorlage Grundstock im Artikelraum oder mit der Vorlage Schemaexport im Benutzerraum von ''Roboter''.
+
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 ''[[#Entchioceung|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
 
Informationen, die im Beispiel-XML nicht enthalten sind, sind
*Pflichtelement?
+
*Multiplicity
 
*Elementdoku
 
*Elementdoku
 
*Pflichtattribut?
 
*Pflichtattribut?
 
*Attributdoku
 
*Attributdoku
Entweder vor oder währen GNU R müssen die — in dieser Pipeline nicht verfügbaren — Doku-Tags bzw. die Info, ob etwas verpflichtend ist, einfließen.
+
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''===
 
===''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 [[User:Ferri_Leberl/xsd_sequence|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.
 
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 [[User:Ferri_Leberl/xsd_sequence|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.
 
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===
 
===Eclipse===
Line 44: Line 54:
  
 
===Auswertung===
 
===Auswertung===
Die Auswertung erfolgt mit einem XSL-Skript, das ich vorerst nur [[User:Ferri Leberl/code.xsl|code.xsl]] nenne:
+
Die Auswertung erfolgte mit einem XSL-Skript, das ich vorerst nur [[User:Ferri Leberl/code.xsl|code.xsl]] nenne:
  
 
''saxonb-xslt railML.xml code.xsl>liste_rml23''
 
''saxonb-xslt railML.xml code.xsl>liste_rml23''
  
Die Ergebnisdatei muss noch mit dem Bashskript [[User:Ferri Leberl/tabkopf|tabkopf]] geputzt werden:
+
Die Ergebnisdatei musste noch mit dem Bashskript [[User:Ferri Leberl/tabkopf|tabkopf]] geputzt werden:
  
 
''tabkopf liste_rml23''
 
''tabkopf liste_rml23''
  
Ergebnis ist eine tabulatorgetrennte Liste (.tsv) mit, in unserem Beispiel, dem Dateinamen ''[[User:Ferri Leberl/liste_rml23|liste_rml23]]'', deren Kopfzeile die Tabelle recht gut erklärt:
+
Ergebnis war eine tabulatorgetrennte Liste (.tsv) mit, in unserem Beispiel, dem Dateinamen ''[[User:Ferri Leberl/liste_rml23|liste_rml23]]'', deren Kopfzeile die Tabelle recht gut erklärt:
  
 
Name↹Kommentar↹Subschema↹Parent↹Children↹Attribute↹Attributkommentare↹Pflichtelement↹Pflichtattribute
 
Name↹Kommentar↹Subschema↹Parent↹Children↹Attribute↹Attributkommentare↹Pflichtelement↹Pflichtattribute
  
Die Spalten ''Children'', ''Attribute'', ''Attributkommentare'' und ''Pflichtattribute'' konnen 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).
+
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 müsste für das GNU-R-Skript verwertbar sein, 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.
+
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.
===Zusammenfühung===
+
An irgendeiner Stelle müssen die Doku-Tags einfließen. Das könnte entweder jetzt mit einem eigenen Skript geschehen, oder des anschließende GNU-R-Skript wird so zurechtgebeutelt, dass es diesen schritt übernimmt. Jedenfalls wäre die logische Struktur für die Doku-Tags eine .tsv mit den im Kopf benannten Spalten
+
  
Name↹Kommentar↹Attribute↹Attributkommentare↹Pflichtelement↹Pflichtattribute
+
DI Wunsch generierte die XML-Datei, die ins Wiki importiert werden soll, direkt mit XSL und reicherte sie mittels xs3p an.
  
in der wieder die Einträge der mehrfach belegbaren Spalten durch Strichpunkte getrennt werden.
 
 
===GNU R: Erstellung der Wikiseiten===
 
===GNU R: Erstellung der Wikiseiten===
 +
{{note|Dieser Teil wurde verworfen, da die Importdatei direkt mit XSL (und xs3p) erzeugt werden kann.}}
 
Im GNU-R-Skript sollen nun folgende Schritte geschehen:
 
Im GNU-R-Skript sollen nun folgende Schritte geschehen:
 
*Konsolidierung mehrfacher Elementnamen (noch nicht implementiert)
 
*Konsolidierung mehrfacher Elementnamen (noch nicht implementiert)

Latest revision as of 10:07, 10 July 2019

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

FileNewDynamic Web ProjectProject name eintragen und Finish

FileImportFile SystemFrom Directory eintragen/suchen und im betreffenden Verzeichnis Select all und Finish

Generieren

Im Projekt die Masterdatei ansteuern→sekundärer MausklickGenerateXML File→Namen der Beispieldatei wählen und NextRoot 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

Note.png 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

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