Wie dokumentieren Sie die Struktur von XML-Dateien
Wenn es darum geht zu dokumentieren, die Struktur von XML-Dateien...
Einer meiner co-Arbeiter hat es in eine Word-Tabelle.
Anderen fügt die Elemente in ein Word-Dokument mit Kommentaren wie diesem:
<learningobject id="{Learning Object Id (same value as the loid tag)}"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="http://www.aicpcu.org/schemas/cms_lo.xsd">
<objectRoot>
<v>
<!-- Current version of the object from the repository. !-->
<!-- (Occurance: 1) -->
</v>
<label>
<!-- Name of the object from the repository. !-->
<!-- (Occurance: 0 or 1 or Many) -->
</label>
</objectRoot>
Welche der beiden Methoden bevorzugt? Gibt es einen besseren Weg?
Gibt es andere Optionen, die nicht von Dritten Schema Documenter-tools zu aktualisieren?
InformationsquelleAutor der Frage joe | 2009-11-17
Du musst angemeldet sein, um einen Kommentar abzugeben.
Ich würde schreiben ein XML-Schema (XSD) - Datei definiert die Struktur des XML-Dokuments.
xs:annotation
undxs:documentation
- tags enthalten, um zu beschreiben, die Elemente. Die XSD-Datei transformiert werden kann in der Dokumentation unter Verwendung von XSLT-stylesheets wie xs3p oder tools wie XML-Schema-Documenter.Für eine Einführung in XML-Schema finden Sie in der XML-Schulen-tutorial.
Hier ist Ihr Beispiel, ausgedrückt als ein XML-Schema mit
xs:annotation
tags:InformationsquelleAutor der Antwort Phil Ross
Genießen Sie RELAX NG compact syntax
Experimentieren mit verschiedenen XML-schema-Sprachen, die ich gefunden habe, RELAX NG beste Passform für die meisten Fälle (Begründung am Ende).
Anforderungen
Modifizierte Beispiel-XML - (doc.xml)
Habe ich Hinzugefügt ein Attribut, um zu veranschaulichen, auch diese Art von Struktur in die Dokumentation.
Mit RELAX NG Compact syntax mit Kommentaren (schema.rnc)
RELAX NG erlaubt die Beschreibung von Beispiel-XML-Struktur in der folgenden Art und Weise:
Ich denke, es ist sehr schwer zu schlagen ist die Einfachheit, halten bestimmtes Maß an Ausdruckskraft.
Wie kommentieren Sie die Struktur
##
Präfix wird automatisch übersetzt in die Dokumentation element im anderen schema-format. Einzelne hash -#
übersetzt in XML-Kommentar und nicht um eine Dokumentation element.mehrere aufeinanderfolgende Kommentare (wie im Beispiel) wird wiederum in eine einzige multi-line-Dokumentation-string in einzelne Elemente.
offensichtliche Tatsache: die inline-XML-Kommentare in
doc.xml
sind irrelevant, nur das, was inschema.rnc
zählt.Wenn XML Schema 1.0 erforderlich ist, generieren (schema.xsd)
Vorausgesetzt, Sie haben eine (open-Source) tool namens
trang
verfügbar, können Sie erstellen Sie eine XML-Schema-Datei wie folgt:Resultierende schema sieht wie folgt aus:
Nun können Ihre Kunden beharren auf verwenden nur XML Schema 1.0 verwenden Sie Ihre XML-Dokument-Spezifikation.
Überprüfen doc.xml gegen schema.rnc
Open-source-Werkzeuge wie
jing
undrnv
unterstützt RELAX NG Compact syntax und sowohl mit Linux als auch auf MS Windows.Hinweis: diese tools sind eher alt, aber sehr stabil. Lesen Sie es als ein Zeichen der Stabilität nicht als Zeichen der veraltet.
Mit jing:
Den
-c
ist wichtig,jing
standardmäßig davon ausgegangen, RELAX NG in XML-form.Mit
rnv
zu überprüfen, dieschema.rnc
selbst gültig ist:und zu validieren
doc.xml
:rnv
ermöglicht die Validierung mehrerer Dokumente auf einmal:RELAX NG Compact syntax - Profis
RELAX NG Einschränkungen
Schlussfolgerungen
Für die Anforderung, die oben definiert, RELAX NG Compact syntax sieht aus wie die beste Passform. Mit RELAX NG Sie erhalten sowohl - als- menschlichen lesbaren schema ist auch anwendbar für automatisierte Validierung.
Bestehenden Grenzen nicht in Kraft treten, sehr oft und können in vielen Fällen gelöst, indem die Kommentare oder auf anderem Wege.
InformationsquelleAutor der Antwort Jan Vlcinsky
Könnten Sie versuchen, es zu dokumentieren, indem Sie ein XSD-schema, das eine mehr formale Spezifikation von XML. Viele tools erzeugen die XSD aus XML-Beispielcode als Ausgangspunkt.
InformationsquelleAutor der Antwort zac
Persönlich, ich würde lieber sehen Sie in XML (2. Weg).
Setzen Sie die Elemente in der Tabelle werden Ihnen nicht sagen, klar, die Elemente sind die Elemente Eltern-Kind-und so weiter. Dass es in XML ist eher klarer und ich kann sehen, was Los ist.
InformationsquelleAutor der Antwort mauris
Zeigt es in einer Tabelle hat seine limitaions z.B. Multi-Ebenen von geschachtelten Kinder, aber für eine einfache XML-Struktur, die ich denke, das wäre in Ordnung. Für alles mit mehr als einer verschachtelten Ebene würde ich lieber den XML Weg.
Einen noch besseren Weg zum erstellen einer XML-Schemadatei (XSD) - Datei. So erhalten Sie die Vorteile sehen Sie in XML, und Sie können überprüfen Sie die Datei, nachdem die Daten eingegeben gegen die schema-Datei in einem software.
Für eine große Reihe von tutorials auf XSD-check-out w3schools, XML-Schema Tutorial
InformationsquelleAutor der Antwort Adam Harte
Ich möchte nur hinzufügen, eine weitere Sache, im Falle, jemand findet es nützlich.
Ich manchmal Programmieren in HTML und zu anderen Zeiten in android. Wenn ich HTML ich mein benutzerdefiniertes XML-Dokument folgt dem gleichen format wie W3Schools, wie in http://www.w3schools.com/tags/att_a_href.asp wenn es ein android-Projekt, das ich arbeite, dann Folge ich Google standards wie in http://developer.android.com/guide/topics/manifest/activity-element.html#screen
Auf diese Weise haben die Programmierer arbeite ich mit nicht extra arbeiten zu verstehen, meine Dokumentation.
InformationsquelleAutor der Antwort Carolina Prieto Muñiz