/usr/share/qt5/doc/qthelp/qthelpproject.html is in qttools5-doc-html 5.5.1-3build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 | <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- qthelp.qdoc -->
<title>Qt Help Project | Qt Help 5.5</title>
<link rel="stylesheet" type="text/css" href="style/offline.css" />
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<ul>
<li>Qt 5.5</li>
<li><a href="qthelp-index.html">Qt Help</a></li>
<li>Qt Help Project</li>
<li id="buildversion">Qt 5.5.1 Reference Documentation</li>
</ul>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#qt-help-project-file-format">Qt Help Project File Format</a></li>
<li class="level2"><a href="#namespace">Namespace</a></li>
<li class="level2"><a href="#virtual-folders">Virtual Folders</a></li>
<li class="level2"><a href="#custom-filters">Custom Filters</a></li>
<li class="level2"><a href="#filter-section">Filter Section</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">Qt Help Project</h1>
<span class="subtitle"></span>
<!-- $$$qthelpproject.html-description -->
<div class="descr"> <a name="details"></a>
<p>A Qt help project collects all data necessary to generate a compressed help file. Along with the actual help data, like the table of contents, index keywords and help documents, it contains some extra information like a namespace to identify the help file. One help project stands for one documentation, for example the Qt Assistant Manual.</p>
<a name="qt-help-project-file-format"></a>
<h2 id="qt-help-project-file-format">Qt Help Project File Format</h2>
<p>The file format is XML-based. For a better understanding of the format we'll discuss the following example:</p>
<pre class="cpp"><span class="operator"><</span><span class="operator">?</span>xml version<span class="operator">=</span><span class="string">"1.0"</span> encoding<span class="operator">=</span><span class="string">"UTF-8"</span><span class="operator">?</span><span class="operator">></span>
<span class="operator"><</span><span class="type">QtHelpProject</span> version<span class="operator">=</span><span class="string">"1.0"</span><span class="operator">></span>
<span class="operator"><</span><span class="keyword">namespace</span><span class="operator">></span>mycompany<span class="operator">.</span>com<span class="operator">.</span>myapplication<span class="operator">.</span><span class="number">1.0</span><span class="operator"><</span><span class="operator">/</span><span class="keyword">namespace</span><span class="operator">></span>
<span class="operator"><</span>virtualFolder<span class="operator">></span>doc<span class="operator"><</span><span class="operator">/</span>virtualFolder<span class="operator">></span>
<span class="operator"><</span>customFilter name<span class="operator">=</span><span class="string">"My Application 1.0"</span><span class="operator">></span>
<span class="operator"><</span>filterAttribute<span class="operator">></span>myapp<span class="operator"><</span><span class="operator">/</span>filterAttribute<span class="operator">></span>
<span class="operator"><</span>filterAttribute<span class="operator">></span><span class="number">1.0</span><span class="operator"><</span><span class="operator">/</span>filterAttribute<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>customFilter<span class="operator">></span>
<span class="operator"><</span>filterSection<span class="operator">></span>
<span class="operator"><</span>filterAttribute<span class="operator">></span>myapp<span class="operator"><</span><span class="operator">/</span>filterAttribute<span class="operator">></span>
<span class="operator"><</span>filterAttribute<span class="operator">></span><span class="number">1.0</span><span class="operator"><</span><span class="operator">/</span>filterAttribute<span class="operator">></span>
<span class="operator"><</span>toc<span class="operator">></span>
<span class="operator"><</span>section title<span class="operator">=</span><span class="string">"My Application Manual"</span> ref<span class="operator">=</span><span class="string">"index.html"</span><span class="operator">></span>
<span class="operator"><</span>section title<span class="operator">=</span><span class="string">"Chapter 1"</span> ref<span class="operator">=</span><span class="string">"doc.html#chapter1"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>section title<span class="operator">=</span><span class="string">"Chapter 2"</span> ref<span class="operator">=</span><span class="string">"doc.html#chapter2"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>section title<span class="operator">=</span><span class="string">"Chapter 3"</span> ref<span class="operator">=</span><span class="string">"doc.html#chapter3"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>section<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>toc<span class="operator">></span>
<span class="operator"><</span>keywords<span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"foo"</span> id<span class="operator">=</span><span class="string">"MyApplication::foo"</span> ref<span class="operator">=</span><span class="string">"doc.html#foo"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"bar"</span> ref<span class="operator">=</span><span class="string">"doc.html#bar"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword id<span class="operator">=</span><span class="string">"MyApplication::foobar"</span> ref<span class="operator">=</span><span class="string">"doc.html#foobar"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>keywords<span class="operator">></span>
<span class="operator"><</span>files<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span>classic<span class="operator">.</span>css<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span><span class="operator">*</span><span class="operator">.</span>html<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>files<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>filterSection<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span><span class="type">QtHelpProject</span><span class="operator">></span></pre>
<a name="namespace"></a>
<h3 >Namespace</h3>
<p>To enable the <a href="qhelpengine.html">QHelpEngine</a> to retrieve the proper documentation to a given link, every documentation set has to have a unique identifier. A unique identifier makes is also possible for the help collection to keep track of a documentation set without relying on its file name. The Qt help system uses a namespace as identifier which is defined by the mandatory namespace tags. In the example above, the namespace is "mycompany.com.myapplication.1.0".</p>
<a name="virtual-folders"></a><a name="virtual-folders"></a>
<h3 >Virtual Folders</h3>
<p>Having a namespace for every documentation naturally means that the documentation sets are quite separated. From the help engines point of view this is beneficial, but from the documentors view it is often desirable to cross reference certain topic from one manual to another without having to specify absolute links. To solve this problem, the help system introduced the concept of virtual folders.</p>
<p>A virtual folder will become the root directory of all files referenced in a compressed help file. When two documentations share the same virtual folder, they can use relative paths when defining hyperlinks pointing to the other documentation. If a file is contained in both documentations or manuals, the one from the current manual has precedence over the other.</p>
<pre class="cpp"><span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="operator"><</span>virtualFolder<span class="operator">></span>doc<span class="operator"><</span><span class="operator">/</span>virtualFolder<span class="operator">></span>
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span></pre>
<p>The above example specifies 'doc' as virtual folder. If another manual, e.g. for a small helper tool for 'My Application' specifies the same folder, it is sufficient to write 'doc.html#section1' to reference the first section in the 'My Application' manual.</p>
<p>The virtual folder tag is mandatory and the folder must not contain any '/'.</p>
<a name="custom-filters"></a><a name="custom-filters"></a>
<h3 >Custom Filters</h3>
<p>Next in the Qt help project file are the optional definitions of custom filters. A custom filter contains a list of filter attributes which will be used later to display only the documentation which has all those attributes assigned to. So, when setting the current filter in the <a href="qhelpengine.html">QHelpEngine</a> to "My Application 1.0" only the documentation which has "myapp" and "1.0" set as filter attributes will be shown.</p>
<pre class="cpp"><span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="operator"><</span>customFilter name<span class="operator">=</span><span class="string">"My Application 1.0"</span><span class="operator">></span>
<span class="operator"><</span>filterAttribute<span class="operator">></span>myapp<span class="operator"><</span><span class="operator">/</span>filterAttribute<span class="operator">></span>
<span class="operator"><</span>filterAttribute<span class="operator">></span><span class="number">1.0</span><span class="operator"><</span><span class="operator">/</span>filterAttribute<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>customFilter<span class="operator">></span>
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span></pre>
<p>It is possible to define any number of custom filters in a help project file. Important to know is, that the filter attributes have not to be specified in the same project file; they can be defined in any other help file. The definition of a filter attributes takes place by specifying them in a filter section.</p>
<a name="filter-section"></a><a name="filter-section"></a>
<h3 >Filter Section</h3>
<p>A filter section contains the actual documentation. One Qt help project file may contain more than one filter sections. Every filter section consists of four parts, the filter attributes section, the table of contents, the keywords and the files list. In theory all parts are optional but not specifying anything there will result in an empty documentation.</p>
<a name="filter-attributes"></a>
<h4 >Filter Attributes</h4>
<p>Every filter section should have filter attributes assigned to it, to enable documentation filtering. If no filter attribute is defined, the documentation will only be shown if no filtering occurs, meaning the current custom filter in the <a href="qhelpengine.html">QHelpEngine</a> does not contain any filter attributes.</p>
<pre class="cpp"><span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="operator"><</span>filterSection<span class="operator">></span>
<span class="operator"><</span>filterAttribute<span class="operator">></span>myapp<span class="operator"><</span><span class="operator">/</span>filterAttribute<span class="operator">></span>
<span class="operator"><</span>filterAttribute<span class="operator">></span><span class="number">1.0</span><span class="operator"><</span><span class="operator">/</span>filterAttribute<span class="operator">></span>
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span></pre>
<p>In this case, the filter attributes 'myapp' and '1.0' are assigned to the filter section, i.e. all contents specified in this section will only be shown if the current custom filter has 'myapp' or '1.0' or both as filter attributes.</p>
<a name="table-of-contents"></a>
<h4 >Table of contents</h4>
<pre class="cpp"><span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="operator"><</span>toc<span class="operator">></span>
<span class="operator"><</span>section title<span class="operator">=</span><span class="string">"My Application Manual"</span> ref<span class="operator">=</span><span class="string">"index.html"</span><span class="operator">></span>
<span class="operator"><</span>section title<span class="operator">=</span><span class="string">"Chapter 1"</span> ref<span class="operator">=</span><span class="string">"doc.html#chapter1"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>section title<span class="operator">=</span><span class="string">"Chapter 2"</span> ref<span class="operator">=</span><span class="string">"doc.html#chapter2"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>section title<span class="operator">=</span><span class="string">"Chapter 3"</span> ref<span class="operator">=</span><span class="string">"doc.html#chapter3"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>section<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>toc<span class="operator">></span>
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span></pre>
<p>One section tag represents one item in the table of contents. The sections can be nested to any degree, but from a users perspective it should not be more than four or five levels. A section is defined by its title and reference. The reference, like all file references in a Qt help project, are relative to the help project file itself.</p>
<p><b>Note: </b>The referenced files must be inside the same directory (or within a subdirectory) as the help project file. An absolute file path is not supported either.</p><a name="keywords"></a>
<h4 >Keywords</h4>
<pre class="cpp"><span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="operator"><</span>keywords<span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"foo"</span> id<span class="operator">=</span><span class="string">"MyApplication::foo"</span> ref<span class="operator">=</span><span class="string">"doc.html#foo"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword name<span class="operator">=</span><span class="string">"bar"</span> ref<span class="operator">=</span><span class="string">"doc.html#bar"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span>keyword id<span class="operator">=</span><span class="string">"MyApplication::foobar"</span> ref<span class="operator">=</span><span class="string">"doc.html#foobar"</span><span class="operator">/</span><span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>keywords<span class="operator">></span>
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span></pre>
<p>The keyword section lists all keywords of this filter section. A keyword consists basically of a name and a file reference. If the attribute 'name' is used then the keyword specified there will appear in the visible index, i.e. it will be accessible through the <a href="qhelpindexmodel.html">QHelpIndexModel</a>. If 'id' is used, the keyword does not appear in the index and is only accessible via the linksForIdentifier() function of the <a href="qhelpenginecore.html">QHelpEngineCore</a>. 'name' and 'id' can be specified at the same time.</p>
<a name="files"></a>
<h4 >Files</h4>
<pre class="cpp"><span class="operator">.</span><span class="operator">.</span><span class="operator">.</span>
<span class="operator"><</span>files<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span>classic<span class="operator">.</span>css<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span>file<span class="operator">></span><span class="operator">*</span><span class="operator">.</span>html<span class="operator"><</span><span class="operator">/</span>file<span class="operator">></span>
<span class="operator"><</span><span class="operator">/</span>files<span class="operator">></span>
<span class="operator">.</span><span class="operator">.</span><span class="operator">.</span></pre>
<p>Finally, the actual documentation files have to be listed. Make sure that all files neccessary to display the help are mentioned, i.e. stylesheets or similar files need to be there as well. The files, like all file references in a Qt help project, are relative to the help project file itself. As the example shows, files (but not directories) can also be specified as patterns using wildcards. All listed files will be compressed and written to the Qt compressed help file. So, in the end, one single Qt help file contains all documentation files along with the contents and indices.</p>
<p><b>Note: </b>The referenced files must be inside the same directory (or within a subdirectory) as the help project file. An absolute file path is not supported either.</p></div>
<!-- @@@qthelpproject.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2015 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
|