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
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
|
// Copyright (C) 2016 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
/*!
\group helpsystem
\title Help System
\ingroup groups
\brief Classes used to provide online-help for applications.
\keyword help system
These classes provide online-help for your application,
with three levels of detail:
\list 1
\li Tool Tips and Status Bar message - flyweight help, extremely brief,
entirely integrated in the user interface, requiring little
or no user interaction to invoke.
\li What's This? - lightweight, but can be
a three-paragraph explanation.
\li Online Help - can encompass any amount of information,
but is typically slower to call up, somewhat separated
from the user's work, and often users feel that using online
help is a digression from their real task.
\endlist
*/
/*!
\page qthelp-framework.html
\title The Qt Help Framework
\brief Integrating Documentation in Applications
\ingroup frameworks-technologies
\section1 Overview
The Qt help system includes tools for generating and viewing
Qt help files. In addition, it provides classes for accessing
help contents programmatically to be able to integrate online
help into Qt applications.
The actual help data, meaning the table of contents, index
keywords, or HTML documents, is contained in Qt compressed help
files. So, one such a help file represents usually one manual
or documentation set. Since most products are more comprehensive
and consist of a number of tools, one manual is rarely enough.
Instead, more manuals, which should be accessible at the same
time, exist. Ideally, it should also be possible to reference
certain points of interest of one manual to another.
Therefore, the Qt help system operates on help collection files,
which include any number of compressed help files.
However, having collection files to merge many documentation
sets may lead to some problems. For example, one index keyword
may be defined in different documentation sets. So, when only seeing
a keyword in the index and activating it, you cannot be sure that
the expected documentation will be shown. Therefore, the Qt
help system offers the possibility to filter the help contents
after certain attributes. This requires, however, that the
attributes have been assigned to the help contents before the
generation of the compressed help file.
As already mentioned, the Qt compressed help file contains all
data, so there is no need any longer to ship all the single HTML
files. Instead, only the compressed help file and, optionally, the
collection file have to be distributed. The collection file is
optional since any existing collection file, for example from an older
release, could be used.
So, in general, there are four files interacting with the help
system, two used for generating Qt help and two meant for
distribution:
\table
\header
\li Name
\li Extension
\li Brief Description
\row
\li \l {Qt Help Project}
\li .qhp
\li Contains the table of contents, indices, and references to the
actual documentation files (*.html). It also defines a unique
namespace for the documentation. This file is passed to the help
generator for creating a compressed help file.
\row
\li Qt Compressed Help
\li .qch
\li Contains all the information specified in the help project file
along with all the compressed documentation files.
\row
\li \l {Qt Help Collection Project}
\li .qhcp
\li An XML file that contains references to the compressed help
files that should be included in the help collection. This file
can be passed to the help generator for creating a help collection
file.
\row
\li Qt Help Collection
\li .qhc
\li The help collection file that QHelpEngine operates on. It can
contain references to any number of compressed help files as
well as additional information.
\endtable
\section1 Generating Qt Help
Building help files for the Qt help system assumes that the HTML
documentation files already exist.
Once the HTML documents are in place, a \l {Qt Help Project} file, with
an extension of \c .qhp, has to be created. After specifying all the relevant
information in this file, it needs to be compiled by calling:
\snippet doc_src_qthelp.qdoc 2
The file \e doc.qch contains all the HTML files in compressed
form along with the table of contents and index keywords. To
test if the generated file is correct, open Qt Assistant and
install the file in \uicontrol Settings > \uicontrol Documentation.
For the standard Qt source build, the .qhp file is generated and placed
in the same directory as the HTML pages.
\target Qt Help Collection Project
\section2 Creating a Qt Help Collection
The first step is to create a Qt Help Collection Project file.
Since a Qt help collection stores primarily references to
compressed help files, the project \e mycollection.qhcp file
looks unsurprisingly simple:
\snippet doc_src_qthelp.qdoc 3
For actually creating the collection file call:
\snippet doc_src_qthelp.qdoc 4
To generate both the compressed help and the collection file in one go,
modify the help collection project file so that it instructs the help
generator to create the compressed help first:
\snippet doc_src_qthelp.qdoc 5
Of course, it is possible to specify more than one file in the
\c generate or \c register section, so any number of compressed
help files can be generated and registered in one go.
\section1 Using QHelpEngine API
QHelpEngine allows embedding the help contents directly in an
application.
Instead of showing the help in an external application such as a
web browser, it is also possible to embed the online help in
the application. The contents can then be retrieved via the
QHelpEngine class and can be displayed in nearly any form.
Showing the help in a QTextBrowser is probably the most common way, but
embedding it in What's This help is also perfectly possible.
Retrieving help data from the file engine does not involve a
lot of code. The first step is to create an instance of the
help engine. Then we ask the engine for the links assigned to
the identifier, in this case \c MyDialog::ChangeButton. If a link
was found, meaning at least one help document exists on this topic,
we get the actual help contents by calling QHelpEngineCore::fileData() and
display the document to the user.
\snippet doc_src_qthelp.cpp 6
For further information on how to use the API, have a look at
the QHelpEngine class reference.
*/
/*!
\page qthelpproject.html
\title Qt Help Project
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 set,
for example the \l{qmake Manual}.
\section1 Qt Help Project File Format
The file format is XML-based. For a better understanding of
the format we will discuss the following example:
\snippet doc_src_qthelp.qdoc 7
\section2 Namespace
To enable the QHelpEngine to retrieve the proper documentation to
a given link, every documentation set has to have a unique
identifier. A unique identifier also makes it 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".
\target Virtual Folders
\section2 Virtual Folders
Having a namespace for every documentation set naturally means that
the documentation sets are quite separated. From the help engine's
point of view, this is beneficial. However, from the writer's view
it is often desirable to cross reference certain topics from one
manual to another without having to specify absolute links. To
solve this problem, the help system introduced the concept of
virtual folders.
A virtual folder will become the root directory of all files
referenced in a compressed help file. When two documentation sets
share the same virtual folder, they can use relative paths when
defining hyperlinks pointing to each other. If a file is contained
in both documentation sets, the one from the current set has
precedence over the other.
\snippet doc_src_qthelp.qdoc 8
The above example specifies \e doc as virtual folder. If another
manual specifies the same folder, for example for a small helper
tool \e {My Application}, it is sufficient to write
\e {doc.html#section1} to reference the first section in the
\e {My Application} manual.
The virtual folder tag is mandatory and the folder name must not
contain any slashes (/).
\target Filter Section
\section2 Filter Section
A filter section contains the actual documentation. A Qt help project
file may contain more than one filter section. Every filter section
consists of 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 set.
\section3 Table of Contents
\snippet doc_src_qthelp.qdoc 11
One section tag represents one item in the table of contents. The
sections can be nested to any degree, but from a user's 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.
\note The referenced files must be in the same directory as the help
project file (or in a subdirectory). An absolute file path is not supported
either.
\section3 Keywords
\snippet doc_src_qthelp.qdoc 12
The keyword section lists all keywords of this filter section. A
keyword consists basically of a name and a file reference. If the
attribute \e name is used, the keyword specified there will appear in the
visible index. That is, it will be accessible through the QHelpIndexModel
class. If \e id is used, the keyword does not appear in the index and is
only accessible via \l QHelpEngineCore::documentsForIdentifier(). \e name
and \e id can be specified at the same time.
\section3 Files
\snippet doc_src_qthelp.qdoc 13
Finally, the actual documentation files have to be listed. Make sure
that all files necessary to display the help are mentioned. That is,
stylesheets or similar files need to be listed 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. \note The referenced files must be inside the same directory
as the help project file (or in a subdirectory). An absolute file path
is not supported either.
*/
|