/*!
    \page assistant-manual.html
    \title Qt Assistant Manual
    \ingroup qttools
    \keyword Qt Assistant

    \chapter Introduction

    This document introduces \QA, a tool for presenting on-line
    documentation. It also introduces the Qt Reference Documentation which
    is accessible using \QA, or with a web browser. The document is
    divided into the following sections:

    \tableofcontents

    \chapter Introduction to the Qt Reference Documentation

    The documentation for the Qt library is written in-line in the \c
    .cpp files by the developers themselves. The documentation team
    revises the documentation to ensure that it is accurate and usable,
    and to provide quality control. The documentation team also writes the
    larger texts, such as the class descriptions that introduce a class
    along with the concepts the class uses, as well as introducing the
    functions and properties that the class provides.

    The documentation focuses on the API rather than the internals, since
    we make great efforts to keep our API consistent and compatible with
    each new version, but we may change the internals considerably to improve
    performance and enhance functionality.

    The Qt Reference Documentation consists of almost 1,500 HTML pages
    (over 2,500 printed pages). The overwhelming majority of pages
    document Qt classes. Since developers differ in the way they
    think and work we provide a variety of approaches to navigating the
    documentation set:

    \list

    \i The \l{Qt's Classes} page lists every class
    in Qt's public API, and consists of several hundred classes.

    \i The \l{Qt's Main Classes} page lists the
    classes you're most likely to use most often, and provides a much
    shorter and more managable list than the All Classes list.

    \i The \l{Grouped Classes} page presents a list
    of groups, each of which leads to a list of related classes, for
    example, the \l{Advanced Widgets} list.

    \i The \l{Class Inheritance Hierarchy} page
    presents a list of classes in terms of the hierarchy of Qt classes.

    \i The \l{Member Function Index} page lists all the
    functions provided by Qt classes, each one with links to the class(es)
    in which it appears.

    \endlist

    No matter where you find yourself in the Qt documentation, you will
    find extensive cross-referencing. Even snippets of example code
    contain clickable links, so that for example, if you come across a
    class declaration in a code example, the class name will be a
    clickable link to the class's documentation.

    In addition to the class documentation some of Qt's modules have
    extensive descriptions, and there are many overview documents which
    describe various aspects of the Qt library; all these are linked from
    the reference documentation home page. There are also two tutorials
    and numerous example programs in the examples subdirectory of the Qt
    distribution.

    \chapter The One-Minute Guide to Using Qt Assistant

    Under Windows, \QA is available as a menu option on the Qt menu. On
    Unix, run \c{assistant} from an xterm.

    When you start up \QA, you will be presented with a standard
    main-window style application, with a menu bar and toolbar. Below
    these, on the left hand side is a navigation window called the \e
    Sidebar, and on the right, taking up most of the space, is the
    documentation window. By default, the Qt Reference Documentation's home
    page is shown in the documentation window.

    \QA works in a similar way to a web browser. If you click underlined
    text (which signifies a cross-reference), the documentation window will
    present the relevant page. You can bookmark pages of particular
    interest and you can click the \gui{Previous} and \gui{Next} toolbar
    buttons to navigate within the pages you've visited.

    Although \QA can be used just like a web browser to navigate through
    the Qt documentation set, \QA offers a powerful means of navigation
    that web browsers don't provide. \QA uses an intelligent algorithm to
    index all the pages in the documentation sets that it presents so that
    you can search for particular words and phrases.

    To perform an index search, click the \gui{Index} tab on the Sidebar
    (or click \key{Ctrl+I}). In the 'Look For' line edit enter a word, e.g.
    'homedirpath'. As you type, words are found and highlighted in a list
    beneath the line edit. If the highlighted text matches what you're
    looking for, double click it, (or press \key{Enter}) and the
    documentation window will display the relevant page. You rarely have
    to type in the whole word before \QA finds a match. Note that for some
    words there may be more than one possible page that is relevant.

    \QA also provides full text searching for finding specific words in
    the documentation. Documents with the highest occurrences of the word
    that you are looking for appear first, and every occurrence of the
    word within the documentation is highlighted.

    \omit
    For example, enter 'setenabled' in the 'Look For' line edit.
    As you type, words are found and highlighted in the list beneath the
    line edit, as before. Once the highlighted text matches what you're
    looking for, double click it, (or press \key{Enter}). In the case of
    setEnabled, it is a function name which occurs in several classes, so
    a dialog pops up listing the possible choices. Click the choice you're
    interested in (or move to it using the \key{Up} and \key{Down} arrow
    keys and press \key{Enter}). The relevant page will display in the
    documentation window.
    \endomit

    \QA can be customized by creating profiles, a collection of
    documentation. Profiles can be created for your own use, or for an
    application you will distribute. With profiles, you can select which
    documentation you want the end user of your application to be able to
    view.

    \chapter Qt Assistant in More Detail

    \img assistant-assistant.png

    \section1 The Sidebar

    \img assistant-sidebar.png

    The sidebar provides four ways of navigating documentation:
    \list 1
    \i The \gui{Contents} tab presents a tree view of the
    documentation sets that are available. If you click an item, its
    documentation will appear in the documentation window. If you double
    click an item or click a '+' sign to the left of an item, the item's
    sub-items will appear. Click a sub-item to make its page appear in the
    documentation window. Click a '-' sign to the left of an item to hide
    its sub-items.
    \i The \gui{Index} tab is used to look up key words or phrases.
    See \l{The One-Minute Guide to Using Qt Assistant} for how to use this
    tab.
    \i The \gui{Bookmarks} tab lists any bookmarks you've made.
    Double click a bookmark to make its page appear in the documentation
    window. The \gui{Bookmarks} tab has a \gui{New Bookmark}
    button and a \gui{Delete Bookmark} button at the bottom. Click
    \gui{New Bookmark} to bookmark the page that is showing in the
    documentation window. Click a bookmark in the list, then click
    \gui{Delete Bookmark} to delete the highlighted bookmark.
    \i The \gui{Search} tab provides full text search of \e all
    the documents. See \l{Full Text Searching} for more information about
    this feature.
    \endlist

    If you want the documentation window to use as much space as possible,
    you can easily hide or show the Sidebar. If the Sidebar is showing,
    press \key{Ctrl+T}, \key{Ctrl+I}, \key{Ctrl+B}, or \key{Ctrl+S} to hide it.
    If the Sidebar is hidden, press \key{Ctrl+T} to show it on the Contents
    tab, or press \key{Ctrl+I} to show it on the Index tab (with the focus
    in the 'Look For' line edit box), or press \key{Ctrl+B} to show it on
    the Bookmarks tab, or press \key{Ctrl+S} to show it on the (full text)
    \gui{Search} tab.

    The Sidebar is a dock window, so you can drag it to the top, left,
    right or bottom of \QA's window, or you can drag it outside \QA to
    float it.

    \section1 The Documentation Window

    \img assistant-docwindow.png

    The documentation window offers a feature for viewing documentation by
    enabling you to create tabs for each documentation page that you view.
    Click the \gui{Add Tab} button and a new tab will appear with the
    page name as the tab's caption. This makes it convenient to switch
    between pages when you are working with different documentation. You
    can delete a tab by clicking the \gui{Close Tab} button located
    on the right side of the documentation window.

    \section1 The Toolbar

    \img assistant-toolbar1.png

    The toolbar provides fast access to the most common actions.
    \list
    \i \gui{Previous} takes you to the previous page. The menu
    option is \menu{Go|Previous} and the keyboard shortcut is \key{Alt+Left
    Arrow}.
    \i \gui{Next} takes you to the next page. The menu
    option is \menu{Go}|Next and the keyboard shortcut is \key{Alt+Right
    Arrow}.
    \i \gui{Home} takes you to the home page (normally the home page
    of the Qt Reference Documentation). The menu
    option is \menu{Go}|Home and the keyboard shortcut is \key{Ctrl+Home}.
    \i \gui{Copy} copies any selected text to the clipboard. The menu
    option is \menu{Edit}|Copy and the keyboard shortcut is \key{Ctrl+C}.
    \i \gui{Find in Text} invokes the \gui{Find Text} dialog. The menu
    option is \menu{Edit|Find in Text} and the keyboard shortcut is \key{Ctrl+F}.
    \i \gui{Print} invokes the \gui{Print} dialog. The menu
    option is \menu{File|Print} and the keyboard shortcut is \key{Ctrl+P}.
    \i \gui{Zoom in} increases the font size. The menu
    option is \menu{View|Zoom in} and the keyboard shortcut is \key{Ctrl++}.
    \i \gui{Zoom out} decreases the font size. The menu
    option is \menu{View|Zoom out} and the keyboard shortcut is \key{Ctrl+-}.
    \i \gui{What's This?} provides a description of a \QA feature.
    The menu option is \menu{Help|What's This?} and the keyboard shortcut
    is \key{Shift+F1}.
    \endlist

    The remaining toolbar buttons are bookmarks and will vary depending on
    your configuration.

    \section1 The Menus

    \section2 The File Menu

    \list
    \i \menu{File|Print} invokes the \gui{Print} dialog.
    \i \menu{File|Exit} terminates \QA.
    \endlist

    \section2 The Edit Menu

    \list
    \i \menu{Edit|Copy} copies any selected text to the clipboard.
    \i \menu{Edit|Find in Text} invokes the \gui{Find Text} dialog.
    \endlist

    \section2 The View Menu

    \list
    \i \menu{View|Zoom in} increases the font size.
    \i \menu{View|Zoom out} decreases the font size.
    \i \menu{View|Views|Sidebar} toggles the display of the Sidebar.
    \i \menu{View|Views|Toolbar} toggles the display of the Toolbar.
    \i \menu{View|Views|Line up} lines up the toolbar buttons in the
    Toolbar.
    \endlist

    \section2 The Go Menu

    \list
    \i \menu{Go|Previous} displays the previous page.
    \i \menu{Go|Next} displays the next page.
    \i \menu{Go|home} goes to the home page.
    \endlist
    This menu also has additional items; these are pre-defined bookmarks
    that vary depending on your configuration.

    \section2 The Bookmarks Menu

    \list
    \i \menu{Bookmarks|Add} adds the current page to the list of bookmarks.
    \endlist
    This menu may have additional items, i.e. any bookmarks that you have
    already made. If you want to delete a bookmark go to the Bookmarks tab
    on the Sidebar.

    \section1 The Dialogs

    \section2 The Print Dialog

    This dialog is platform-specific. It gives access to various printer
    options and can be used to print the current page.

    \section2 The Find Text Dialog

    This dialog is used to find text in the current page. Enter the
    text you want to find in the Find line edit. If you check the
    'Whole words only' checkbox, the search will only consider whole
    words, i.e. if you search for 'spin' with this checkbox checked
    it will not match 'spinbox', but will match 'spin'. If you check
    the 'Case sensitive' check box then, for example, 'spin' will
    match 'spin' but not 'Spin'. You can search Forward or Backward
    from your current position in the page by clicking one of the
    Direction radio buttons. Click the \gui{Find} button to search
    (or search again), and click the \gui{Close} button to finish.

    \chapter Full Text Searching

    \img assistant-search.png

    \QA provides a powerful full text search engine. To search
    for certain words or text, click the 'Search' tab in the sidebar. Then
    enter the text you want to look for and press \key{Enter} or click
    \gui{Search}. The search is not case sensitive, so Foo, fOo and
    FOO are all treated as the same. The following are examples of common search
    patterns:

    \list
    \i \c deep -- lists all the documents that contain the word 'deep'

    \i \c{deep*} -- lists all the documents that contain a word beginning
    with 'deep'

    \i \c{deep copy} -- lists all documents that contain both 'deep' \e
    and 'copy'

    \i \c{"deep copy"} -- list all documents that contain the phrase 'deep copy'
    \endlist

    The wildcard (*) character cannot be used within quotes.

    The list of documents found is ordered according to the number of
    occurrences of the search text they contain, therefore those with the
    highest number of occurrences appearing first. Simply click any
    document in the list to display it in the document window.

    If the documentation has changed, i.e. if documents have been added or
    removed, \QA will reindex.

    \chapter Customizing Qt Assistant

    \QA can be customized by adding and removing documentation from its
    documentation set. In addition, \QA introduces the profiles option,
    which enables its properties to change, for example, the default
    startup page, and application icon.

    \section1 Modifying the Default Documentation Set

    When it is started without any options, \QA displays a default set of
    documentation. When Qt is installed, the default documentation set in
    \QA contains the Qt reference documentation as well as the tools that
    come with Qt, such as \QD and qmake.

    Documentation can be added or removed from \QA by
    adding and removing the content files. The format of the content files are
    specified below.  To add a content file, type the following command line
    option: \c{-addContentFile docfile}. To remove a content file from the
    default set, type the following command line option:
    \c{-removeContentFile docfile}. For example:

    \code
    1: > assistant -addContentFile file.dcf
    2: > assistant
    3: > assistant -removeContentFile file.dcf
    \endcode

    In line one, we add the content file \c file.dcf. In line two, we start
    \QA. The default set will now be extended with the doc file
    \c file.dcf. In line three we remove the file \c file.dcf from the default
    documentation set so that subsequent use of \QA will not contain this
    file.

    \section2 Documentation Content File Format

    The Documentation Content File must contain the documentation's table
    of contents and all important keywords for the index. In addition, it
    may inherit an icon for the documentation which is displayed in the
    \QA toolbar. You can also specify an extra directory path for
    additional images used in the documentation.

    An example of a content file that uses all the available tags and
    attributes is shown below:
    \code
    <assistantconfig version="3.2.0">
        <DCF ref="demo.html" icon="handbook.png" imagedir="../img/"
                title="Development Demo Handbook">
            <section ref="./chap1/chap1.html" title="Chapter1">
                <section ref="./chap1/section1.html" title="Section1">
                    <keyword ref="./chap1/section1.html#foo">foo</keyword>
                    <keyword ref="./chap1/section1.html#bla">bla</keyword>
                    <section ref="./chap1/section1.html#subsection1" title="Subsection 1"/>
                    <section ref="./chap1/section1.html#subsection2" title="Subsection 2"/>
                    <section ref="./chap1/section1.html#subsection3" title="Subsection 3"/>
                </section>
                <section ref="./chap1/section2" title="Section2">
                    <section ref="./chap1/section2.html#subsection1" title="Subsection 1"/>
                    <section ref="./chap1/section2.html#subsection2" title="Subsection 2"/>
                    <section ref="./chap1/section2.html#subsection3" title="Subsection 3"/>
                </section>
            </section>
            <section ref="./chap2/chap2.html" title="Chapter2">
                <keyword ref="./chap2/chap2.html#foo">foo</keyword>
                <section ref="./chap2/section1.html" title="Section1"/>
            </section>
        </DCF>
    </assistantconfig>
    \endcode

    Sections may be nested as deeply as necessary. All references should
    be related.

    Note that any \c keyword tags for a given section must appear \e
    before any sections nested within the given section.

    The paths in the \c refs attribute are always written Unix-style
    (forward slashes) and are relative to the location of the
    documentation content file itself.

    Since the introduction of the new root tag \c assistantconfig in the
    fileformat from Qt version 3.2.0, it is possible to specify multiple DCF tags in
    one file. Note that the old document contents file format, used up to
    Qt 3.2 is still valid.

    \section1 Profiles

    Profiles enable \QA to act as a specialized help tool for displaying
    documentation for applications. With profiles, the documentation
    writer can change properties such as \QA's title, application icons, and
    'about' dialogs. In addition, profiles can be used to run specialized
    documentation sets that are separate from the Qt docs. \QA can be
    customized by changing the following properties:

    \list

    \i Name - This property is used to name the profile. If multiple
    profiles are used for the same installation of \QA, this
    parameter is crucial to keep their profile specific settings
    apart. The property name is \c name

    \i Title - This property is used to specify a window title for \QA.
    The property name is \c title

    \i Application Icon - This property describes an icon that will be used
    as \QA application icon. The location of the icon is relative to the
    location of the profile. The property name is \c applicationicon

    \i Start Page - This property specifies which page \QA should initially
    display when the profile is used. Usually, this is the HTML file which
    contains the documentation's table of contents. This property also
    describes the default location to go to when pressing the home button
    in \QA's main user interface. The start page is specified relative to
    the location of the profile. The property name is \c startpage

    \i About Menu Text - This property describes the text that appears in
    the \menu{Help} menu, e.g. About Application. The property name is \c
    aboutmenutext

    \i About URL - This property can be used to point to an HTML file that
    describes the contents in the About dialog that is opened for the
    \menu{Help} menu, e.g. About Application. The url is specified relative
    to the location of the profile. The property name is \c abouturl

    \i \QA Documentation - This property describes the location of the \QA
    documentation, which is used when the user requests help from the
    \gui{Search} tab. The location is a directory relative to the location
    of the profile. The property name is \c assistantdocs.

    \endlist

    To define a profile, one needs to specify a \QA Document
    Profile, usually abbreviated \c{.adp}. The profile is an extension of
    the Documentation Content File described above. We add a \c profile
    tag containing \c property tags to the format.

    An example of a document profile file is shown below:

    \c simpletextviewer.adp

    \quotefile assistant/simpletextviewer/documentation/simpletextviewer.adp

    \section2 Using Profiles

    To use a profile, run \QA with the option \c {-profile filename}.
    This will load the profile specified in the file and will customize
    \QA accordingly. For example, to run \QA with the example
    file above, \c simpletextviewer.adp, we would run the command as follows:

    \code
    > assistant -profile simpletextviewer.adp
    \endcode

    See the \l {assistant/simpletextviewer}{Simple Text Viewer} example
    in the Qt distribution for a demonstration on how to use \QA with
    profiles for your own applications.

    \omit
    For small documentation sets, the sidebar may not be necessary. You
    can hide the sidebar on startup with the following:
    \code
    assistant -hideSidebar
    \endcode
    \endomit
*/
