10 files changed, 569 insertions, 0 deletions

diff --git a/tools/assistant/book/assistant.book b/tools/assistant/book/assistant.book
new file mode 100644
index 000000000..feb658899
--- /dev/null
+++ b/tools/assistant/book/assistant.book
@@ -0,0 +1,6 @@
+\title Qt Assistant Manual
+
+\granularity chapter
+
+\input assistant.leaf
+
diff --git a/tools/assistant/book/assistant.leaf b/tools/assistant/book/assistant.leaf
new file mode 100644
index 000000000..588f9df18
--- /dev/null
+++ b/tools/assistant/book/assistant.leaf
@@ -0,0 +1,563 @@
+\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 retquired 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
+
diff --git a/tools/assistant/book/images/assistant.png b/tools/assistant/book/images/assistant.png
new file mode 100644
index 000000000..940194010
--- /dev/null
+++ b/tools/assistant/book/images/assistant.png
diff --git a/tools/assistant/book/images/docwindow.png b/tools/assistant/book/images/docwindow.png
new file mode 100644
index 000000000..18fa0988e
--- /dev/null
+++ b/tools/assistant/book/images/docwindow.png
diff --git a/tools/assistant/book/images/general.png b/tools/assistant/book/images/general.png
new file mode 100644
index 000000000..2fad053f0
--- /dev/null
+++ b/tools/assistant/book/images/general.png
diff --git a/tools/assistant/book/images/pdf1.png b/tools/assistant/book/images/pdf1.png
new file mode 100644
index 000000000..104ac1675
--- /dev/null
+++ b/tools/assistant/book/images/pdf1.png
diff --git a/tools/assistant/book/images/search.png b/tools/assistant/book/images/search.png
new file mode 100644
index 000000000..667a4a625
--- /dev/null
+++ b/tools/assistant/book/images/search.png
diff --git a/tools/assistant/book/images/sidebar.png b/tools/assistant/book/images/sidebar.png
new file mode 100644
index 000000000..7e005cd0b
--- /dev/null
+++ b/tools/assistant/book/images/sidebar.png
diff --git a/tools/assistant/book/images/toolbar1.png b/tools/assistant/book/images/toolbar1.png
new file mode 100644
index 000000000..0f3358a16
--- /dev/null
+++ b/tools/assistant/book/images/toolbar1.png
diff --git a/tools/assistant/book/images/web.png b/tools/assistant/book/images/web.png
new file mode 100644
index 000000000..5888f79cb
--- /dev/null
+++ b/tools/assistant/book/images/web.png