qthelp.qdoc

Go to the documentation of this file.

// 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.
*/