Revision control
++ // 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.
++
++ \warning Only register compressed help files (.qch) that come from a
++ source that you trust. Registering and viewing a help file from an
++ untrusted source is a security risk. For more information, see
++ \l{qthelp-security-considerations}{Security Considerations}.
++
++ 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.
++
++ \target qthelp-security-considerations
++ \section1 Security Considerations
++
++ A compressed help file is a database that can hold documents of any type,
++ and the help system processes those documents on behalf of the user. The
++ Qt Help module is not designed or hardened to handle malicious
++ content. Therefore, only register help files that come from a source that
++ you trust, such as your Qt installation or the vendor of an application
++ that you installed. Treat a .qch file that you download from the web,
++ receive by email, or find in a shared folder with the same caution as an
++ executable from the same source.
++
++ In particular, be aware of the following:
++
++ \list
++ \li A help file is opened as an SQLite database, and QHelpSearchEngine
++ indexes the documents in it for full text search as soon as the
++ file is registered, which is before any page from it is displayed.
++ \li The documents are rendered by whichever class your application
++ uses for that purpose, such as QTextBrowser. Such a renderer is
++ not hardened, and misses many of the security features of a modern
++ HTML5 renderer. It might therefore crash or misbehave for some
++ documents.
++ \li A help file can contain links that point outside the file, such as
++ \c http or \c mailto links. If your application passes such an
++ address to QDesktopServices::openUrl(), the operating system opens
++ it in the web browser or mail client of the user. Documentation
++ that appears to be local can therefore direct the user to any
++ address on the internet.
++ \li A help file can contain documents of a type that your application
++ cannot display itself. If your application writes such a document
++ to a temporary file and lets the operating system open it, the
++ help file determines which application is launched.
++ \li QHelpEngineCore::fileData() returns the documents exactly as they
++ are stored in the help file, without any filtering. The HTML, CSS,
++ and JavaScript it returns are untrusted content, and your
++ application is responsible for displaying them in a suitably
++ restricted environment.
++ \li All registered documentation is addressed through the single
++ \c qthelp URL scheme, whatever help file it comes from. A renderer
++ that follows web security rules, such as a web engine, might
++ therefore treat all \c{qthelp://} URLs as one origin. In that case,
++ a script in one help file can read and modify the documents of
++ every other registered help file, and can access any interface
++ that your application exposes to the rendered pages. Registering
++ one untrusted help file thus exposes all other registered help
++ files as well. If you build a help viewer on a web engine, consider
++ giving each help file namespace its own origin, and do not expose
++ application interfaces to the rendered pages.
++ \endlist
++
++ The same considerations apply to the help collection file (.qhc), because
++ the collection file determines which help files are loaded.
++ */
++
++ /*!
++ \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.
++ */