User:RailML Coord Documentation/Autodoku

From railML 2 Wiki
Jump to navigation Jump to search

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

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