Photon Helpviewer
helpviewer [-b color] [-f color] [-F start_page] [-h height[%]] [-l color] [-m] [-o] [-r topic.toc] [-S i|m|n] [-s server] [-t topic_dir] [-u home_page] [-w width[%]] [-x position[%][r]] [-y position[%][r]] [url]
Neutrino
If server_name is: | This server is used: |
---|---|
node_path | node_path/dev/photon |
fullpath | fullpath |
relative_path | /dev/relative_path |
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:
$QNX_TARGET/usr/help/product/neutrino/user_guide/examples.html
URLs are case-sensitive. These URLs are restricted in scope to the local help files; they can't be used to access the Web. |
/Photon microGUI/User's Guide/Utilities/pdm
For convenience, the topic path is case-insensitive and may contain the wildcard characters * or ?, where * matches a string and ? matches a character. The first matching topic is selected for display.
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 $QNX_TARGET/usr/help/product directory. The format of topic files is described in “Creating topic files” below.
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.
You should take care not to include features above HTML level 3.2 in your help files (they might cause helpviewer to crash). |
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 |
The Helpviewer also supports the standard HTML1/ISO entities for characters, plus:
Entity: | Meaning: | Rendered as: |
---|---|---|
| Nonbreaking space | Space |
  | Em-space | Space |
  | En-space | Space |
— | Em-dash | Dash (-) |
– | En-dash | Dash (-) |
“ | Left double quote | Double quote (“) |
” | Right double quote | Double quote (”) |
‘ | Left single quote | ‘ |
’ | Right single quote | ’ |
™ | Trademark | TM |
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:
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.
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:
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 $QNX_TARGET/usr/help/product/ide_en, which contains:
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 $QNX_TARGET/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.
Here is an example of how .toc files can be nested. In the $QNX_TARGET/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.
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. |
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.
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.
These environment variables are set by default by the sh and ksh shells, and are specified in /etc/profile.d/qnxsdk.sh. If you use a different shell (such as esh or bsh), you need to explicitly set these environment variables or helpviewer will not display the default QNX help. |
“Getting help with the Helpviewer” in the Using the Photon microGUI chapter of the Neutrino User's Guide