Long live Qt!

1 files changed, 403 insertions, 0 deletions

diff --git a/doc/src/qthelp.qdoc b/doc/src/qthelp.qdoc
new file mode 100644
index 0000000..05bf3e3
--- /dev/null
+++ b/doc/src/qthelp.qdoc
@@ -0,0 +1,403 @@
+/****************************************************************************
+**
+** Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+** Contact: Qt Software Information (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 either Technology Preview License Agreement or the
+** Beta Release License Agreement.
+**
+** 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.0, included in the file LGPL_EXCEPTION.txt in this
+** package.
+**
+** GNU General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU
+** General Public License version 3.0 as published by the Free Software
+** Foundation and appearing in the file LICENSE.GPL included in the
+** packaging of this file.  Please review the following information to
+** ensure the GNU General Public License version 3.0 requirements will be
+** met: http://www.gnu.org/copyleft/gpl.html.
+**
+** If you are unsure which license is appropriate for your use, please
+** contact the sales department at qt-sales@nokia.com.
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+/*!
+    \module QtHelp
+    \title QtHelp Module
+    \contentspage Qt's Modules
+    \previouspage QtUiTools
+    \nextpage QtAssistant
+    \ingroup modules
+
+    \brief The QtHelp module provides classes for integrating
+    online documentation in applications.
+
+    To include the definitions of the module's classes, use the
+    following directive:
+
+    \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 0
+
+    To link against the module, add this line to your \l qmake \c
+    .pro file:
+
+    \snippet doc/src/snippets/code/doc_src_qthelp.qdoc 1
+
+    \note These classes are part of the \l{Open Source Versions of Qt} and
+    \l{Qt Commercial Editions}{Qt Full Framework Edition} for commercial
+    users.
+
+    \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.
+
+    \section1 License Information
+
+    The QtHelp module uses the CLucene indexing library to provide full-text
+    searching capabilities for Qt Assistant and applications that use the
+    features of QtHelp.
+
+    Qt Commercial Edition licensees that wish to distribute applications that
+    use these features of the QtHelp module need to be aware of their
+    obligations under the GNU Lesser General Public License (LGPL). 
+
+    Developers using the Open Source Edition can choose to redistribute
+    the module under the appropriate version of the GNU LGPL; version 2.1
+    for applications and libraries licensed under the GNU GPL version 2,
+    or version 3 for applications and libraries licensed under the GNU
+    GPL version 3.
+
+    \legalese
+    Copyright (C) 2003-2006 Ben van Klinken and the CLucene Team \BR
+    Changes are Copyright (C) 2009 Nokia Corporation and/or its subsidiary(-ies).
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Lesser General Public
+    License as published by the Free Software Foundation; either
+    version 2.1 of the License, or (at your option) any later version.
+
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Lesser General Public License for more details.
+
+    You should have received a copy of the GNU Lesser General Public
+    License along with this library; if not, write to the Free Software
+    Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+    \endlegalese
+*/
+
+/*!
+    \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 shouldn't 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 file are relative to the help project file
+    itself.
+    
+    \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. 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.
+*/