Doc: Document example manifest files in QDoc manual

Adds documentation for example manifest files and the related qdoc
configuration command \manifestmeta into QDoc manual.

Change-Id: I6a627698ab14f57c9a117b6d4b794f352959f5ac
Reviewed-by: Martin Smith <martin.smith@digia.com>
Reviewed-by: Jerome Pasion <jerome.pasion@digia.com>

1 files changed, 93 insertions, 0 deletions

diff --git a/src/tools/qdoc/doc/qdoc-manual.qdoc b/src/tools/qdoc/doc/qdoc-manual.qdoc
index 4d70faa968..b715b200bf 100644
--- a/src/tools/qdoc/doc/qdoc-manual.qdoc
+++ b/src/tools/qdoc/doc/qdoc-manual.qdoc
@@ -65,6 +65,7 @@
           \li \l {C++ Specific Configuration Variables}
           \li \l {HTML Specific Configuration Variables}
           \li \l {Supporting Derived Projects}
+          \li \l {Example Manifest Files}
           \li \l {qt.qdocconf}
           \li \l {minimum.qdocconf}
           \li \l {Generating DITA XML Output}
@@ -7154,6 +7155,7 @@
     \li \l {22-qdoc-configuration-generalvariables.html#images.fileextensions-variable} {images.fileextensions}
     \li \l {22-qdoc-configuration-generalvariables.html#language-variable} {language}
     \li \l {22-qdoc-configuration-generalvariables.html#macro-variable} {macro}
+    \li \l {22-qdoc-configuration-generalvariables.html#manifestmeta-variable} {manifestmeta}
     \li \l {22-qdoc-configuration-generalvariables.html#outputdir-variable} {outputdir}
     \li \l {22-qdoc-configuration-generalvariables.html#outputformats-variable} {outputformats}
     \li \l {22-qdoc-configuration-generalvariables.html#sourcedirs-variable} {sourcedirs}
@@ -7850,6 +7852,14 @@
 
     See also \l {alias-variable} {alias}.
 
+    \target manifestmeta-variable
+    \section1 manifestmeta
+
+    The \c manifestmeta variable specifies additional meta-content
+    for the example manifest files generated by QDoc.
+
+    See the \l{Manifest Meta Content} section for more information.
+
     \target naturallanguage-variable
     \section1 naturallanguage
 
@@ -8472,6 +8482,7 @@
     \page 25-qdoc-configuration-derivedprojects.html
     \previouspage HTML Specific Configuration Variables
     \contentspage QDoc Manual
+    \nextpage Example Manifest Files
 
     \title Supporting Derived Projects
 
@@ -8610,6 +8621,88 @@
 */
 
 /*!
+    \page 26-qdoc-configuration-example-manifest-files.html
+    \previouspage Supporting Derived Projects
+    \contentspage QDoc Manual
+
+    \title Example Manifest Files
+
+    QDoc generates XML files that contain information about all documented
+    examples and demos. These files, named \c {examples-manifest.xml} and
+    \c {demos-manifest.xml}, are used by Qt Creator to present a list of
+    examples in its welcome screen and to link to their documentation.
+
+    \section1 Manifest XML Structure
+
+    A manifest file has the following structure:
+
+    \code
+    <?xml version="1.0" encoding="UTF-8"?>
+    <instructionals module="QtGui">
+        <examples>
+            <example
+                name="Analog Clock Window Example"
+                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-example.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>
+    \endcode
+
+    Each \c {<example>} element contains information about a name,
+    description, the location of the project file and documentation,
+    as well as a list of tags associated with the example.
+
+    \target metacontent
+    \section1 Manifest Meta Content
+
+    It is possible to augment the manifest files with additional
+    meta-content - that is, extra attributes and tags for selected
+    examples, using the \c manifestmeta configuration command.
+
+    One use case for meta-content is highlighting a number of prominent
+    examples. Another is improving search functionality by adding
+    relevant keywords as tags for a certain category of examples.
+
+    The examples for which meta-content is applied to is specified using
+    one or more filters. Matching examples to filters is done based on
+    names, with each example name prefixed with a module name and a
+    slash. Simple wildcard matching is supported; by using \c {*} at the
+    end it's possible to match multiple examples with a single string.
+
+    Example:
+
+    \code
+    manifestmeta.filters                = highlighted sql webkit global
+
+    manifestmeta.highlighted.names      = "QtGui/Analog Clock Window Example" \
+                                          "QtWidgets/Analog Clock Example"
+    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            = qt5
+    \endcode
+
+    Above, an \c isHighlighted attribute is added to two examples. If
+    the attribute value is omitted, QDoc uses the string \c {true} by
+    default. Extra tags are added for Qt WebKit and Qt SQL examples, and
+    another tag is applied to all examples by using just \c {*} as the
+    match string.
+*/
+
+/*!
     \page 27-qdoc-commands-alphabetical.html
     \previouspage Introduction to QDoc
     \contentspage QDoc Manual