Qt Help Proyecto

Un proyecto Qt Help recoge todos los datos necesarios para generar un archivo de ayuda comprimido. Junto con los datos de ayuda reales, como la tabla de contenidos, las palabras clave del índice y los documentos de ayuda, contiene alguna información extra como un espacio de nombres para identificar el archivo de ayuda. Un proyecto de ayuda representa un conjunto de documentación, por ejemplo el Manual de qmake.

Qt Help Formato del archivo de proyecto

El formato de archivo está basado en XML. Para una mejor comprensión del formato discutiremos el siguiente ejemplo:

<?xml version="1.0" encoding="UTF-8"?>
<QtHelpProject version="1.0">
    <namespace>mycompany.com.myapplication.1.0</namespace>
    <virtualFolder>doc</virtualFolder>
    <customFilter name="My Application 1.0">
        <filterAttribute>myapp</filterAttribute>
        <filterAttribute>1.0</filterAttribute>
    </customFilter>
    <filterSection>
        <filterAttribute>myapp</filterAttribute>
        <filterAttribute>1.0</filterAttribute>
        <toc>
            <section title="My Application Manual" ref="index.html">
                <section title="Chapter 1" ref="doc.html#chapter1"/>
                <section title="Chapter 2" ref="doc.html#chapter2"/>
                <section title="Chapter 3" ref="doc.html#chapter3"/>
            </section>
        </toc>
        <keywords>
            <keyword name="foo" id="MyApplication::foo" ref="doc.html#foo"/>
            <keyword name="bar" ref="doc.html#bar"/>
            <keyword id="MyApplication::foobar" ref="doc.html#foobar"/>
        </keywords>
        <files>
            <file>classic.css</file>
            <file>*.html</file>
        </files>
    </filterSection>
</QtHelpProject>

Espacio de nombres

Para que QHelpEngine pueda recuperar la documentación correspondiente a un enlace determinado, cada conjunto de documentación debe tener un identificador único. Un identificador único también hace posible que la colección de ayuda siga la pista de un conjunto de documentación sin depender de su nombre de archivo. El sistema de ayuda de Qt utiliza un espacio de nombres como identificador que se define mediante las etiquetas obligatorias del espacio de nombres. En el ejemplo anterior, el espacio de nombres es "miempresa.com.miaplicación.1.0".

Carpetas virtuales

Tener un espacio de nombres para cada conjunto de documentación significa naturalmente que los conjuntos de documentación están bastante separados. Desde el punto de vista del motor de ayuda, esto es beneficioso. Sin embargo, desde el punto de vista del escritor, a menudo es deseable cruzar referencias de ciertos temas de un manual a otro sin tener que especificar enlaces absolutos. Para resolver este problema, el sistema de ayuda introdujo el concepto de carpetas virtuales.

Una carpeta virtual se convertirá en el directorio raíz de todos los archivos a los que se haga referencia en un archivo de ayuda comprimido. Cuando dos conjuntos de documentación comparten la misma carpeta virtual, pueden utilizar rutas relativas al definir hipervínculos que apunten el uno al otro. Si un archivo está contenido en ambos conjuntos de documentación, el del conjunto actual tiene prioridad sobre el otro.

...
<virtualFolder>doc</virtualFolder>
...

El ejemplo anterior especifica doc como carpeta virtual. Si otro manual especifica la misma carpeta, por ejemplo para una pequeña herramienta de ayuda Mi aplicación, basta con escribir doc.html#section1 para hacer referencia a la primera sección del manual Mi aplicación.

La etiqueta de carpeta virtual es obligatoria y el nombre de la carpeta no debe contener barras (/).

Sección Filtro

Una sección de filtro contiene la documentación propiamente dicha. Un archivo de proyecto de ayuda Qt puede contener más de una sección de filtro. Cada sección de filtro consiste en la tabla de contenidos, las palabras clave y la lista de archivos. En teoría, todas las partes son opcionales, pero si no se especifica nada, la documentación quedará vacía.

Tabla de contenidos

...
<toc>
    <section title="My Application Manual" ref="index.html">
        <section title="Chapter 1" ref="doc.html#chapter1"/>
        <section title="Chapter 2" ref="doc.html#chapter2"/>
        <section title="Chapter 3" ref="doc.html#chapter3"/>
    </section>
</toc>
...

Una etiqueta de sección representa un elemento del índice. Las secciones pueden anidarse en cualquier grado, pero desde la perspectiva del usuario no deberían superar los cuatro o cinco niveles. Una sección se define por su título y su referencia. La referencia, como todas las referencias de archivos en un proyecto de ayuda Qt, son relativas al propio archivo del proyecto de ayuda.

Palabras clave

...
<keywords>
   <keyword name="foo" id="MyApplication::foo" ref="doc.html#foo"/>
   <keyword name="bar" ref="doc.html#bar"/>
   <keyword id="MyApplication::foobar" ref="doc.html#foobar"/>
</keywords>
...

La sección de palabras clave enumera todas las palabras clave de esta sección de filtrado. Una palabra clave consiste básicamente en un nombre y una referencia de archivo. Si se utiliza el atributo nombre, la palabra clave especificada allí aparecerá en el índice visible. Es decir, será accesible a través de la clase QHelpIndexModel. Si se utiliza id, la palabra clave no aparecerá en el índice y sólo será accesible a través de QHelpEngineCore::documentsForIdentifier(). name e id pueden especificarse al mismo tiempo.

Archivos

...
<files>
    <file>classic.css</file>
    <file>*.html</file>
</files>
...

Por último, hay que enumerar los archivos de documentación propiamente dichos. Asegúrese de que se mencionan todos los archivos necesarios para mostrar la ayuda. Es decir, las hojas de estilo o archivos similares deben ser listados también. Los archivos, como todas las referencias a archivos en un proyecto de ayuda Qt, son relativos al propio archivo del proyecto de ayuda. Como muestra el ejemplo, los archivos (pero no los directorios) también pueden especificarse como patrones utilizando comodines. Todos los archivos listados serán comprimidos y escritos en el archivo de ayuda comprimido de Qt. Así, al final, un único archivo de ayuda Qt contiene todos los archivos de documentación junto con los contenidos e índices.