User:RailML Coord Documentation/Autodoku: Difference between revisions

From railML 2 Wiki
Jump to navigation Jump to search
(Replaced content with "{{mirror|{{iuser}}}}")
Tag: Replaced
(3 intermediate revisions by the same user not shown)
Line 1: Line 1:
'''Unterstützung der {{rml}}-Dokumentation durch Skripte'''
{{mirror|{{iuser}}}}
==Motivation==
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.
#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)
*{{rml}}-Version
*'''Gibt es ein gleichnamiges {{rml}}-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 ''[[#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
*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 [[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.
 
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 {{rml}}2.3 stellt sich bei mir das Ergebnis [[User:Ferri Leberl/railML.xml|railML.xml]] ein.
 
===Auswertung===
Die Auswertung erfolgt mit einem XSL-Skript, das ich vorerst nur [[User:Ferri Leberl/code.xsl|code.xsl]] nenne:
 
''saxonb-xslt railML.xml code.xsl>liste_rml23''
 
Die Ergebnisdatei muss noch mit dem Bashskript [[User:Ferri Leberl/tabkopf|tabkopf]] geputzt werden:
 
''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:
 
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).
 
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.
===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
 
in der wieder die Einträge der mehrfach belegbaren Spalten durch Strichpunkte getrennt werden.
===GNU R: Erstellung der Wikiseiten===
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 [[User:Ferri_Leberl/c_roboterseiten.R|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 [[User:Ferri_Leberl/dump2wiki.xml|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 [[User:Ferri_Leberl/Vorlagen.xml|Vorlagen.xml]] importfertig angelegt.
 
==Spezifikationen==
[[User:Ferri Leberl/Autodoku/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 <nowiki>{{&lt;!-- NEVER expand this template!!! -->User:Robot/{{current}}/{{{element}}}}}</nowiki> 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==
[[User:Ferri Leberl/Autodoku/Mediawiki|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

Revision as of 11:11, 19 June 2020