The purpose of this document is to set out what information the online help for Qt Extended should contain and how that information is to be formatted. This includes the positioning of tags, use of headings and images, and the rules governing when such hyperlinks as See Also should be used.
Content
The Qt Extended help pages are written in a subset of the HTML language.
The Qt Extended online help system provides the capability to provide context-sensitive help for any screen displayed by the Qt Extended server or by a Qt Extended application. The QObject::setObjectName() function should be called when constructing each screen in order to set the name that the Help Browser will use to find the correct help page.
Each help page should describe the purpose of the corresponding screen and what actions the user can perform on that screen, including the meaning of each menu option. Due to the restricted screen space on most devices, help descriptions should be brief and concise. The main help page for an application will generally also provide links to the pages describing the main screens provided by that application.
Help pages should be written to be applicable in all cases. If there is something dynamic that would change the documentation, there are a number of ways to use the Help Browser Preprocessor to present the correct content. The preprocessor can handle both device-specific content and content that depends on certain boolean properties of a running Qt Extended system.
Headings
Each help page should include a title tag. This title will be displayed in the Qt Extended title bar when the page is being viewed in the Help Browser. As the page title will therefore always be visible to the user, there is no need to include the title in the body of the page.
Long pages may contain sub-headings, though overly long pages should be divided into smaller pages referenced by hyperlinks from the main topic page.
Images and Icons
Images and icons may be used freely in help pages, but each page should generally reference only the following images and icons: <ul> <li>the set of images and icons that belong to that application (i.e. those installed by the application's project file at build time),</li> <li>the set of images and icons that are shared by all applications (i.e. those installed by the Qt Extended server's project file at build time), and>/li> <li>the icons provided by the help browser itself (such as the icon for the directional keypad).</li> </ul>
Images and icons are referenced using the same naming scheme that is used in Qt Extended source code. This naming scheme is aware of internationalization. For example:
<img src=":icon/options"> </img> Options menu icon
<img src=":icon/i18n/back"> </img> Back icon used in context bar. Differs for left-to-right and right-to-left languages.
<img src=":icon/help/dpad"> </img> Icon for the directional keypad.
<img src=":image/qtopia"> </img> Qt Extended logo.
When writing help text, it is important to remember that the Qt Extended soft-menu bar can display either text labels or icons. Therefore, when referring to the soft-menu bar, help text should include both the text and the icon of the soft-menu item, as shown below.
To abandon the message completely, press <img src=":icon/options"><b>Options</b> and select <b>Cancel</b>.
In some cases, a help author will want to place a space after an image in the help text. To make this work, you must include the whitespace within the image tag, as shown below.
<img src=":icon/datebook/audible"> </img> shows that a task has an audible reminder.
Layout
This section explains when different terms, methods of sectioning, and images should be used.
| Term | Usage |
|---|
| Index | Applied to a topic page that lists subordinate pages |
| See Also | Used when a topic outside the current one is of direct relevance and does not have an in-text link (in-text links are preferred). |
| Fullstops in lists | Use a fullstop if the list item is a complete sentence or a significant sentence fragment. |
| Hyphenate | Always hyphenate the following: pop-up, check-box, combo-box, |
| Do not hyphenate | Do not hyphenate the following: email |
| Bold | Use bold tags for the following: menu options, screen names, key / button names, and fields, |
| Screen or Dialog | Use the term dialog when referring to a message directed at the user that requires a response (a dialog between device and user) all others are screens (even though they collect input in fields etc). |
| Window | Do not use this term. Instead use the term screen or dialog (see above for clarification). |
Rules on Hyperlinks
| Item | Rule |
|---|
| See Also | This should only be used if the link cannot be placed neatly within the text. |
| Back/parent links | Should not be used since the Qt Extended Help Browser has a Back function and since most pages can be reached in a variety of ways (resulting in an unclear return path). |
| Go to | Avoid using this if possible. Used for main topic pages that can be reached via more than one parent. This does not include links from child pages belonging to another main topic. |
