Beispiel-Manifestdateien

QDoc generiert „example-manifest.xml“-Dateien, die Informationen zu allen dokumentierten Beispielen enthalten. Diese Dateien werden von Qt Creator verwendet, um auf der Startseite eine Liste der Beispiele anzuzeigen und auf deren Dokumentation zu verlinken.

XML-Struktur des Manifests

Eine Manifest-Datei hat 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 „ <example> “-Element enthält Informationen zu einem Namen, einer Beschreibung, dem Speicherort der Projektdatei und der Dokumentation sowie eine Liste der mit dem Beispiel verbundenen Tags.

Meta-Inhalt des Manifests

Es ist möglich, die Manifestdateien mit zusätzlichen Metainformationen zu ergänzen – d. h. mit zusätzlichen Attributen und Tags für ausgewählte Beispiele –, indem der Konfigurationsbefehl ` manifestmeta ` verwendet wird.

Ein Anwendungsfall für Metainhalte ist die Hervorhebung einer Reihe besonders wichtiger Beispiele. Ein weiterer besteht darin, die Suchfunktion zu verbessern, indem relevante Schlüsselwörter als Tags für eine bestimmte Kategorie von Beispielen hinzugefügt werden.

Die Beispiele, auf die Metainhalte angewendet werden sollen, werden mithilfe eines oder mehrerer Filter festgelegt. Die Zuordnung der Beispiele zu den Filtern erfolgt anhand der Namen, wobei jedem Beispielnamen ein Modulname und ein Schrägstrich vorangestellt werden. Einfache Platzhalter sind 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 wird zwei Beispielen ein „ isHighlighted “-Attribut hinzugefügt. Wird der Attributwert weggelassen, verwendet QDoc standardmäßig die Zeichenfolge „ 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 lediglich „ * “ als Übereinstimmungszeichenfolge verwendet wird.