Beispiel für Manifestdateien

QDoc generiert example-manifest.xml Dateien, die Informationen über alle dokumentierten Beispiele enthalten. Diese Dateien werden von Qt Creator verwendet, um eine Liste von Beispielen in seinem Willkommensbildschirm zu präsentieren und um auf ihre Dokumentation zu verweisen.

XML-Struktur des Manifests

Eine Manifestdatei hat die folgende Struktur:

<?xml version="1.0" encoding="UTF-8"?>
<instructionals module="QtGui">
    <examples>
        <example
            name="Analog Clock Window"
            docUrl="qthelp://org.qt-project.qtgui.502/qtgui/analogclock.html"
            projectPath="gui/analogclock/analogclock.pro"
            imageUrl="qthelp://org.qt-project.qtgui.502/qtgui/images/analogclock-window.png">
            <description><![CDATA[The Analog Clock Window example shows how
                to draw the contents of a custom window.]]></description>
            <tags>analog,clock,window</tags>
            <fileToOpen>gui/analogclock/main.cpp</fileToOpen>
        </example>
        ...
    </examples>
</instructionals>

Jedes Element <example> enthält Informationen über einen Namen, eine Beschreibung, den Speicherort der Projektdatei und der Dokumentation sowie eine Liste der mit dem Beispiel verbundenen Tags.

Manifest-Meta-Inhalt

Es ist möglich, die Manifestdateien mit Hilfe des Konfigurationsbefehls manifestmeta um zusätzliche Meta-Inhalte zu erweitern, d.h. um zusätzliche Attribute und Tags für ausgewählte Beispiele.

Ein Anwendungsfall für Meta-Inhalte ist das Hervorheben einer Reihe von herausragenden Beispielen. Ein weiterer Anwendungsfall ist die Verbesserung der Suchfunktionalität durch Hinzufügen relevanter Schlüsselwörter als Tags für eine bestimmte Kategorie von Beispielen.

Die Beispiele, auf die der Meta-Inhalt angewendet wird, werden mit einem oder mehreren Filtern festgelegt. Die Zuordnung von Beispielen zu Filtern erfolgt auf der Grundlage von Namen, wobei jedem Beispielnamen ein Modulname und ein Schrägstrich vorangestellt wird. Es wird ein einfacher Wildcard-Abgleich unterstützt; durch die Verwendung von * am Ende ist es möglich, mehrere Beispiele mit einer einzigen Zeichenfolge abzugleichen.

Beispiel:

manifestmeta.filters                = highlighted sql webkit global

manifestmeta.highlighted.names      = "QtGui/Analog Clock Window" \
                                      "QtWidgets/Analog Clock"
manifestmeta.highlighted.attributes = isHighlighted:true

manifestmeta.sql.names              = "QtSql/*"
manifestmeta.sql.tags               = database,sql

manifestmeta.webkit.names           = "QtWebKitExamples/*"
manifestmeta.webkit.tags            = webkit

manifestmeta.global.names           = *
manifestmeta.global.tags            = qt6

Oben wurde ein isHighlighted Attribut zu zwei Beispielen hinzugefügt. Wenn der Wert des Attributs weggelassen wird, verwendet QDoc standardmäßig die Zeichenkette true. Für die Beispiele Qt WebKit und Qt SQL werden zusätzliche Tags hinzugefügt, und ein weiteres Tag wird auf alle Beispiele angewendet, indem nur * als Match-String verwendet wird.