Update copyright headers
[qt:qt.git] / doc / src / development / assistant-manual.qdoc
1 /****************************************************************************
2 **
3 ** Copyright (C) 2015 The Qt Company Ltd.
4 ** Contact: http://www.qt.io/licensing/
5 **
6 ** This file is part of the documentation of the Qt Toolkit.
7 **
8 ** $QT_BEGIN_LICENSE:FDL$
9 ** Commercial License Usage
10 ** Licensees holding valid commercial Qt licenses may use this file in
11 ** accordance with the commercial license agreement provided with the
12 ** Software or, alternatively, in accordance with the terms contained in
13 ** a written agreement between you and The Qt Company. For licensing terms
14 ** and conditions see http://www.qt.io/terms-conditions. For further
15 ** information use the contact form at http://www.qt.io/contact-us.
16 **
17 ** GNU Free Documentation License Usage
18 ** Alternatively, this file may be used under the terms of the GNU Free
19 ** Documentation License version 1.3 as published by the Free Software
20 ** Foundation and appearing in the file included in the packaging of
21 ** this file.  Please review the following information to ensure
22 ** the GNU Free Documentation License version 1.3 requirements
23 ** will be met: http://www.gnu.org/copyleft/fdl.html.
24 ** $QT_END_LICENSE$
25 **
26 ****************************************************************************/
27
28 /*!
29     \page assistant-manual.html
30     \title Qt Assistant Manual
31     \ingroup qttools
32
33     \startpage {index.html}{Qt Reference Documentation}
34     \nextpage Qt Assistant in More Detail
35
36     \keyword Qt Assistant
37
38     This document introduces \QA, a tool for presenting on-line
39     documentation. The document is divided into the following sections:
40
41     Table of contents:
42
43     \list
44     \o \l{The One-Minute Guide to Using Qt Assistant}
45     \o \l{Qt Assistant in More Detail}
46     \o \l{Using Qt Assistant as a Custom Help Viewer}
47     \endlist
48
49     \chapter The One-Minute Guide to Using Qt Assistant
50
51     Once you have installed Qt, \QA should be ready to run:
52
53     \list
54     \o On Windows, \QA is available as a menu option on the Qt menu.
55     \o On Mac OS X, \QA is installed in the /Developer/Applications/Qt directory.
56     \o On Unix/Linux, open a terminal, type \c{assistant} and press \key{Enter}.
57     \endlist
58
59     When you start up \QA, you will be presented with a standard main window
60     application, with a menu bar and toolbar. Below these, on the left hand
61     side are navigation windows called \e{Contents}, \e{Index} and \e{Bookmarks}.
62     On the right, taking up most of the space, is the \e{Documentation} window.
63     By default, \QA loads the Qt reference documentation along with the manuals
64     of other Qt tools, like \QD or \QL.
65
66     \QA works in a similar way to a Web browser. If you click hyperlinks
67     (cross-references), the \e{Documentation} window will present the relevant
68     page. You can bookmark pages of particular interest and you can click the
69     \gui{Previous} and \gui{Next} toolbar buttons to navigate within the pages
70     you have visited.
71
72     Although \QA can be used just like a Web browser to navigate through
73     the documentation, \QA offers a powerful means of navigation that Web
74     browsers do not provide. \QA uses an advanced full text search engine
75     to index all the pages in each compressed help file so that you can
76     search for particular words and phrases.
77
78     To perform an index search, click the \gui{Index} tab on the Sidebar
79     (or press \key{Alt+I}). In the \gui{'Look For'} line edit enter a word;
80     e.g., 'homedirpath'. As you type, words are found and highlighted in a list
81     beneath the line edit. If the highlighted text matches what you're
82     looking for, double click it, (or press \key{Enter}) and the
83     \e{Documentation} window will display the relevant page. You rarely have
84     to type in the whole word before \QA finds a match. Note that for some
85     words there may be more than one possible page that is relevant.
86
87     \QA also provides full text searching for finding specific words in
88     the documentation. To activate the full text search, either press \key(Alt+S)
89     or click on the \gui{Search} tab in the \e{Documentation} window. Then
90     enter the term you're looking for and hit the \gui{Search} button. All
91     documents containing the specified term will then be listed in the list box
92     below.
93 */
94
95 /*!
96     \page assistant-details.html
97     \title Qt Assistant in More Detail
98
99     \contentspage {Qt Assistant Manual}{Contents}
100     \previouspage Qt Assistant Manual
101     \nextpage Using Qt Assistant as a Custom Help Viewer
102
103     \tableofcontents
104
105     \img assistant-assistant.png
106
107     \section1 Command Line Options
108
109     \QA handles the following command line options:
110
111     \table
112         \header
113             \o Command Line Option
114             \o Brief Description
115         \row
116             \o -collectionFile <file.qhc>
117             \o Uses the specified collection file instead of the default one.
118         \row
119             \o -showUrl <URL>
120             \o Shows the document referenced by URL.
121         \row
122             \o -enableRemoteControl
123             \o Enables \QA to be remotly controlled.
124         \row
125             \o -show <widget>
126             \o Shows the specified dockwidget which can be "contents", "index",
127             "bookmarks" or "search".
128         \row
129             \o -hide <widget>
130             \o Hides the specified dockwidget which can be "contents", "index",
131             "bookmarks" or "search.
132         \row
133             \o -activate <widget>
134             \o Activates the specified dockwidget which can be "contents",
135             "index", "bookmarks" or "search.
136         \row
137             \o -register <doc.qch>
138             \o Registers the specified compressed help file in the given help
139             collection.
140         \row
141             \o -unregister <doc.qch>
142             \o Unregisters the specified compressed help file from the given
143                collection file.
144         \row
145             \o -remove-search-index
146             \o Purges the help search engine's index. This option is
147                useful in case the associated index files get corrupted.
148                \QA will re-index the documentation at the next start-up.
149         \row
150             \o -rebuild-search-index
151             \o Rebuilds the help search engine's index. 
152                Note that this operation may take a while to finish.
153         \row
154             \o -setCurrentFilter <filter>
155             \o Sets the given filter as the active filter.
156         \row
157             \o -quiet
158             \o Doesn't show any error, warning or success messages.
159     \endtable
160
161     \section1 Tool Windows
162
163     \img assistant-dockwidgets.png
164
165     The tool windows provide four ways to navigate the documentation:
166
167     \list
168     \o The \gui{Contents} window presents a table of contents implemented as a
169     tree view for the documentation that is available. If you click an item,
170     its documentation will appear in the \e{Documentation} window. If you double
171     click an item or click on the control to the left of it, the item's sub-items
172     will appear. Click a sub-item to make its page appear in the \e{Documentation}
173     window. Click on the control next to an open item to hide its sub-items.
174     \o The \gui{Index} window is used to look up key words or phrases.
175     See \l{Qt Assistant Manual#The One-Minute Guide to Using Qt Assistant}{The One-Minute Guide to Using Qt Assistant} for how to use this
176     window.
177     \o The \gui{Bookmarks} window lists any bookmarks you have made. Double
178     click a bookmark to make its page appear in the \e{Documentation} window.
179     The \gui{Bookmarks} window provides a context menu with \gui{Show Item},
180     \gui{Delete Item} as well as \gui{Rename Item}. Click in the main menu
181     \menu{Bookmark|Add Bookmark...} (or press \key{Ctrl+B}) to bookmark the
182     page that is currently showing in the \e{Documentation} window. Right click
183     a bookmark in the list to rename or delete the highlighted bookmark.
184     \endlist
185
186     If you want the \gui{Documentation} window to use as much space as possible,
187     you can easily group, move or hide the tool windows. To group the windows,
188     drag one on top of the other and release the mouse. If one or all tool
189     windows are not shown, press \key{Alt+C}, \key{Alt+I} or \key{Alt+O} to show
190     the required window.
191
192     The tool windows can be docked into the main window, so you can drag them
193     to the top, left, right or bottom of \e{Qt Assistant's} window, or you can
194     drag them outside \QA to float them as independent windows.
195
196     \section1 Documentation Window
197
198     \img assistant-docwindow.png
199
200     The \gui{Documentation} window lets you create a tab for each
201     documentation page that you view. Click the \gui{Add Tab} button and a new
202     tab will appear with the page name as the tab's caption. This makes it
203     convenient to switch between pages when you are working with different
204     documentation. You can delete a tab by clicking the \gui{Close Tab} button
205     located on the right side of the \gui{Documentation} window.
206
207     \section1 Toolbars
208
209     \img assistant-toolbar.png
210
211     The main toolbar provides fast access to the most common actions.
212
213     \table
214     \header \o Action \o Description \o Menu Item \o Shortcut
215     \row \o \gui{Previous} \o Takes you to the previous page in the history.
216          \o \menu{Go|Previous} \o \key{Alt+Left Arrow}
217     \row \o \gui{Next} \o Takes you to the next page in the history.
218          \o \menu{Go|Next} \o \key{Alt+Right Arrow}
219     \row \o \gui{Home}
220          \o Takes you to the home page as specified in the Preferences Dialog.
221          \o \menu{Go|Home} \o \key{Ctrl+Home}.
222     \row \o \gui{Sync with Table of Contents}
223          \o Synchronizes the \gui{Contents} tool window with the page currently
224             shown in the \gui{Documentation} window.
225          \o \menu{Go|Sync with Table of Contents} \o
226     \row \o \gui{Copy} \o Copies any selected text to the clipboard.
227          \o \menu{Edit|Copy} \o \key{Ctrl+C}
228     \row \o \gui{Print} \o Opens the \gui{Print} dialog.
229          \o \menu{File|Print} \o \key{Ctrl+P}
230     \row \o \gui{Find in Text} \o Opens the \gui{Find Text} dialog.
231          \o \menu{Edit|Find in Text} \o \key{Ctrl+F}
232     \row \o \gui{Zoom in}
233          \o Increases the font size used to display text in the current tab.
234          \o \menu{View|Zoom in} \o \key{Ctrl++}
235     \row \o \gui{Zoom out}
236          \o Decreases the font size used to display text in the current tab.
237          \o \menu{View|Zoom out} \o \key{Ctrl+-}
238     \row \o \gui{Normal Size}
239          \o Resets the font size to its normal size in the current tab.
240          \o \menu{View|Normal Size} \o \key{Ctrl+0}
241     \endtable
242
243     \img assistant-address-toolbar.png
244
245     The address toolbar provides a fast way to enter a specific URL for a
246     documentation file. By default, the address toolbar is not shown, so it
247     has to be activated via \menu{View|Toolbars|Address Toolbar}.
248
249     \img assistant-filter-toolbar.png
250
251     The filter toolbar allows you to apply a filter to the currently installed
252     documentation. As with the address toolbar, the filter toolbar is not visible
253     by default and has to be activated via \menu{View|Toolbars|Filter Toolbar}.
254
255     \section1 Menus
256
257     \section2 File Menu
258
259     \list
260     \o \menu{File|Page Setup...} invokes a dialog allowing you to define
261     page layout properties, such as margin sizes, page orientation and paper size.
262     \o \menu{File|Print Preview...} provides a preview of the printed pages.
263     \o \menu{File|Print...} opens the \l{#Print Dialog}{\gui{Print} dialog}.
264     \o \menu{File|New Tab} opens a new empty tab in the \gui{Documentation}
265     window.
266     \o \menu{File|Close Tab} closes the current tab of the
267     \gui{Documentation} window.
268     \o \menu{File|Exit} closes the \QA application.
269     \endlist
270
271     \section2 Edit Menu
272
273     \list
274     \o \menu{Edit|Copy} copies any selected text to the clipboard.
275     \o \menu{Edit|Find in Text} invokes the \l{#Find Text Control}{\gui{Find Text}
276     control} at the lower end of the \gui{Documentation} window.
277     \o \menu{Edit|Find Next} looks for the next occurance of the specified
278     text in the \gui{Find Text} control.
279     \o \menu{Edit|Find Previous} looks for the previous occurance of
280     the specified text in the \l{#Find Text Control}{\gui{Find Text} control}.
281     \o \menu{Edit|Preferences} invokes the \l{#Preferences Dialog}{\gui{Preferences} dialog}.
282     \endlist
283
284     \section2 View Menu
285
286     \list
287     \o \menu{View|Zoom in} increases the font size in the current tab.
288     \o \menu{View|Zoom out} decreases the font size in the current tab.
289     \o \menu{View|Normal Size} resets the font size in the current tab.
290     \o \menu{View|Contents} toggles the display of the \gui{Contents} tool window.
291     \o \menu{View|Index} toggles the display of the \gui{Index} tool window.
292     \o \menu{View|Bookmarks} toggles the display of the \gui{Bookmarks} tool window.
293     \o \menu{View|Search} toggles the display of the Search in the \gui{Documentation} window.
294     \endlist
295
296     \section2 Go Menu
297
298     \list
299     \o \menu{Go|Home} goes to the home page.
300     \o \menu{Go|Back} displays the previous page in the history.
301     \o \menu{Go|Forward} displays the next page in the history.
302     \o \menu{Go|Sync with Table of Contents} syncs the \gui{Contents} tool window to the currently shown page.
303     \o \menu{Go|Next Page} selects the next tab in the \gui{Documentation} window.
304     \o \menu{Go|Previous Page} selects the previous tab in the \gui{Documentation} window.
305     \endlist
306
307     \section2 Bookmarks Menu
308
309     \list
310     \o \menu{Bookmarks|Add} adds the current page to the list of bookmarks.
311     \endlist
312
313     \section1 Dialogs
314
315     \section2 Print Dialog
316
317     This dialog is platform-specific. It gives access to various printer
318     options and can be used to print the document shown in the current tab.
319
320     \section2 Preferences Dialog
321
322     \img assistant-preferences-fonts.png
323
324     The \menu{Fonts} page allows you to change the font family and font sizes of the
325     browser window displaying the documentation or the application itself.
326
327     \img assistant-preferences-filters.png
328
329     The \menu{Filters} page lets you create and remove documentation
330     filters. To add a new filter, click the \gui{Add} button, specify a
331     filter name in the pop-up dialog and click \gui{OK}, then select
332     the filter attributes in the list box on the right hand side.
333     You can delete a filter by selecting it and clicking the \gui{Remove}
334     button.
335
336     \img assistant-preferences-documentation.png
337
338     The \menu{Documentation} page lets you install and remove compressed help
339     files. Click the \gui{Install} button and choose the path of the compressed
340     help file (*.qch) you would like to install.
341     To delete a help file, select a documentation set in the list and click
342     \gui{Remove}.
343
344     \img assistant-preferences-options.png
345
346     The \menu{Options} page lets you specify the homepage \QA will display when
347     you click the \gui{Home} button in \QA's main user interface. You can specify
348     the homepage by typing it here or clicking on one of the buttons below the
349     textbox. \gui{Current Page} sets the currently displayed page as your home
350     page while \gui{Restore to default} will reset your home page to the default
351     home page.
352
353     \section1 Find Text Control
354
355     This control is used to find text in the current page. Enter the text you want
356     to find in the line edit. The search is incremental, meaning that the most
357     relevant result is shown as you enter characters into the line edit.
358
359     If you check the \gui{Whole words only} checkbox, the search will only consider
360     whole words; for example, if you search for "spin" with this checkbox checked it will
361     not match "spinbox", but will match "spin". If you check the \gui{Case sensitive}
362     checkbox then, for example, "spin" will match "spin" but not "Spin". You can
363     search forwards or backwards from your current position in the page by clicking
364     the \gui{Previous} or \gui{Next} buttons. To hide the find control, either click the
365     \gui{Close} button or hit the \key{Esc} key.
366
367     \section1 Filtering Help Contents
368
369     \QA allows you to install any kind of documentation as long as it is organized
370     in Qt compressed help files (*.qch). For example, it is possible to install the
371     Qt reference documentation for Qt 4.4.0 and Qt 4.4.1 at the same time. In many
372     respects, this is very convenient since only one version of \QA is needed.
373     However, at the same time it becomes more complicated when performing tasks like
374     searching the index because nearly every keyword is defined in Qt 4.4.0 as well
375     as in Qt 4.4.1. This means that \QA will always ask the user to choose which one
376     should be displayed.
377
378     We use documentation filters to solve this issue. A filter is identified by its
379     name, and contains a list of filter attributes. An attribute is just a string and
380     can be freely chosen. Attributes are defined by the documentation itself, this
381     means that every documentation set usually has one or more attributes.
382
383     For example, the Qt 4.4.0 \QA documentation defines the attributes \c {assistant},
384     \c{tools} and \c{4.4.0}, \QD defines \c{designer}, \c{tools} and \c{4.4.0}.
385     The filter to display all tools would then define only the attribute
386     \c{tools} since this attribute is part of both documentation sets.
387     Adding the attribute \c{assistant} to the filter would then only show \QA
388     documentation since the \QD documentation does not contain this
389     attribute. Having an empty list of attributes in a filter will match all
390     documentation; i.e., it is equivalent to requesting unfiltered documentation.
391
392     \section1 Full Text Searching
393
394     \img assistant-search.png
395
396     \QA provides a powerful full text search engine. To search
397     for certain words or text, click the \gui{Search} tab in the \gui{Documentation}
398     window. Then enter the text you want to look for and press \key{Enter}
399     or click the \gui{Search} button. The search is not case sensitive, so,
400     for example, Foo, fOo and FOO are all treated as the same. The following are
401     examples of common search patterns:
402
403     \list
404     \o \c deep -- lists all the documents that contain the word 'deep'
405     \o \c{deep*} -- lists all the documents that contain a word beginning
406     with 'deep'
407     \o \c{deep copy} -- lists all documents that contain both 'deep' \e
408     and 'copy'
409     \o \c{"deep copy"} -- list all documents that contain the phrase 'deep copy'
410     \endlist
411
412     It is also possible to use the \gui{Advanced search} to get more flexibility.
413     You can specify some words so that hits containing these are excluded from the
414     result, or you can search for an exact phrase. Searching for similar words will
415     give results like these:
416
417     \list
418     \o \c{QStin} -- lists all the documents with titles that are similar, such as \c{QString}
419     \o \c{QSting} -- lists all the documents with titles that are similar, such as \c{QString}
420     \o \c{QStrin} -- lists all the documents with titles that are similar, such as \c{QString}
421     \endlist
422
423     Options can be combined to improve the search results.
424
425     The list of documents found is ordered according to the number of
426     occurrences of the search text which they contain, with those containing
427     the highest number of occurrences appearing first. Simply click any
428     document in the list to display it in the \gui{Documentation} window.
429
430     If the documentation has changed \mdash for example, if documents have been added
431     or removed \mdash \QA will index them again.
432
433 */
434
435 /*!
436     \page assistant-custom-help-viewer.html
437     \title Using Qt Assistant as a Custom Help Viewer
438
439     \contentspage {Qt Assistant Manual}{Contents}
440     \previouspage Qt Assistant in More Detail
441
442     Using \QA as custom help viewer requires more than just being able to
443     display custom documentation. It is equally important that the
444     appearance of \QA can be customized so that it is seen as a
445     application-specific help viewer rather than \QA. This is achieved by
446     changing the window title or icon, as well as some application-specific
447     menu texts and actions. The complete list of possible customizations
448     can be found in the \l{Creating a Custom Help Collection File} section.
449
450     Another requirement of a custom help viewer is the ability to receive
451     actions or commands from the application it provides help for. This is
452     especially important when the application offers context sensitive help.
453     When used in this way, the help viewer may need to change its contents
454     depending on the state the application is currently in. This means that
455     the application has to communicate the current state to the help viewer.
456     The section about \l{Using Qt Assistant Remotely} explains how this can
457     be done.
458
459     \tableofcontents
460
461     The \l{Simple Text Viewer Example}{Simple Text Viewer} example uses the
462     techniques described in this document to show how to use \QA as a custom
463     help viewer for an application.
464
465     \warning In order to ship Qt Assistant in your application, it is crucial
466     that you include the sqlite plugin. For more information on how to include
467     plugins in your application, refer to the \l{Deploying Qt Applications}
468     {deployment documentation}.
469
470     \section1 Qt Help Collection Files
471
472     The first important point to know about \QA is that it stores all
473     settings related to its appearance \e and a list of installed
474     documentation in a help collection file. This means, when starting \QA
475     with different collection files, \QA may look totally different. This
476     complete separation of settings makes it possible to deploy \QA as a
477     custom help viewer for more than one application on one machine
478     without risk of interference between different instances of \QA.
479
480     To apply a certain help collection to \QA, specify the respective
481     collection file on the command line when starting it. For example:
482
483     \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 8
484
485     However, storing all settings in one collection file raises some problems.
486     The collection file is usually installed in the same directory as the
487     application itself, or one of its subdirectories. Depending on the
488     directory and the operating system, the user may not have any permissions
489     to modify this file which would happen when the user settings are stored.
490     Also, it may not even be possible to give the user write permissions;
491     e.g., when the file is located on a read-only medium like a CD-ROM.
492
493     Even if it is possible to give everybody the right to store their settings
494     in a globally available collection file, the settings from one user would
495     be overwritten by another user when exiting \QA.
496
497     To solve this dilemma, \QA creates user specific collection files which
498     are more or less copied from the original collection file. The user-specific
499     collection file will be saved in a subdirectory of the path returned by
500     QDesktopServices::DataLocation. The subdirectory, or \e{cache directory}
501     within this user-specific location, can be defined in the help collection
502     project file. For example:
503
504     \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 7
505
506     So, when calling
507
508     \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 8
509
510     \QA actually uses the collection file:
511
512     \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 9
513
514     There is no need ever to start \QA with the user specific collection
515     file. Instead, the collection file shipped with the application should
516     always be used. Also, when adding or removing documentation from the
517     collection file (see next section) always use the normal collection file.
518     \QA will take care of synchronizing the user collection files when the
519     list of installed documentation has changed.
520
521     \section1 Displaying Custom Documentation
522
523     Before \QA is able to show documentation, it has to know where it can
524     find the actual documentation files, meaning that it has to know the
525     location of the Qt compressed help file (*.qch). As already mentioned,
526     \QA stores references to the compressed help files in the currently used
527     collection file. So, when creating a new collection file you can list
528     all compressed help files \QA should display.
529
530     \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 5
531
532     Sometimes, depending on the application for which \QA acts as a
533     help viewer, more documentation needs to be added over time; for
534     example, when installing more application components or plugins.
535     This can be done manually by starting \QA, opening the \gui{Edit|Preferences}
536     dialog and navigating to the \gui{Documentation} tab page. Then click
537     the \gui{Add...} button, select a Qt compressed help file (*.qch)
538     and press \gui{Open}. However, this approach has the disadvantage
539     that every user has to do it manually to get access to the new
540     documentation.
541
542     The prefered way of adding documentation to an already existing collection
543     file is to use the \c{-register} command line flag of \QA. When starting
544     \QA with this flag, the documentation will be added and \QA will
545     exit right away displaying a message if the registration was successful
546     or not.
547
548     The search indexing will only index your custom *.html, *.htm,
549     and *.txt files.
550
551     \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 6
552
553     The \c{-quiet} flag can be passed on to \QA to prevent it from writing
554     out the status message.
555
556     \bold{Note:} \QA will show the documentation in the contents view in the same
557     order as it was registered.
558
559
560     \section1 Changing the Appearance of Qt Assistant
561
562     The appearance of \QA can be changed by passing different command line options
563     on startup. However, these command line options only allow to show or hide
564     specific widgets, like the contents or index view. Other customizations, such
565     as changing the application title or icon, or disabling the filter functionality,
566     can be done by creating a custom help collection file.
567
568     \section2 Creating a Custom Help Collection File
569
570     The help collection file (*.qhc) used by \QA is created when running the
571     \c qcollectiongenerator tool on a help collection project file (*.qhcp).
572     The project file format is XML and supports the following tags:
573
574     \table
575         \header
576             \o Tag
577             \o Brief Description
578         \row
579             \o \c{<title>}
580             \o This property is used to specify a window title for \QA.
581         \row
582             \o \c{<homePage>}
583             \o This tag specifies which page should be display when
584             pressing the home button in \QA's main user interface.
585         \row
586             \o \c{<startPage>}
587             \o This tag specifies which page \QA should initially
588             display when the help collection is used.
589         \row
590             \o \c{<currentFilter>}
591             \o This tag specifies the \l{Qt Assistant in More Detail#Preferences Dialog}{filter}
592             that is initially used.
593             If this filter is not specified, the documentation will not be filtered. This has
594             no impact if only one documentation set is installed.
595         \row
596             \o \c{<applicationIcon>}
597             \o This tag describes an icon that will be used instead of the normal \QA
598             application icon. This is specified as a relative path from the directory
599             containing the collection file.
600         \row
601             \o \c{<enableFilterFunctionality>}
602             \o This tag is used to enable or disable user accessible filter functionality,
603             making it possible to prevent the user from changing any filter when running \QA.
604             It does not mean that the internal filter functionality is completely disabled.
605             Set the value to \c{false} if you want to disable the filtering. If the filter
606             toolbar should be shown by default, set the attribute \c{visible} to \c{true}.
607         \row
608             \o \c{<enableDocumentationManager>}
609             \o This tag is used to specify whether the documentation manager should be shown
610             in the preferences dialog. Disabling the Documentation Manager allows you to limit
611             \QA to display a specific documentation set or make it impossible for the end user
612             to accidentally remove or install documentation. To hide the documentation manager,
613             set the tag value to \c{false}.
614         \row
615             \o \c{<enableAddressBar>}
616             \o This tag describes if the address bar can be shown. By default it is
617             enabled; if you want to disable it set the tag value to \c{false}. If the
618             address bar functionality is enabled, the address bar can be shown by setting the
619             tag attribute \c{visible} to \c{true}.
620         \row
621             \o \c{<aboutMenuText>, <text>}
622             \o The \c{aboutMenuText} tag lists texts for different languages which will
623             later appear in the \menu{Help} menu; e.g., "About Application". A text is
624             specified within the \c{text} tags; the \c{language} attribute takes the two
625             letter language name. The text is used as the default text if no language
626             attribute is specified.
627         \row
628             \o \c{<aboutDialog>, <file>, <icon>}
629             \o The \c{aboutDialog} tag can be used to specify the text for the \gui{About}
630             dialog that can be opened from the \menu{Help} menu. The text is taken from the
631             file in the \c{file} tags. It is possible to specify a different file or any
632             language. The icon defined by the \c{icon} tags is applied to any language.
633         \row
634             \o \c{<cacheDirectory base="collection|default">}
635             \o The cache directory is used to store index files
636             needed for the full text search and a copy of the collection file.
637             The copy is needed because \QA stores all its settings in the collection file; i.e., it must be writable for the user.
638             The directory is specified as a relative path. 
639             If the \c{base} attribute is set to "collection", the path is 
640             relative to the directory the collection file resides in. 
641             If the attribute is set to "default" or if it is missing, 
642             the path is relative to the directory given by 
643             QDesktopServices::DataLocation. The first form is useful for 
644             collections that are used in a "mobile" way, e.g. carried around 
645             on a USB stick.
646         \row
647             \o \c{<enableFullTextSearchFallback>}
648             \o This tag describes the ability to fallback and use the full text
649             search if a keyword can't be found in the index. This functionality
650             can be used while remote controlling \QA. To make it available for
651             remote control set the tag value to \c{true}.
652     \endtable
653
654     In addition to those \QA specific tags, the tags for generating and registering
655     documentation can be used. See \l{The Qt Help Framework#Creating a Qt Help Collection}
656     {Qt Help Collection} documentation for more information.
657
658     An example of a help collection file that uses all the available tags is shown below:
659
660     \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 1
661
662     To create the binary collection file, run the \c qcollectiongenerator tool:
663
664     \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 10
665
666     To test the generated collection file, start \QA in the following way:
667
668     \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 8
669
670     \section1 Using Qt Assistant Remotely
671
672     Even though the help viewer is a standalone application, it will mostly
673     be launched by the application it provides help for. This approach
674     gives the application the possibility to ask for specific help contents
675     to be displayed as soon as the help viewer is started. Another advantage
676     with this approach is that the application can communicate with the
677     help viewer process and can therefore request other help contents to be
678     shown depending on the current state of the application.
679
680     So, to use \QA as the custom help viewer of your application, simply
681     create a QProcess and specify the path to the Assistant executable. In order
682     to make Assistant listen to your application, turn on its remote control
683     functionality by passing the \c{-enableRemoteControl} command line option.
684
685     The following example shows how this can be done:
686
687     \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 2
688
689     Once \QA is running, you can send commands by using the stdin channel of
690     the process. The code snippet below shows how to tell \QA to show a certain
691     page in the documentation.
692
693     \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 3
694
695     Note that the trailing newline character is required to mark the end
696     of the input.
697
698     The following commands can be used to control \QA:
699
700     \table
701         \header
702             \o Command
703             \o Brief Description
704         \row
705             \o \c{show <Widget>}
706             \o Shows the dock widget specified by <Widget>. If the widget
707             is already shown and this command is sent again, the widget will be
708             activated, meaning that it will be raised and given the input focus.
709             Possible values for <Widget> are "contents", "index", "bookmarks" or "search".
710         \row
711             \o \c{hide <Widget>}
712             \o Hides the dock widget specified by <Widget>. Possible values for
713             <Widget> are "contents", "index", "bookmarks" and "search".
714         \row
715             \o \c{setSource <Url>}
716             \o Displays the given <Url>. The URL can be absolute or relative
717             to the currently displayed page. If the URL is absolute, it has to
718             be a valid Qt help system URL; i.e., starting with "qthelp://".
719         \row
720             \o \c{activateKeyword <Keyword>}
721             \o Inserts the specified <Keyword> into the line edit of the
722             index dock widget and activates the corresponding item in the
723             index list. If such an item has more than one link associated
724             with it, a topic chooser will be shown.
725         \row
726             \o \c{activateIdentifier <Id>}
727             \o Displays the help contents for the given <Id>. An ID is unique
728             in each namespace and has only one link associated to it, so the
729             topic chooser will never pop up.
730         \row
731             \o \c{syncContents}
732             \o Selects the item in the contents widget which corresponds to
733             the currently displayed page.
734         \row
735             \o \c{setCurrentFilter <filter>}
736             \o Selects the specified filter and updates the visual representation
737             accordingly.
738         \row
739             \o \c{expandToc <Depth>}
740             \o Expands the table of contents tree to the given depth. If depth
741             is 0, the tree will be collapsed completely. If depth is -1,
742             the tree will be expanded completely.
743         \row
744             \o \c{register <help file>}
745             \o Adds the given Qt compressed help file to the collection.
746         \row
747             \o \c{unregister <help file>}
748             \o Removes the given Qt compressed help file from the collection.
749     \endtable
750
751     If you want to send several commands within a short period of time, it is
752     recommended that you write only a single line to the stdin of the process
753     instead of one line for every command. The commands have to be separated by
754     a semicolon, as shown in the following example:
755
756     \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 4
757
758     \section1 Compatibility with Old Formats
759
760     In older versions of Qt, the help system was based on Document Content File
761     (DCF) and Qt Assistant Documentation Profile (ADP) formats. In contrast,
762     Qt Assistant and the help system used in Qt 4.4 use the formats described
763     earlier in this manual.
764
765     Unfortunately, the old file formats are not compatible with the new ones.
766     In general, the differences are not that big \mdash in most cases is the old
767     format is just a subset of the new one. One example is the \c namespace tag in
768     the Qt Help Project format, which was not part of the old format, but plays a vital
769     role in the new one. To help you to move to the new file format, we have created
770     a conversion wizard.
771
772     The wizard is started by executing \c qhelpconverter. It guides you through the
773     conversion of different parts of the file and generates a new \c qch or \c qhcp
774     file.
775
776     Once the wizard is finished and the files created, run the \c qhelpgenerator
777     or the \c qcollectiongenerator tool to generate the binary help files used by \QA.
778 */
779
780 /*
781 \section2 Modifying \QA with Command Line Options
782
783     Different help collections can be shown by simply passing the help collection
784     path to \QA. For example:
785
786     \snippet doc/src/snippets/code/doc_src_assistant-manual.qdoc 0
787
788     Other available options the can be passed on the command line.
789
790     \table
791         \header
792             \o Command Line Option
793             \o Brief Description
794         \row
795             \o -collectionFile <file.qhc>
796             \o Uses the specified collection file instead of the default one.
797         \row
798             \o -showUrl URL
799             \o Shows the document referenced by URL.
800         \row
801             \o -enableRemoteControl
802             \o Enables \QA to be remotly controlled.
803         \row
804             \o -show <widget>
805             \o Shows the specified dockwidget which can be "contents", "index",
806             "bookmarks" or "search".
807         \row
808             \o -hide <widget>
809             \o Hides the specified dockwidget which can be "contents", "index",
810             "bookmarks" or "search.
811         \row
812             \o -activate <widget>
813             \o Activates the specified dockwidget which can be "contents",
814             "index", "bookmarks" or "search.
815         \row
816             \o -register <doc.qch>
817             \o Registers the specified compressed help file in the given help
818             collection.
819         \row
820             \o -unregister <doc.qch>
821             \o Unregisters the specified compressed help file from the given
822             collection file.
823         \row
824             \o -quiet
825             \o Doesn't show any error, warning or success messages.
826     \endtable
827     */