helpviewer

Photon Helpviewer

Syntax:

helpviewer [-b color] [-f color] [-h height[%]]
           [-l color] [-m] [-o] [-r topic.toc]
           [-S i|m|n] [-s server]
           [-t topic_dir]
           [-w width[%]] [-x position[%][r]]
           [-y position[%][r]] [url]

Runs on:

Neutrino

Options:

-b color
Set background color to the hex RBG value.
-f color
Set foreground (text) color to the hex RBG value.
-h height[%]
The height of the window, in pixels, or as a percentage of the screen height if % is specified.
-l color
Set link color to the hex RBG value.
-m
Turn on caching (increase memory to speed up searching).
-o
Keep the topics in the same order as the TOC file (default is to sort the top two levels of topics).
-r topic.toc
Display only the specified topics from the topic root. You can specify more than one -r option.
-Si|m|n
The initial state of the main window (iconified, maximized, or normal).
-s server_name
The name of the Photon server:
If server_name is: This server is used:
node_path node_path/dev/photon
fullpath fullpath
relative_path /dev/relative_path
-t topic_dir
Display the help file referred to by the topic directory.
-w width[%]
The width of the window, in pixels, or as a percentage of the screen width if % is specified.
-x position[%][r]
The x coordinate of the upper-left corner of the window, in pixels, or as a percentage of screen width if % is specified. If r is specified, the coordinate is relative to the current console.
-y position[%][r]
The y coordinate of the upper-left corner of the window, in pixels, or as a percentage of screen height if % is specified. If r is specified, the coordinate is relative to the current console.
url
Display the help file referred to by the URL.

Description:

The helpviewer application displays online help, with several navigational aids including contents, text search, history, and bookmarks.

The helpviewer supports online help documents written in HTML. However, the helpviewer can access only local files and therefore can't be used as an Internet Web browser. It also supports GIF, JPEG, and BMP image formats.

You can specify which HTML file to open using either URLs or topic paths:

The helpviewer loads the table of contents either from a single topic file (with a .toc extension) or from a directory. By default the topic files are loaded from the /usr/help/product directory. The format of topic files is described in "Creating topic files" below.

Creating help files:

The helpviewer supports help files written in HTML level 3.2 with some extensions. You can create HTML help files using a text editor or special HTML editors or word processors.


Note: You should take care not to include features above HTML level 3.2 in your help files (they might cause helpviewer to crash).

Supported elements

The following table shows the HTML elements and attributes supported by the helpviewer:

Element Tags Attributes
Comment <!-- comment -->
Document <html>...</html>
Head <head>...</head>
Title <title>...</title>
Link <link> href=url, rel=string
Body <body>...</body> id=string, bgcolor=hexvalue, link=hexvalue, text=hexvalue
Heading 1 <h1>...</h1> id=string, align=left|center|right
Heading 2 <h2>...</h2> id=string, align=left|center|right
Heading 3 <h3>...</h3> id=string, align=left|center|right
Heading 4 <h4>...</h4> id=string, align=left|center|right
Heading 5 <h5>...</h5> id=string, align=left|center|right
Heading 6 <h6>...</h6> id=string, align=left|center|right
Rule <hr>
Paragraph <p>...[</p>] id=string
Linebreak <br> id=string
Image <img> src=url, align=top|middle|bottom, alt=string, id=string
Anchor <a>...</a> href=url, name=string, id=string
Preformatted <pre>...</pre> id=string
Blockquote <blockquote>...</blockquote> id=string
Address <address>...</address> id=string
Note <note>...</note> src=url, id=string
Definition list <dl>...</dl> compact, id=string
Term <dt>...[</dt>] id=string
Description <dd>...[</dd>] id=string
Ordered list <ol>...</ol> id=string
Unordered list <ul>...</ul> id=string
List item <li>...[</li>] id=string
Emphasis <em>...</em>
Strong <strong>...</strong>
Code <code>...</code>
Sample <samp>...</samp>
Keyboard <kbd>...</kbd>
Variable <var>...</var>
Definition <dfn>...</dfn>
Citation <cite>...</cite>
Teletype <tt>...</tt>
Bold <b>...</b>
Italic <i>...</i>
Underlined <u>...</u>
Table <table>...</table> border, border=0, align=left|center|right, id=string
Table heading <th>...[</th>] align=left|center|right, id=string
Table data <td>...[</td>] align=left|center|right, id=string
Table row <tr>...[</tr>] id=string

Supported entities

The Helpviewer also supports the standard HTML1/ISO entities for characters, plus:

Entity: Meaning: Rendered as:
&nbsp; Nonbreaking space Space
&emsp; Em-space Space
&ensp; En-space Space
&mdash; Em-dash Dash (-)
&ndash; En-dash Dash (-)
&ldquo; Left double quote Double quote (")
&rdquo; Right double quote Double quote (")
&lsquo; Left single quote '
&rsquo; Right single quote '
&trade; Trademark TM

Creating topic files

The helpviewer uses a table of contents and directory hierarchy to organize the online help. The table of contents is kept separate from the HTML files themselves and is not part of the HTML definition.

Topic files must be created by hand based on your online help files. You can create either a single topic file or a hierarchy of topic files in different directories.

Topic files must have a .toc extension. They are text files with one topic per line. Each topic line has the following format:

level|title|HTML or TOC file

where:

level
The heading level. A value of 1 represents a top-level heading, which users can access directly from the Topics tree. Heading levels 1 and 2 are sorted alphabetically in the Topics tree; levels 3 and lower appear in the order they occur in the TOC file.
title
Text of the topic title (do not include any HTML -- use plain text only).
HTML or TOC file
Either an HTML file/URL or a TOC file.

Note: Don't use the vertical bar (|) in topic titles, because it's used as a delimiter in the TOC files.

Usually there's an entry in the topic file corresponding to each HTML heading level in your help files. The topic title doesn't have to be identical to the title in your help file.

Each topic can refer to an HTML file or a topic file. If the topic refers to an HTML file, that file is displayed when the topic is selected. If the topic refers to a topic file, helpviewer reads the subtopics from that file and displays them, but no HTML is displayed.

If the HTML file is in a subdirectory of the parent topic, helpviewer scans the directory for topic files (this happens up to topic level 4 only). You don't have to specify the topic file explicitly in this case.

You can increase the performance of the helpviewer by creating toc_index files in directories that contain several TOC files. A toc_index simply lists the TOC files in that directory, and is created by typing

ls *.toc > toc_index.

The helpviewer assumes that your help is maintained in a three-level directory hierarchy. The levels and the types of files that should be kept at each level are listed below.

Level 1

The top level help system directory.

This level contains a folder for each bookset in the help system, and a top level TOC file for each bookset.

An example is /usr/help/product, which contains several booksets, including:

Level 2

The bookset level directory.

This level contains a folder and TOC file for each book in the bookset, and a top level HTML file for the bookset.

An example is /usr/help/product/ide_en, which contains:

Level 3

The book level directory.

This level contains a TOC file and one or more topic HTML files. It may optionally contain sub-directories to organize HTML files into chapters. The TOC file has level-3 and lower entries for every topic in the help for the book.

An example is /usr/help/product/phindows_en/user_guide, which contains:

Your help must use the same three-level hierarchy, even if there is only one book. The helpviewer uses a combination of the topic level in the TOC file and the directory level of the TOC file to nest topics in the contents pane.

An example

Here is an example of how .toc files can be nested. In the /usr/help/product directory the Photon help directory and top-level TOC file are located:

photon_2.0_en.toc
photon_2.0_en/

The photon_2.0_en.toc file consists of the following line:

1|Photon microGUI for QNX Neutrino|./photon_2.0_en/bookset.html

The photon_2.0_en directory contains a TOC file and a directory for each book. For example, for the Programmer's Guide, the directory includes:

prog_guide.toc
prog_guide/

The prog_guide.toc file consists of the following line:

2|Programmer's Guide|./prog_guide/about.html

The prog_guide directory contains the HTML files, and a book.toc file that identifies the topic titles in the HTML files:

3|About This Guide|about.html#ABOUTTHISGUIDE
4|Assumptions|#id3
4|Changes and corrections|#ChangesAndCorrections
3|Introduction|intro.html#id1
4|Photon Application Builder - PhAB|#PhABApplications
6|Get immediate results|#id3
...

The part of the URL following the # is an anchor defined in the HTML.


Note: If the .toc files contain non-ASCII characters, they must be in multibyte format to be displayed correctly in the Contents pane.

The Photon ped editor allows the entry of UTF-8 characters. For more information, see the ped man page.


Publishing your topic file

You can either include your table of contents in the default table of contents (along with our online documentation) or keep it separate and specify where helpviewer can find the table of contents.

Including your help in the default help

To include your help in the default table of contents, you must create a top-level topic file and include it in the root help directory (/usr/help/product). The helpviewer reads all topic files from the root directory and sorts the topics alphabetically.

Keeping your help separate

Similarly, to start the helpviewer with your own table of contents and help files, change the default help file directory using the -t option, like this:

helpviewer -t /home/user/mytopics

The helpviewer application displays your table of contents and home page only. You won't be able to access the default table of contents.

Searching

You can search the documentation by entering keywords in the Find field and then pressing the Go! button. The following characters are considered to be separators:

,.:&()[]/\"#{};?-+=!\n space

Using the above characters, the helpviewer splits your input into keywords. It then searches its database for each keyword and keeps only the results that include all the keywords. If you haven't checked Match Whole Words, the search is a partial match search for each of the keywords. For example, "Toggle" will match "PtToggle". Check Case sensitive to match the case of the keywords.

You can use a space as an AND operator. For example, if you search for Photon coordinate space in the document text, the helpviewer finds all the documents that contain the words Photon, coordinate, and space. It doesn't necessarily mean that the listed documents include the full string Photon coordinate space.

Files:

/usr/help/product
Default topic directory.
~/.ph/phelp/options
Configuration file.
~/.ph/phelp/bookmarks
Your bookmarks.
~/.ph/phelp/history
A list of the documents you've viewed.

See also:

"Getting help with the Helpviewer" in the Using the Photon microGUI chapter of the Neutrino User's Guide