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
(28 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]]
#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:Roboter'' angelegt wird, in dessen Benutzernamensraum die Daten geparkt werden. Zu Seite CO:railml gäbe es dann eine Seite ''User:Roboter/CO:railml'', die eine Vorlage mit imprinzip den Werten von #1 aufruft, nur mit dem Stand der jeweils aktuellen Version. Hierfür ist Dazu dient [[User:Ferri Leberl/Template:Schemaexport]] vorgesehen.
 
Aus dem Schema ableitbare daten sind:
*Elementname
*Pflichtelement? (verworfen)
*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)
 
==Pipeline==
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''.
 
Informationen, die im Beispiel-XML nicht enthalten sind, sind
*Pflichtelement?
*Elementdoku
*Pflichtattribut?
*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.
===''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.
===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''
===Auswertung===
Die Auswertung erfolgt mit einem XSL-Skript, das ich vorerst nur [[code.xsl]] nenne:
 
''saxonb-xslt railml.xml code.xsl>liste''
 
Die Ergebnisdatei muss noch mit dem Bashskript [[tabkopf]] geputzt werden:
 
''tabkopf liste''
 
Ergebnis ist eine tabulatorgetrennte Liste mit, in unserem Beispiel, dem Dateinamen ''liste'', 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).
 
==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

Revision as of 11:11, 19 June 2020