FCL/sf/mw/qt: comparison doc/src/frameworks-technologies/qthelp.qdoc

equal deleted inserted replaced

-:41300fa6a67c
+:f7bc934e204c
+/****************************************************************************
+**
+** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).
+** All rights reserved.
+** Contact: Nokia Corporation (qt-info@nokia.com)
+**
+** This file is part of the documentation of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL$
+** No Commercial Usage
+** This file contains pre-release code and may not be distributed.
+** You may use this file in accordance with the terms and conditions
+** contained in the Technology Preview License Agreement accompanying
+** this package.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 as published by the Free Software
+** Foundation and appearing in the file LICENSE.LGPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU Lesser General Public License version 2.1 requirements
+** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** In addition, as a special exception, Nokia gives you certain additional
+** rights.  These rights are described in the Nokia Qt LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** If you have questions regarding the use of this file, please contact
+** Nokia at qt-info@nokia.com.
+**
+**
+**
+**
+**
+**
+**
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+/*!
+\group helpsystem
+\title Help System
+\ingroup groups
+\brief Classes used to provide online-help for applications.
+\keyword help system
+These classes provide for all forms of online-help in your application,
+with three levels of detail:
+\list 1
+\o Tool Tips and Status Bar message - flyweight help, extremely brief,
+entirely integrated in the user interface, requiring little
+or no user interaction to invoke.
+\o What's This? - lightweight, but can be
+a three-paragraph explanation.
+\o 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 Topics
+\tableofcontents
+\section1 Overview
+The Qt help system includes tools for generating and viewing
+Qt help files. In addition it provides classes for accessing
+help contents programatically 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 documentations. So, when only seeing
+it in the index and activating it, you cannot be sure that
+the expected documentation will be shown. Therefore, the Qt
+help system offers the possibiltiy 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 single html
+files. Instead, only the compressed help file and optionally the
+collection file has to be distributed. The collection file is
+optional since any existing collection file, e.g. 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
+\o Name
+\o Extension
+\o Brief Description
+\row
+\o \l {Qt Help Project}
+\o .qhp
+\o The input file for the help generator consisting of the table
+of contents, indices and references to the actual documentation
+files (*.html); it also defines a unique namespace for the
+documentation.
+\row
+\o Qt Compressed Help
+\o .qch
+\o The output file of the help generator. This binary file contains
+all information specified in the help project file along with all
+compressed documentation files.
+\row
+\o \l {Qt Help Collection Project}
+\o .qhcp
+\o The input file for the help collection generator. It contains
+references to compressed help files which should be included in
+the collection; it also may contain other information for
+customizing Qt Assistant.
+\row
+\o Qt Help Collection
+\o .qhc
+\o The output of the help collection generator. This is the file
+QHelpEngine operates on. It contains references to any number of
+compressed help files as well as additional information, such as
+custom filters.
+\endtable
+\section1 Generating Qt Help
+Building help files for the Qt help system assumes that the html
+documentation files already exist, i.e. the Qt help system does
+not offer the possibility to create html files like e.g. Doxygen.
+Once the html documentents are in place, a \l {Qt Help Project} file
+has to be created. After specifying all relevant information in
+this file, it needs to be compiled by calling:
+\snippet doc/src/snippets/code/doc_src_qthelp.qdoc 2
+The file 'doc.qch' contains then all 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 via the Settings|Documentation page.
+\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 'mycollection.qhcp' file
+looks unsurprisingly simple:
+\snippet doc/src/snippets/code/doc_src_qthelp.qdoc 3
+For actually creating the collection file call:
+\snippet doc/src/snippets/code/doc_src_qthelp.qdoc 4
+Instead of running two tools, one for generating the compressed
+help and one for generating the collection file, it is also
+possible to just run the qcollectiongenerator tool with a
+slightly modified project file instructing the generator to
+create the compressed help first.
+\snippet doc/src/snippets/code/doc_src_qthelp.qdoc 5
+Of course, it is possible to specify more than one file in the
+'generate' or 'register' section, so any number of compressed
+help files can be generated and registered in one go.
+\section1 Using Qt Help
+Accessing the help contents can be done in two ways: Using Qt
+Assistant as documentation browser or using the QHelpEngine
+API for embedding the help contents directly in an application.
+\section2 Using Qt Assistant
+\QA operates on a collection file which can be specified
+before start up. If no collection file is given, a default one
+will be created and used. In either case, it is possible to
+register any Qt compressed help file and access the help contents.
+When using Assistant as the help browser for an application, it
+would be desirable that it can be customized to fit better to the
+application and doesn't look like an independent, standalone
+help browser. To achieve this, several additional properties can
+be set in an Qt help collection file, to change e.g. the title
+or application icon of Qt Assistant. For more information on
+this topic have a look at the \l{assistant-manual.html}
+{Qt Assistant manual}.
+\section2 Using QHelpEngine API
+Instead of showing the help in an external application like the
+Qt Assistant, 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 it 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 "MyDialog::ChangeButton". If a link
+was found, meaning at least one help document exists to this topic,
+we get the actual help contents by calling fileData() and display
+the document to the user.
+\snippet doc/src/snippets/code/doc_src_qthelp.qdoc 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,
+e.g. the Qt Assistant manual.
+\section1 Qt Help Project File Format
+The file format is XML-based. For a better understanding of
+the format we'll discuss the following example:
+\snippet doc/src/snippets/code/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 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".
+\target Virtual Folders
+\section2 Virtual Folders
+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.
+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.
+\snippet doc/src/snippets/code/doc_src_qthelp.qdoc 8
+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.
+The virtual folder tag is mandatory and the folder must not
+contain any '/'.
+\target Custom Filters
+\section2 Custom Filters
+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 QHelpEngine to "My Application 1.0" only
+the documentation which has "myapp" and "1.0" set as filter
+attributes will be shown.
+\snippet doc/src/snippets/code/doc_src_qthelp.qdoc 9
+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.
+\target Filter Section
+\section2 Filter Section
+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.
+\section3 Filter Attributes
+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 QHelpEngine does not contain any filter
+attributes.
+\snippet doc/src/snippets/code/doc_src_qthelp.qdoc 10
+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.
+\section3 Table of contents
+\snippet doc/src/snippets/code/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 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.
+\note 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.
+\section3 Keywords
+\snippet doc/src/snippets/code/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 'name' is used then the keyword specified there will appear in
+the visible index, i.e. it will be accessible through the QHelpIndexModel.
+If 'id' is used, the keyword does not appear in the index and is
+only accessible via the linksForIdentifier() function of the
+QHelpEngineCore. 'name' and 'id' can be specified at the same time.
+\section3 Files
+\snippet doc/src/snippets/code/doc_src_qthelp.qdoc 13
+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. \note 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.
+*/