doc/src/qthelp.qdoc

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
   4 ** All rights reserved.
   5 ** Contact: Nokia Corporation (qt-info@nokia.com)
   6 **
   7 ** This file is part of the documentation of the Qt Toolkit.
   8 **
   9 ** $QT_BEGIN_LICENSE:LGPL$
  10 ** No Commercial Usage
  11 ** This file contains pre-release code and may not be distributed.
  12 ** You may use this file in accordance with the terms and conditions
  13 ** contained in the Technology Preview License Agreement accompanying
  14 ** this package.
  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 ** If you have questions regarding the use of this file, please contact
  29 ** Nokia at qt-info@nokia.com.
  30 **
  31 **
  32 **
  33 **
  34 **
  35 **
  36 **
  37 **
  38 ** $QT_END_LICENSE$
  39 **
  40 ****************************************************************************/
  41
  42 /*!
  43     \module QtHelp
  44     \title QtHelp Module
  45     \contentspage Qt's Modules
  46     \previouspage QtUiTools
  47     \nextpage QtAssistant
  48     \ingroup modules
  49
  50     \brief The QtHelp module provides classes for integrating
  51     online documentation in applications.
  52
  53     To include the definitions of the module's classes, use the
  54     following directive:
  55
  56     \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 0
  57
  58     To link against the module, add this line to your \l qmake \c
  59     .pro file:
  60
  61     \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 1
  62
  63     \note These classes are part of the \l{Open Source Versions of Qt} and
  64     \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial
  65     users.
  66
  67     \section1 Topics
  68
  69     \tableofcontents
  70
  71     \section1 Overview
  72     The Qt help system includes tools for generating and viewing
  73     Qt help files. In addition it provides classes for accessing
  74     help contents programatically to be able to integrate online
  75     help into Qt applications.
  76
  77     The actual help data, meaning the table of contents, index
  78     keywords or html documents, is contained in Qt compressed help
  79     files. So, one such a help file represents usually one manual
  80     or documentation set. Since most products are more comprehensive
  81     and consist of a number of tools, one manual is rarely enough.
  82     Instead, more manuals which should be accessible at the same
  83     time, exist. Ideally, it should also be possible to reference
  84     certain points of interest of one manual to another.
  85     Therefore, the Qt help system operates on help collection files
  86     which include any number of compressed help files.
  87
  88     However, having collection files to merge many documentation
  89     sets may lead to some problems. For example, one index keyword
  90     may be defined in different documentations. So, when only seeing
  91     it in the index and activating it, you cannot be sure that
  92     the expected documentation will be shown. Therefore, the Qt
  93     help system offers the possibiltiy to filter the help contents
  94     after certain attributes. This requires however, that the
  95     attributes have been assigned to the help contents before the
  96     generation of the compressed help file.
  97
  98     As already mentioned, the Qt compressed help file contains all
  99     data, so there is no need any longer to ship all single html
 100     files. Instead, only the compressed help file and optionally the
 101     collection file has to be distributed. The collection file is
 102     optional since any existing collection file, e.g. from an older
 103     release could be used.
 104
 105     So, in general, there are four files interacting with the help
 106     system, two used for generating Qt help and two meant for
 107     distribution:
 108
 109     \table
 110         \header
 111             \o Name
 112             \o Extension
 113             \o Brief Description
 114         \row
 115             \o \l {Qt Help Project}
 116             \o .qhp
 117             \o The input file for the help generator consisting of the table
 118                of contents, indices and references to the actual documentation
 119                files (*.html); it also defines a unique namespace for the
 120                documentation.
 121
 122         \row
 123             \o Qt Compressed Help
 124             \o .qch
 125             \o The output file of the help generator. This binary file contains
 126                all information specified in the help project file along with all
 127                compressed documentation files.
 128
 129         \row
 130             \o \l {Qt Help Collection Project}
 131             \o .qhcp
 132             \o The input file for the help collection generator. It contains
 133                references to compressed help files which should be included in
 134                the collection; it also may contain other information for
 135                customizing Qt Assistant.
 136
 137         \row
 138             \o Qt Help Collection
 139             \o .qhc
 140             \o The output of the help collection generator. This is the file
 141                QHelpEngine operates on. It contains references to any number of
 142                compressed help files as well as additional information, such as
 143                custom filters.
 144     \endtable
 145
 146     \section1 Generating Qt Help
 147
 148     Building help files for the Qt help system assumes that the html
 149     documentation files already exist, i.e. the Qt help system does
 150     not offer the possibility to create html files like e.g. Doxygen.
 151
 152     Once the html documentents are in place, a \l {Qt Help Project} file
 153     has to be created. After specifying all relevant information in
 154     this file, it needs to be compiled by calling:
 155
 156     \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 2
 157
 158     The file 'doc.qch' contains then all html files in compressed
 159     form along with the table of contents and index keywords. To
 160     test if the generated file is correct, open Qt Assistant and
 161     install the file via the Settings|Documentation page.
 162
 163     \target Qt Help Collection Project
 164     \section2 Creating a Qt Help Collection
 165
 166     The first step is to create a Qt Help Collection Project file.
 167     Since a Qt help collection stores primarily references to
 168     compressed help files, the project 'mycollection.qhcp' file
 169     looks unsurprisingly simple:
 170
 171     \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 3
 172
 173     For actually creating the collection file call:
 174
 175     \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 4
 176
 177     Instead of running two tools, one for generating the compressed
 178     help and one for generating the collection file, it is also
 179     possible to just run the qcollectiongenerator tool with a
 180     slightly modified project file instructing the generator to
 181     create the compressed help first.
 182
 183     \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 5
 184
 185     Of course, it is possible to specify more than one file in the
 186     'generate' or 'register' section, so any number of compressed
 187     help files can be generated and registered in one go.
 188
 189     \section1 Using Qt Help
 190
 191     Accessing the help contents can be done in two ways: Using Qt
 192     Assistant as documentation browser or using the QHelpEngine
 193     API for embedding the help contents directly in an application.
 194
 195     \section2 Using Qt Assistant
 196
 197     \QA operates on a collection file which can be specified
 198     before start up. If no collection file is given, a default one
 199     will be created and used. In either case, it is possible to
 200     register any Qt compressed help file and access the help contents.
 201
 202     When using Assistant as the help browser for an application, it
 203     would be desirable that it can be customized to fit better to the
 204     application and doesn't look like an independent, standalone
 205     help browser. To achieve this, several additional properties can
 206     be set in an Qt help collection file, to change e.g. the title
 207     or application icon of Qt Assistant. For more information on
 208     this topic have a look at the \l{assistant-manual.html}
 209     {Qt Assistant manual}.
 210
 211     \section2 Using QHelpEngine API
 212
 213     Instead of showing the help in an external application like the
 214     Qt Assistant, it is also possible to embed the online help in
 215     the application. The contents can then be retrieved via the
 216     QHelpEngine class and can be displayed in nearly any form.
 217     Showing it in a QTextBrowser is probably the most common way, but
 218     embedding it in What's This help is also perfectly possible.
 219
 220     Retrieving help data from the file engine does not involve a
 221     lot of code. The first step is to create an instance of the
 222     help engine. Then we ask the engine for the links assigned to
 223     the identifier, in this case "MyDialog::ChangeButton". If a link
 224     was found, meaning at least one help document exists to this topic,
 225     we get the actual help contents by calling fileData() and display
 226     the document to the user.
 227
 228     \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 6
 229
 230     For further information on how to use the API, have a look at
 231     the QHelpEngine class reference.
 232
 233     \section1 License Information
 234
 235     The QtHelp module uses the CLucene indexing library to provide full-text
 236     searching capabilities for Qt Assistant and applications that use the
 237     features of QtHelp.
 238
 239     Qt Commercial Edition licensees that wish to distribute applications that
 240     use these features of the QtHelp module need to be aware of their
 241     obligations under the GNU Lesser General Public License (LGPL).
 242
 243     Developers using the Open Source Edition can choose to redistribute
 244     the module under the appropriate version of the GNU LGPL; version 2.1
 245     for applications and libraries licensed under the GNU GPL version 2,
 246     or version 3 for applications and libraries licensed under the GNU
 247     GPL version 3.
 248
 249     \legalese
 250     Copyright (C) 2003-2006 Ben van Klinken and the CLucene Team \BR
 251     Changes are Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
 252
 253     This library is free software; you can redistribute it and/or
 254     modify it under the terms of the GNU Lesser General Public
 255     License as published by the Free Software Foundation; either
 256     version 2.1 of the License, or (at your option) any later version.
 257
 258     This library is distributed in the hope that it will be useful,
 259     but WITHOUT ANY WARRANTY; without even the implied warranty of
 260     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 261     Lesser General Public License for more details.
 262
 263     You should have received a copy of the GNU Lesser General Public
 264     License along with this library; if not, write to the Free Software
 265     Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 266     \endlegalese
 267 */
 268
 269 /*!
 270     \page qthelpproject.html
 271     \title Qt Help Project
 272
 273     A Qt help project collects all data necessary to generate a
 274     compressed help file. Along with the actual help data, like
 275     the table of contents, index keywords and help documents, it
 276     contains some extra information like a namespace to identify
 277     the help file. One help project stands for one documentation,
 278     e.g. the Qt Assistant manual.
 279
 280     \section1 Qt Help Project File Format
 281
 282     The file format is XML based. For a better understanding of
 283     the format we'll discuss the following example:
 284
 285     \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 7
 286
 287     \section2 Namespace
 288
 289     To enable the QHelpEngine to retrieve the proper documentation to
 290     a given link, every documentation set has to have a unique
 291     identifier. A unique identifier makes is also possible for the
 292     help collection to keep track of a documentation set without relying
 293     on its file name. The Qt help system uses a namespace as identifier
 294     which is defined by the mandatory namespace tags. In the example
 295     above, the namespace is "mycompany.com.myapplication.1_0".
 296
 297     \target Virtual Folders
 298     \section2 Virtual Folders
 299
 300     Having a namespace for every documentation naturally means that
 301     the documentation sets are quite separated. From the help engines
 302     point of view this is beneficial, but from the documentors view
 303     it is often desirable to cross reference certain topic from one
 304     manual to another without having to specify absolute links. To
 305     solve this problem, the help system introduced the concept of
 306     virtual folders.
 307
 308     A virtual folder will become the root directory of all files
 309     referenced in a compressed help file. When two documentations
 310     share the same virtual folder, they can use relative paths when
 311     defining hyperlinks pointing to the other documentation. If a
 312     file is contained in both documentations or manuals, the one
 313     from the current manual has precedence over the other.
 314
 315     \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 8
 316
 317     The above example specifies 'doc' as virtual folder. If another
 318     manual, e.g. for a small helper tool for 'My Application'
 319     specifies the same folder, it is sufficient to write
 320     'doc.html#section1' to reference the first section in the
 321     'My Application' manual.
 322
 323     The virtual folder tag is mandatory and the folder must not
 324     contain any '/'.
 325
 326     \target Custom Filters
 327     \section2 Custom Filters
 328
 329     Next in the Qt help project file are the optional definitions of
 330     custom filters. A custom filter contains a list of filter
 331     attributes which will be used later to display only the documentation
 332     which has all those attributes assigned to. So, when setting the
 333     current filter in the QHelpEngine to "My Application 1.0" only
 334     the documentation which has "myapp" and "1.0" set as filter
 335     attributes will be shown.
 336
 337     \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 9
 338
 339     It is possible to define any number of custom filters in a help
 340     project file. Important to know is, that the filter attributes have
 341     not to be specified in the same project file; they can be defined
 342     in any other help file. The definition of a filter attributes
 343     takes place by specifying them in a filter section.
 344
 345     \target Filter Section
 346     \section2 Filter Section
 347
 348     A filter section contains the actual documentation. One Qt help project
 349     file may contain more than one filter sections. Every filter section
 350     consists of four parts, the filter attributes section, the table of
 351     contents, the keywords and the files list. In theory all parts are
 352     optional but not specifying anything there will result in an empty
 353     documentation.
 354
 355     \section3 Filter Attributes
 356
 357     Every filter section should have filter attributes assigned to it, to
 358     enable documentation filtering. If no filter attribute is defined, the
 359     documentation will only be shown if no filtering occurs, meaning the
 360     current custom filter in the QHelpEngine does not contain any filter
 361     attributes.
 362
 363     \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 10
 364
 365     In this case, the filter attributes 'myapp' and '1.0' are assigned
 366     to the filter section, i.e. all contents specified in this section
 367     will only be shown if the current custom filter has 'myapp' or '1.0'
 368     or both as filter attributes.
 369
 370     \section3 Table of contents
 371
 372     \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 11
 373
 374     One section tag represents one item in the table of contents. The
 375     sections can be nested to any degree, but from a users perspective
 376     it should not be more than four or five levels. A section is defined
 377     by its title and reference. The reference, like all file references in a Qt
 378     help project, are relative to the help project file itself.
 379     \note The referenced files must be inside the same directory (or within a
 380     subdirectory) as the help project file. An absolute file path is not supported
 381     either.
 382
 383     \section3 Keywords
 384
 385     \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 12
 386
 387     The keyword section lists all keywords of this filter section. A
 388     keyword consists basically of a name and a file reference. If the
 389     attribute 'name' is used then the keyword specified there will appear in
 390     the visible index, i.e. it will be accessible through the QHelpIndexModel.
 391     If 'id' is used, the keyword does not appear in the index and is
 392     only accessible via the linksForIdentifier() function of the
 393     QHelpEngineCore. 'name' and 'id' can be specified at the same time.
 394
 395     \section3 Files
 396
 397     \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 13
 398
 399     Finally, the actual documentation files have to be listed. Make sure
 400     that all files neccessary to display the help are mentioned, i.e.
 401     stylesheets or similar files need to be there as well. The file, like all
 402     file references in a Qt help project, are relative to the help project file
 403     itself. All listed files will be compressed and written to the Qt compressed
 404     help file. So, in the end, one single Qt help file contains all
 405     documentation files along with the contents and indices. \note The
 406     referenced files must be inside the same directory (or within a subdirectory)
 407     as the help project file. An absolute file path is not supported either.
 408 */