source: trunk/doc/src/frameworks-technologies/qthelp.qdoc@ 568

Last change on this file since 568 was 561, checked in by Dmitry A. Kuminov, 15 years ago

trunk: Merged in qt 4.6.1 sources.

  • Property svn:eol-style set to native
File size: 16.3 KB
Line 
1/****************************************************************************
2**
3** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
4** All rights reserved.
5** Contact: Nokia Corporation ([email protected])
6**
7** This file is part of the documentation of the Qt Toolkit.
8**
9** $QT_BEGIN_LICENSE:LGPL$
10** Commercial Usage
11** Licensees holding valid Qt Commercial licenses may use this file in
12** accordance with the Qt Commercial License Agreement provided with the
13** Software or, alternatively, in accordance with the terms contained in
14** a written agreement between you and Nokia.
15**
16** GNU Lesser General Public License Usage
17** Alternatively, this file may be used under the terms of the GNU Lesser
18** General Public License version 2.1 as published by the Free Software
19** Foundation and appearing in the file LICENSE.LGPL included in the
20** packaging of this file. Please review the following information to
21** ensure the GNU Lesser General Public License version 2.1 requirements
22** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
23**
24** In addition, as a special exception, Nokia gives you certain additional
25** rights. These rights are described in the Nokia Qt LGPL Exception
26** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
27**
28** GNU General Public License Usage
29** Alternatively, this file may be used under the terms of the GNU
30** General Public License version 3.0 as published by the Free Software
31** Foundation and appearing in the file LICENSE.GPL included in the
32** packaging of this file. Please review the following information to
33** ensure the GNU General Public License version 3.0 requirements will be
34** met: http://www.gnu.org/copyleft/gpl.html.
35**
36** If you have questions regarding the use of this file, please contact
37** Nokia at [email protected].
38** $QT_END_LICENSE$
39**
40****************************************************************************/
41
42/*!
43 \group helpsystem
44 \title Help System
45 \ingroup groups
46
47 \brief Classes used to provide online-help for applications.
48
49 \keyword help system
50
51 These classes provide for all forms of online-help in your application,
52 with three levels of detail:
53
54 \list 1
55 \o Tool Tips and Status Bar message - flyweight help, extremely brief,
56 entirely integrated in the user interface, requiring little
57 or no user interaction to invoke.
58 \o What's This? - lightweight, but can be
59 a three-paragraph explanation.
60 \o Online Help - can encompass any amount of information,
61 but is typically slower to call up, somewhat separated
62 from the user's work, and often users feel that using online
63 help is a digression from their real task.
64 \endlist
65
66*/
67
68/*!
69 \page qthelp-framework.html
70 \title The Qt Help Framework
71 \brief Integrating Documentation in Applications
72 \ingroup frameworks-technologies
73
74 \section1 Topics
75
76 \tableofcontents
77
78 \section1 Overview
79 The Qt help system includes tools for generating and viewing
80 Qt help files. In addition it provides classes for accessing
81 help contents programatically to be able to integrate online
82 help into Qt applications.
83
84 The actual help data, meaning the table of contents, index
85 keywords or html documents, is contained in Qt compressed help
86 files. So, one such a help file represents usually one manual
87 or documentation set. Since most products are more comprehensive
88 and consist of a number of tools, one manual is rarely enough.
89 Instead, more manuals which should be accessible at the same
90 time, exist. Ideally, it should also be possible to reference
91 certain points of interest of one manual to another.
92 Therefore, the Qt help system operates on help collection files
93 which include any number of compressed help files.
94
95 However, having collection files to merge many documentation
96 sets may lead to some problems. For example, one index keyword
97 may be defined in different documentations. So, when only seeing
98 it in the index and activating it, you cannot be sure that
99 the expected documentation will be shown. Therefore, the Qt
100 help system offers the possibiltiy to filter the help contents
101 after certain attributes. This requires however, that the
102 attributes have been assigned to the help contents before the
103 generation of the compressed help file.
104
105 As already mentioned, the Qt compressed help file contains all
106 data, so there is no need any longer to ship all single html
107 files. Instead, only the compressed help file and optionally the
108 collection file has to be distributed. The collection file is
109 optional since any existing collection file, e.g. from an older
110 release could be used.
111
112 So, in general, there are four files interacting with the help
113 system, two used for generating Qt help and two meant for
114 distribution:
115
116 \table
117 \header
118 \o Name
119 \o Extension
120 \o Brief Description
121 \row
122 \o \l {Qt Help Project}
123 \o .qhp
124 \o The input file for the help generator consisting of the table
125 of contents, indices and references to the actual documentation
126 files (*.html); it also defines a unique namespace for the
127 documentation.
128
129 \row
130 \o Qt Compressed Help
131 \o .qch
132 \o The output file of the help generator. This binary file contains
133 all information specified in the help project file along with all
134 compressed documentation files.
135
136 \row
137 \o \l {Qt Help Collection Project}
138 \o .qhcp
139 \o The input file for the help collection generator. It contains
140 references to compressed help files which should be included in
141 the collection; it also may contain other information for
142 customizing Qt Assistant.
143
144 \row
145 \o Qt Help Collection
146 \o .qhc
147 \o The output of the help collection generator. This is the file
148 QHelpEngine operates on. It contains references to any number of
149 compressed help files as well as additional information, such as
150 custom filters.
151 \endtable
152
153 \section1 Generating Qt Help
154
155 Building help files for the Qt help system assumes that the html
156 documentation files already exist, i.e. the Qt help system does
157 not offer the possibility to create html files like e.g. Doxygen.
158
159 Once the html documentents are in place, a \l {Qt Help Project} file
160 has to be created. After specifying all relevant information in
161 this file, it needs to be compiled by calling:
162
163 \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 2
164
165 The file 'doc.qch' contains then all html files in compressed
166 form along with the table of contents and index keywords. To
167 test if the generated file is correct, open Qt Assistant and
168 install the file via the Settings|Documentation page.
169
170 \target Qt Help Collection Project
171 \section2 Creating a Qt Help Collection
172
173 The first step is to create a Qt Help Collection Project file.
174 Since a Qt help collection stores primarily references to
175 compressed help files, the project 'mycollection.qhcp' file
176 looks unsurprisingly simple:
177
178 \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 3
179
180 For actually creating the collection file call:
181
182 \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 4
183
184 Instead of running two tools, one for generating the compressed
185 help and one for generating the collection file, it is also
186 possible to just run the qcollectiongenerator tool with a
187 slightly modified project file instructing the generator to
188 create the compressed help first.
189
190 \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 5
191
192 Of course, it is possible to specify more than one file in the
193 'generate' or 'register' section, so any number of compressed
194 help files can be generated and registered in one go.
195
196 \section1 Using Qt Help
197
198 Accessing the help contents can be done in two ways: Using Qt
199 Assistant as documentation browser or using the QHelpEngine
200 API for embedding the help contents directly in an application.
201
202 \section2 Using Qt Assistant
203
204 \QA operates on a collection file which can be specified
205 before start up. If no collection file is given, a default one
206 will be created and used. In either case, it is possible to
207 register any Qt compressed help file and access the help contents.
208
209 When using Assistant as the help browser for an application, it
210 would be desirable that it can be customized to fit better to the
211 application and doesn't look like an independent, standalone
212 help browser. To achieve this, several additional properties can
213 be set in an Qt help collection file, to change e.g. the title
214 or application icon of Qt Assistant. For more information on
215 this topic have a look at the \l{assistant-manual.html}
216 {Qt Assistant manual}.
217
218 \section2 Using QHelpEngine API
219
220 Instead of showing the help in an external application like the
221 Qt Assistant, it is also possible to embed the online help in
222 the application. The contents can then be retrieved via the
223 QHelpEngine class and can be displayed in nearly any form.
224 Showing it in a QTextBrowser is probably the most common way, but
225 embedding it in What's This help is also perfectly possible.
226
227 Retrieving help data from the file engine does not involve a
228 lot of code. The first step is to create an instance of the
229 help engine. Then we ask the engine for the links assigned to
230 the identifier, in this case "MyDialog::ChangeButton". If a link
231 was found, meaning at least one help document exists to this topic,
232 we get the actual help contents by calling fileData() and display
233 the document to the user.
234
235 \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 6
236
237 For further information on how to use the API, have a look at
238 the QHelpEngine class reference.
239*/
240
241/*!
242 \page qthelpproject.html
243 \title Qt Help Project
244
245 A Qt help project collects all data necessary to generate a
246 compressed help file. Along with the actual help data, like
247 the table of contents, index keywords and help documents, it
248 contains some extra information like a namespace to identify
249 the help file. One help project stands for one documentation,
250 e.g. the Qt Assistant manual.
251
252 \section1 Qt Help Project File Format
253
254 The file format is XML-based. For a better understanding of
255 the format we'll discuss the following example:
256
257 \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 7
258
259 \section2 Namespace
260
261 To enable the QHelpEngine to retrieve the proper documentation to
262 a given link, every documentation set has to have a unique
263 identifier. A unique identifier makes is also possible for the
264 help collection to keep track of a documentation set without relying
265 on its file name. The Qt help system uses a namespace as identifier
266 which is defined by the mandatory namespace tags. In the example
267 above, the namespace is "mycompany.com.myapplication.1_0".
268
269 \target Virtual Folders
270 \section2 Virtual Folders
271
272 Having a namespace for every documentation naturally means that
273 the documentation sets are quite separated. From the help engines
274 point of view this is beneficial, but from the documentors view
275 it is often desirable to cross reference certain topic from one
276 manual to another without having to specify absolute links. To
277 solve this problem, the help system introduced the concept of
278 virtual folders.
279
280 A virtual folder will become the root directory of all files
281 referenced in a compressed help file. When two documentations
282 share the same virtual folder, they can use relative paths when
283 defining hyperlinks pointing to the other documentation. If a
284 file is contained in both documentations or manuals, the one
285 from the current manual has precedence over the other.
286
287 \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 8
288
289 The above example specifies 'doc' as virtual folder. If another
290 manual, e.g. for a small helper tool for 'My Application'
291 specifies the same folder, it is sufficient to write
292 'doc.html#section1' to reference the first section in the
293 'My Application' manual.
294
295 The virtual folder tag is mandatory and the folder must not
296 contain any '/'.
297
298 \target Custom Filters
299 \section2 Custom Filters
300
301 Next in the Qt help project file are the optional definitions of
302 custom filters. A custom filter contains a list of filter
303 attributes which will be used later to display only the documentation
304 which has all those attributes assigned to. So, when setting the
305 current filter in the QHelpEngine to "My Application 1.0" only
306 the documentation which has "myapp" and "1.0" set as filter
307 attributes will be shown.
308
309 \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 9
310
311 It is possible to define any number of custom filters in a help
312 project file. Important to know is, that the filter attributes have
313 not to be specified in the same project file; they can be defined
314 in any other help file. The definition of a filter attributes
315 takes place by specifying them in a filter section.
316
317 \target Filter Section
318 \section2 Filter Section
319
320 A filter section contains the actual documentation. One Qt help project
321 file may contain more than one filter sections. Every filter section
322 consists of four parts, the filter attributes section, the table of
323 contents, the keywords and the files list. In theory all parts are
324 optional but not specifying anything there will result in an empty
325 documentation.
326
327 \section3 Filter Attributes
328
329 Every filter section should have filter attributes assigned to it, to
330 enable documentation filtering. If no filter attribute is defined, the
331 documentation will only be shown if no filtering occurs, meaning the
332 current custom filter in the QHelpEngine does not contain any filter
333 attributes.
334
335 \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 10
336
337 In this case, the filter attributes 'myapp' and '1.0' are assigned
338 to the filter section, i.e. all contents specified in this section
339 will only be shown if the current custom filter has 'myapp' or '1.0'
340 or both as filter attributes.
341
342 \section3 Table of contents
343
344 \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 11
345
346 One section tag represents one item in the table of contents. The
347 sections can be nested to any degree, but from a users perspective
348 it should not be more than four or five levels. A section is defined
349 by its title and reference. The reference, like all file references in a Qt
350 help project, are relative to the help project file itself.
351 \note The referenced files must be inside the same directory (or within a
352 subdirectory) as the help project file. An absolute file path is not supported
353 either.
354
355 \section3 Keywords
356
357 \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 12
358
359 The keyword section lists all keywords of this filter section. A
360 keyword consists basically of a name and a file reference. If the
361 attribute 'name' is used then the keyword specified there will appear in
362 the visible index, i.e. it will be accessible through the QHelpIndexModel.
363 If 'id' is used, the keyword does not appear in the index and is
364 only accessible via the linksForIdentifier() function of the
365 QHelpEngineCore. 'name' and 'id' can be specified at the same time.
366
367 \section3 Files
368
369 \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 13
370
371 Finally, the actual documentation files have to be listed. Make sure
372 that all files neccessary to display the help are mentioned, i.e.
373 stylesheets or similar files need to be there as well. The files, like all
374 file references in a Qt help project, are relative to the help project file
375 itself. As the example shows, files (but not directories) can also be
376 specified as patterns using wildcards. All listed files will be compressed
377 and written to the Qt compressed help file. So, in the end, one single Qt
378 help file contains all documentation files along with the contents and
379 indices. \note The referenced files must be inside the same directory
380 (or within a subdirectory) as the help project file. An absolute file path
381 is not supported either.
382*/
Note: See TracBrowser for help on using the repository browser.