SDB:KIWI Kochbuch RelaxNG Schema

Wechseln zu: Navigation, Suche


Hier kann man herausfinden, wie man das KIWI RELAX NG Schema entwickeln und anpassen kann. Es wird für die Validierung der XML-Konfigurations-Datei benötigt.
Getestet mit openSUSE Empfohlene Artikel Verwandte Artikel
Icon-checked.png

Icon-manual.png Icon-help.png


Ein neues Element in das KIWI RELAX NG Schema einfügen

In den vorherigen Beispielen haben wir die Datei config.xml modifiziert, um das von Kiwi erzeugte Abbild zu steuern. Als der Teil der Kiwi-Abarbeitung wird diese XML-Datei gegen ein Schema validiert. Und wenn Sie einen Tippfehler beim Modifizierungs-Prozess in der XML-Datei eingebracht haben, sind Sie bereits dem Validierungs-Prozess in der Form einer Fehlermeldung begegnet. Das Schema das die config.xml-Datei beherrscht ist in RELAX NG implementiert. Sie können sich das neueste Schema hier ansehen.

Anders als unseren vorangegangenen Beispiele, die sich auf die Anwendung von Kiwi zur Erstellung eines Abbildes konzentrierten, wird dieses Beispiel mehr auf den Entwickler ausgerichtet, da es zeigt, wie man Modifikationen in das Schema bringt, das die config.xml-Datei beherrscht.

Eine Bemerkung zur Kiwi-Entwicklung

Das Kiwi-Projekt ist in berlios.de untergebracht und der Projekt-Code wird im Repository git verwaltet. Sie können den Quellbaum über den anonymous git Zugang des folgenden url: git://git.berlios.de/kiwi klonen. Mehr Informationen über git erhalten Sie auf der git Projekt Seite.

Übersicht

RELAX NG ist eine Schema-Sprache, die verwendet wird, um XML-Schema zu definieren. Anders als die DTD (Dokumenten-Type- Definition) oder W3C XML Schema hat die praktische Anwendung der Schema-Definition RELAX LG (betont relaxing) den Vorteil, dass sie Definition des Schemas in XML oder in einer kompakten Syntax geschrieben sein könnte. Besuchen Sie die RELAX NG Home page und erfahren Sie mehr über Relax NG. Das Kiwi-Schema wird in der kompakten Syntax (bekannt als RNC) entwickelt.

Neue Elemente zum KIWI-Schema hinzufügen

Es wird empfohlen, dass Sie die folgenden Schritte vorrangig verwenden, um Veränderungen in das Kiwi-Schema einzubringen:

  1. Haben Sie Grundwissen zu Git haben
  2. Sie benötigen grundlegende Kenntnisse von XML und RELAX NG (prüfen Sie die Anleitung unter RELAX NG
  3. Ziehen Sie die grundsätzliche Anwendbarkeit und Notwendigkeit des Elements in Betracht oder würde ein Attribut in einem vorhandenen Element genügen?
  4. Fragen Sie die Entwickler-Gemeinschaft der Kiwi-Entwickler-Liste kiwi-devel auf lists.berlios.de

Die folgenden Schritte zeigen die grundsätzliche Vorgehensweise auf, wie man ein neues Element hinzufügt, wenn Sie festgelegt haben, dass es notwendig ist.

  1. Unter Verwendung Ihres bevorzugten Editors bearbeiten Sie die kompakte Dyntax-Datei modules/KIWISchema.rnc
  2. Verwenden Sie die Vorlage unten als Ihre Anleitung und passen Sie es an die Bedürfnisse des neuen Elements an. Versuchen Sie vorhandene Muster so oft wie möglich zu verwenden.
  3. Fügen Sie Ihr neues Element als ein Kind zu einem Eltern-Element. Ihr neues Element könnte ein Kind des image -Elements oder eines anderen Elements sein.
  4. Validieren Sie das Kiwi-Schema mit dem RELAX NG Schema. Verwenden Sie Jing, um es zu validieren und korrigieren Sie alle berichteten Fehler:
jing -c relaxng.rng KIWISchema.rnc
  1. Verändern Sie die Kiwi-Dokumentation, um das neue Element zu dokumentieren.
  2. Erstellen Sie ein Patch und senden Sie es zur Kiwi-Entwickler-Liste (kiwi-devel auf lists.berlios.de)

Struktur eines KIWI Elements

Jedes Element im RNC-Schema enthält folgende Teile:

  • Eine Bezeichnung, beginnend mit k., zum Beispiel k.image
    • Diese Bezeichnung wird als Referenz verwendet, um Ihr Element-Muster zu sammeln.
  • Ein kurzer RELAX NG Kommentar
  • Ein DocBook 5 para Element für eine ausführlichere Dokumentation
  • Die sinngemäße Element Definition

Die Definition von Attributen ist ähnlich der Element-Definition. Attribute haben kein DocBook 5 Dokumentations-Element

Bezeichnungs-Vereinbarung

RNC verwendet eine Bezeichnungs-Vereinbarung, mit dem Ziel, die Einheitlichkeit zu ermöglichen. In der Vereinbarung, die unten aufgezeigt ist ersetzen Sie die Platzhalter in kursiv mit den geeigneten Werten für Ihre Änderungen/Ergänzungen.

  • Element Muster: k.ELEMENTNAME
    Enthält die komplette Definition des gegebenen Elements, einschließlich Attribute und Inhalts-Modell. Zum Beispiel: k.image für das image Element.
  • Attribut Muster: k.ELEMENTNAME.ATTRNAME.attribute
    Contains an attribute definition for a given element, for example: k.image.name.attribute für das name Attribut des image Elements.
  • Attribut Muster für geteilte Attribute: k.ATTRNAME.attribute
    Verwendet für Attribute, die von mehreren Elementen verwendet werden, zum Beispeil: k.id.attribute für das id Attribut.
  • Attribut Zusammenstellung: k.ELEMENTNAME.attlist
    Sammelt alle Attribute für ein gegebenes Element, zum Beispiel: k.image.attlist enthält alle Attribute des image Elements.
  • Inhalts-Muster: k.ELEMENTNAME.content
    Enthält die unterstützten Werte und Datentypen in diesem Kontext.

KIWI Element Vorlage

Soweit zu den Einführungen. Lassen Sie uns genauer auf die Grund-Vorlage für die Element-Definition im RNC-Format schauen. Für Ihre eigene Elementen-Definition ersetzen Sie foo durch die geeignete Bezeichnung. Die Zahlen (x) sind nicht Bestandteil der Vorlage und verweisen auf die detaillierte Erklärung unter der Vorlage. 

# ==========================================
# The element <foo>
#
div { # (1)
  # (2)
  k.foo.name.attribute = k.name.attribute

  # (3)
  k.foo.bar.attribute =
    ## The bar attribute does a very important task ...
    attribute bar { text }
  
  # (4)
  k.foo.attlist =
    k.foo.name.attribute
    & k.foo.bar.attribute?

  # (5)
  k.foo = 
    ## A useful foo element
    [
      db:para [ "Insert a more descriptive text, examples, ..." ]
    ]
    element foo 
    { 
      k.foo.attlist, text 
    }
}

# (6)

Detaillierte Erklärung der Vorlage:

  1. Packen Sie jede Elementdefinition in eine div { ... }-Konstruktion
  2. Bezeichnen Sie Ihre Attribute gemäß der obigen Vereinbarungen. Verwenden Sie vorhandene Attribute, wenn immer es möglich ist.
  3. Definieren Sie Ihre eigenen Attribute unf fügen Sie eine Anmerkung mit ## und dem korrespondieren Attribut ein.
  4. Definieren Sie eine Zusammenstellung aller Ihrer definierten Attribute in der .attlist -Bezeichnung. Wenn ein Attribut optional ist, kennzeichnen Sie es mit dem Zeichen ?. Da Attribute keine Vorschrift besitzen, verwenden Sie die Muster-Verschachtelung, die durch das Zeichen & angezeigt wird.
  5. Definiere das Element. Fügen Sie die Anmerkung hinzu (##), die Dokumentation (db:para) und die Element-Definition. Abhängig vom Inhaltsmodell (Beziehung und Struktur) müssten Sie weitere Elemente auf ähnliche Weise definieren. Vergessen Sie nicht die .attlist-Bezeichnung einzufügen.
  6. Integrieren Sie das neu definierte Element in das Inhalts-Modell von einem anderen Element.

Vergessen Sie nicht, die Kiwi-Dokumentation mit der Beschreibung des neuen Elements zu aktualisieren.

Erstellung des XML Format aus der Compact-Syntax

Das Kiwi-Schema wird in RNC entwickelt, kann aber in die XML-Syntax konvertiert werden, unter Verwendung von trang:

trang KIWISchema.rnc KIWISchema.rng


Das XML-Syntax-Format und das Compact-Syntax-Format sind gleichwertig. Das XML-Format, das als Teil des Kiwi-Bau-Prozesses generiert wird, könnte für weitere Bearbeitungen verwendet werden. Zum Beispiel: extrahieren der Dokumentation um eine HTML-Seite zu erstellen.

Zusätzliche Informationen

Zusätzlich zum Hinzufügen neuer Elemente zu dem Schema ist es möglich durch Erweiterung von Kiwi das Schema individuell einzurichten. Das wird im Blog KIWI RELAX NG Schema erklärt.

Abgerufen von „https://de.opensuse.org/index.php?title=SDB:KIWI_Kochbuch_RelaxNG_Schema&oldid=32430“