| 1 | /****************************************************************************
|
|---|
| 2 | **
|
|---|
| 3 | ** Copyright (C) 2011 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:FDL$
|
|---|
| 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 a
|
|---|
| 14 | ** written agreement between you and Nokia.
|
|---|
| 15 | **
|
|---|
| 16 | ** GNU Free Documentation License
|
|---|
| 17 | ** Alternatively, this file may be used under the terms of the GNU Free
|
|---|
| 18 | ** Documentation License version 1.3 as published by the Free Software
|
|---|
| 19 | ** Foundation and appearing in the file included in the packaging of this
|
|---|
| 20 | ** file.
|
|---|
| 21 | **
|
|---|
| 22 | ** If you have questions regarding the use of this file, please contact
|
|---|
| 23 | ** Nokia at [email protected].
|
|---|
| 24 | ** $QT_END_LICENSE$
|
|---|
| 25 | **
|
|---|
| 26 | ****************************************************************************/
|
|---|
| 27 |
|
|---|
| 28 | /*!
|
|---|
| 29 | \group helpsystem
|
|---|
| 30 | \title Help System
|
|---|
| 31 | \ingroup groups
|
|---|
| 32 |
|
|---|
| 33 | \brief Classes used to provide online-help for applications.
|
|---|
| 34 |
|
|---|
| 35 | \keyword help system
|
|---|
| 36 |
|
|---|
| 37 | These classes provide for all forms of online-help in your application,
|
|---|
| 38 | with three levels of detail:
|
|---|
| 39 |
|
|---|
| 40 | \list 1
|
|---|
| 41 | \o Tool Tips and Status Bar message - flyweight help, extremely brief,
|
|---|
| 42 | entirely integrated in the user interface, requiring little
|
|---|
| 43 | or no user interaction to invoke.
|
|---|
| 44 | \o What's This? - lightweight, but can be
|
|---|
| 45 | a three-paragraph explanation.
|
|---|
| 46 | \o Online Help - can encompass any amount of information,
|
|---|
| 47 | but is typically slower to call up, somewhat separated
|
|---|
| 48 | from the user's work, and often users feel that using online
|
|---|
| 49 | help is a digression from their real task.
|
|---|
| 50 | \endlist
|
|---|
| 51 |
|
|---|
| 52 | */
|
|---|
| 53 |
|
|---|
| 54 | /*!
|
|---|
| 55 | \page qthelp-framework.html
|
|---|
| 56 | \title The Qt Help Framework
|
|---|
| 57 | \brief Integrating Documentation in Applications
|
|---|
| 58 | \ingroup frameworks-technologies
|
|---|
| 59 |
|
|---|
| 60 | \section1 Topics
|
|---|
| 61 |
|
|---|
| 62 | \tableofcontents
|
|---|
| 63 |
|
|---|
| 64 | \section1 Overview
|
|---|
| 65 | The Qt help system includes tools for generating and viewing
|
|---|
| 66 | Qt help files. In addition it provides classes for accessing
|
|---|
| 67 | help contents programatically to be able to integrate online
|
|---|
| 68 | help into Qt applications.
|
|---|
| 69 |
|
|---|
| 70 | The actual help data, meaning the table of contents, index
|
|---|
| 71 | keywords or html documents, is contained in Qt compressed help
|
|---|
| 72 | files. So, one such a help file represents usually one manual
|
|---|
| 73 | or documentation set. Since most products are more comprehensive
|
|---|
| 74 | and consist of a number of tools, one manual is rarely enough.
|
|---|
| 75 | Instead, more manuals which should be accessible at the same
|
|---|
| 76 | time, exist. Ideally, it should also be possible to reference
|
|---|
| 77 | certain points of interest of one manual to another.
|
|---|
| 78 | Therefore, the Qt help system operates on help collection files
|
|---|
| 79 | which include any number of compressed help files.
|
|---|
| 80 |
|
|---|
| 81 | However, having collection files to merge many documentation
|
|---|
| 82 | sets may lead to some problems. For example, one index keyword
|
|---|
| 83 | may be defined in different documentations. So, when only seeing
|
|---|
| 84 | it in the index and activating it, you cannot be sure that
|
|---|
| 85 | the expected documentation will be shown. Therefore, the Qt
|
|---|
| 86 | help system offers the possibiltiy to filter the help contents
|
|---|
| 87 | after certain attributes. This requires however, that the
|
|---|
| 88 | attributes have been assigned to the help contents before the
|
|---|
| 89 | generation of the compressed help file.
|
|---|
| 90 |
|
|---|
| 91 | As already mentioned, the Qt compressed help file contains all
|
|---|
| 92 | data, so there is no need any longer to ship all single html
|
|---|
| 93 | files. Instead, only the compressed help file and optionally the
|
|---|
| 94 | collection file has to be distributed. The collection file is
|
|---|
| 95 | optional since any existing collection file, e.g. from an older
|
|---|
| 96 | release could be used.
|
|---|
| 97 |
|
|---|
| 98 | So, in general, there are four files interacting with the help
|
|---|
| 99 | system, two used for generating Qt help and two meant for
|
|---|
| 100 | distribution:
|
|---|
| 101 |
|
|---|
| 102 | \table
|
|---|
| 103 | \header
|
|---|
| 104 | \o Name
|
|---|
| 105 | \o Extension
|
|---|
| 106 | \o Brief Description
|
|---|
| 107 | \row
|
|---|
| 108 | \o \l {Qt Help Project}
|
|---|
| 109 | \o .qhp
|
|---|
| 110 | \o The input file for the help generator consisting of the table
|
|---|
| 111 | of contents, indices and references to the actual documentation
|
|---|
| 112 | files (*.html); it also defines a unique namespace for the
|
|---|
| 113 | documentation.
|
|---|
| 114 |
|
|---|
| 115 | \row
|
|---|
| 116 | \o Qt Compressed Help
|
|---|
| 117 | \o .qch
|
|---|
| 118 | \o The output file of the help generator. This binary file contains
|
|---|
| 119 | all information specified in the help project file along with all
|
|---|
| 120 | compressed documentation files.
|
|---|
| 121 |
|
|---|
| 122 | \row
|
|---|
| 123 | \o \l {Qt Help Collection Project}
|
|---|
| 124 | \o .qhcp
|
|---|
| 125 | \o The input file for the help collection generator. It contains
|
|---|
| 126 | references to compressed help files which should be included in
|
|---|
| 127 | the collection; it also may contain other information for
|
|---|
| 128 | customizing Qt Assistant.
|
|---|
| 129 |
|
|---|
| 130 | \row
|
|---|
| 131 | \o Qt Help Collection
|
|---|
| 132 | \o .qhc
|
|---|
| 133 | \o The output of the help collection generator. This is the file
|
|---|
| 134 | QHelpEngine operates on. It contains references to any number of
|
|---|
| 135 | compressed help files as well as additional information, such as
|
|---|
| 136 | custom filters.
|
|---|
| 137 | \endtable
|
|---|
| 138 |
|
|---|
| 139 | \section1 Generating Qt Help
|
|---|
| 140 |
|
|---|
| 141 | Building help files for the Qt help system assumes that the html
|
|---|
| 142 | documentation files already exist, i.e. the Qt help system does
|
|---|
| 143 | not offer the possibility to create html files like e.g. Doxygen.
|
|---|
| 144 |
|
|---|
| 145 | Once the html documentents are in place, a \l {Qt Help Project} file
|
|---|
| 146 | has to be created. After specifying all relevant information in
|
|---|
| 147 | this file, it needs to be compiled by calling:
|
|---|
| 148 |
|
|---|
| 149 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 2
|
|---|
| 150 |
|
|---|
| 151 | The file 'doc.qch' contains then all html files in compressed
|
|---|
| 152 | form along with the table of contents and index keywords. To
|
|---|
| 153 | test if the generated file is correct, open Qt Assistant and
|
|---|
| 154 | install the file via the Settings|Documentation page.
|
|---|
| 155 |
|
|---|
| 156 | \target Qt Help Collection Project
|
|---|
| 157 | \section2 Creating a Qt Help Collection
|
|---|
| 158 |
|
|---|
| 159 | The first step is to create a Qt Help Collection Project file.
|
|---|
| 160 | Since a Qt help collection stores primarily references to
|
|---|
| 161 | compressed help files, the project 'mycollection.qhcp' file
|
|---|
| 162 | looks unsurprisingly simple:
|
|---|
| 163 |
|
|---|
| 164 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 3
|
|---|
| 165 |
|
|---|
| 166 | For actually creating the collection file call:
|
|---|
| 167 |
|
|---|
| 168 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 4
|
|---|
| 169 |
|
|---|
| 170 | Instead of running two tools, one for generating the compressed
|
|---|
| 171 | help and one for generating the collection file, it is also
|
|---|
| 172 | possible to just run the qcollectiongenerator tool with a
|
|---|
| 173 | slightly modified project file instructing the generator to
|
|---|
| 174 | create the compressed help first.
|
|---|
| 175 |
|
|---|
| 176 | \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 5
|
|---|
| 177 |
|
|---|
| 178 | Of course, it is possible to specify more than one file in the
|
|---|
| 179 | 'generate' or 'register' section, so any number of compressed
|
|---|
| 180 | help files can be generated and registered in one go.
|
|---|
| 181 |
|
|---|
| 182 | \section1 Using Qt Help
|
|---|
| 183 |
|
|---|
| 184 | Accessing the help contents can be done in two ways: Using Qt
|
|---|
| 185 | Assistant as documentation browser or using the QHelpEngine
|
|---|
| 186 | API for embedding the help contents directly in an application.
|
|---|
| 187 |
|
|---|
| 188 | \section2 Using Qt Assistant
|
|---|
|
|---|
