Archivos de manifiesto de ejemplo

QDoc genera archivos example-manifest.xml que contienen información sobre todos los ejemplos documentados. Estos archivos son utilizados por Qt Creator para presentar una lista de ejemplos en su pantalla de bienvenida y para enlazar con su documentación.

Estructura XML del manifiesto

Un archivo de manifiesto tiene la siguiente estructura:

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

Cada elemento <example> contiene información sobre un nombre, una descripción, la ubicación del archivo del proyecto y la documentación, así como una lista de etiquetas asociadas al ejemplo.

Contenido meta del manifiesto

Es posible aumentar los archivos de manifiesto con metacontenido adicional, es decir, atributos y etiquetas extra para los ejemplos seleccionados, utilizando el comando de configuración manifestmeta.

Uno de los usos del metacontenido es destacar una serie de ejemplos destacados. Otro es mejorar la funcionalidad de búsqueda añadiendo palabras clave relevantes como etiquetas para una determinada categoría de ejemplos.

Los ejemplos a los que se aplica el metacontenido se especifican mediante uno o varios filtros. La correspondencia de los ejemplos con los filtros se basa en los nombres, con cada nombre de ejemplo precedido de un nombre de módulo y una barra oblicua. Se admite el uso de comodines simples; si se utiliza * al final, es posible emparejar varios ejemplos con una sola cadena.

Ejemplo:

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

Arriba, se añade un atributo isHighlighted a dos ejemplos. Si se omite el valor del atributo, QDoc utiliza por defecto la cadena true. Se añaden etiquetas adicionales para los ejemplos de Qt WebKit y Qt SQL, y se aplica otra etiqueta a todos los ejemplos utilizando sólo * como cadena de coincidencia.