source: trunk/tools/assistant/book/assistant.leaf

\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:

\list
\i Introduction to the Qt Reference Documentation
\i The 1 Minute Guide to using Qt Assistant
\i Qt Assistant in More Detail
\i Full Text Searching
\i Customizing Qt Assistant 
\endlist

\chapter Introduction to the Qt Reference Documentation

The documentation for the Qt library is written in-line in the \File
.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 \link classes.html All Classes\endlink page lists every class
in Qt's public API, and consists of several hundred classes.

\i The \link mainclasses.html Main Classes\endlink 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 \link groups.html Grouped Classes\endlink page presents a list
of groups, each of which leads to a list of related classes, for
example, the \link advanced.html Advanced Widgets\endlink list.

\i The \link hierarchy.html Inheritance Hierarchy\endlink page
presents a list of classes in terms of the hierarchy of Qt classes.

\i The \link functions.html All Functions\endlink 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 1 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 \Toolbutton Previous and \Toolbutton
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 \Toolbutton 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.png
\caption Qt Assistant

\section1 The Sidebar

\img sidebar.png

The sidebar provides four ways of navigating documentation:
\list 1
\i The \Toolbutton 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 \Toolbutton Index tab is used to look up key words or phrases.
See \l{The 1 Minute Guide to using Qt Assistant} for how to use this
tab.
\i The \Toolbutton Bookmarks tab lists any bookmarks you've made.
Double click a bookmark to make its page appear in the documentation
window. The \Toolbutton Bookmarks tab has a \Button{New Bookmark}
button and a \Button{Delete Bookmark} button at the bottom. Click
\Button{New Bookmark} to bookmark the page that is showing in the
documentation window. Click a bookmark in the list, then click 
\Button{Delete Bookmark} to delete the highlighted bookmark.
\i The \Toolbutton 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)
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 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 \Button {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 \Button {Close Tab} button located
on the right side of the documentation window.

\section1 The Toolbar

\img toolbar1.png

The toolbar provides fast access to the most common actions.
\list
\i \Toolbutton Previous takes you to the previous page. The menu
option is \Menu Go|Previous and the keyboard shortcut is \Key{Alt+Left
Arrow}.
\i \Toolbutton Next takes you to the next page. The menu
option is \Menu Go|Next and the keyboard shortcut is \Key{Alt+Right
Arrow}.
\i \Toolbutton 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 \Toolbutton Copy copies any selected text to the clipboard. The menu
option is \Menu Edit|Copy and the keyboard shortcut is \Key{Ctrl+C}.
\i \Toolbutton{Find in Text} invokes the \Dialog{Find Text} dialog. The menu
option is \Menu{Edit|Find in Text} and the keyboard shortcut is \Key{Ctrl+F}.
\i \Toolbutton{Print} invokes the \Dialog{Print} dialog. The menu
option is \Menu{File|Print} and the keyboard shortcut is \Key{Ctrl+P}.
\i \Toolbutton{Zoom in} increases the font size. The menu
option is \Menu{View|Zoom in} and the keyboard shortcut is \Key{Ctrl++}.
\i \Toolbutton{Zoom out} decreases the font size. The menu
option is \Menu{View|Zoom out} and the keyboard shortcut is \Key{Ctrl+-}.
\i \Toolbutton{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 \Dialog{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 \Dialog{Find Text} dialog.
\i \Menu{Edit|Settings} invokes the \Dialog{Settings} 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 \Button
Find button to search (or search again), and click the \Button Close
button to finish.

\section2 The Settings Dialog

The Settings dialog is used to set your preferences for \QA. The
dialog has four tabs: General Settings, Web Settings, PDF Settings,
and Profiles. \QA will remember your settings between sessions,
including window sizes and positions, and which pages you have open.
Each of the tabs is discussed as follows: 

\list
\i General Settings

\img general.png

To change the base font used throughout \QA, select a 
font type from the Font combobox. To choose a new fixed-width 
font, for example, to show code snippets, choose a font type from 
the 'Fixed font' combobox. To change the color of hypertext 
links, click the 'Link color' color button. Uncheck the 
'Underline links' checkbox if you don't want underlined links. 

\i Web Settings 

\img web.png

Some pages contain links to external web pages. In order to display
these links, you must specify a web browser. Type the name of your
browser's executable in the Web Browser Application line edit.
Alternatively, click the \Button {(ellipsis)} button to invoke the
\Widget {Set Web Browser} dialog and navigate until you find the web
browser you want to use. Click \Button {Save} to accept the selection.

To change \QA's default home page, enter the file name in the Home
Page line edit. Alternatively, click the \Button {(ellipsis)} button
to invoke the \Widget {Set Homepage} dialog. Navigate until you find
the home page file you want to use and then click \Button {Save} to
accept the selection.

\i PDF Settings

\img pdf1.png

Some pages contain links to PDF documents. In order to display these
links, you must specify a PDF viewer. Type in the name of your PDF viewer's
executable in the line edit. Alternatively, click the \Button {(ellipsis)}
button to invoke the \Widget {Set PDF Browser} dialog and navigate
until you find the PDF viewer you want to use. Click \Button Save to
accept the selection. 

\chapter Full Text Searching

\img 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
\Button 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 caption 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. This is required since \QA provides
self help, such as the full text search help and the \QA
Manual option in the \Menu Help menu. 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 helpdemo.adp

\code
<assistantconfig version="3.2.0">

    <profile>
        <property name="name">HelpExample</property>
        <property name="title">Help Example</property>
        <property name="applicationicon">logo.png</property>
        <property name="startpage">index.html</property>
        <property name="aboutmenutext">About Help</property>
        <property name="abouturl">../about.txt</property>
        <property name="assistantdocs">../../../doc/html</property>
    </profile>

    <DCF ref="index.html" icon="handbook.png" title="Help example">
        <section ref="./manual.html" title="How to use this Example">
            <keyword ref="./manual.html#installdocs">Install Docs</keyword>
            <keyword ref="./manual.html#onlydoc">Example Profile</keyword>
            <keyword ref="./manual.html#hide">Hide Sidebar</keyword>
            <keyword ref="./manual.html#openqabutton">Open</keyword>
            <keyword ref="./manual.html#closeqabutton">Close</keyword>
            <keyword ref="./manual.html#display">Display</keyword>
        </section>
   </DCF>

</assistantconfig>
\endcode

These files are XML files. Characters such as \c{<}, \c{>}, and \c{&}
must be written as entities (e.g., \c{&lt;}, \c{&gt;}, \c{&amp;}).

\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 helpdemo.adp, we would run the command as follows:

\code 
> assistant -profile helpdemo.adp
\endcode

See the HelpDemo example in the Qt distribution for a demonstration
on how to use \QA with profiles for your own applications.

When distributing \QA with your application, you will also need to
copy the icon files from the \c QTDIR/tools/assistant/images
directory so that \QA finds its icons.

\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