[Previous] [Contents] [Index] [Next]


Start Photon Helpviewer


helpviewer [-b color] [-f color] [-h height] [-l color]
           [-m] [-o] [-S i|m|n] [-s server]
           [-T tocfile | tocdir] [-t topic] [-w width]
           [-x x_pos] [-y y_pos] [url]


-b color
Set background color to the hex RBG value.
-f color
Set foreground (text) color to the hex RBG value.
-h height
Set initial height of window to height pixels.
-l color
Set link color to the hex RBG value.
Turn on caching (increase memory to speed up searching).
Keep the topics in the same order as the TOC file (default is to sort the topics).
-S i|m|n
Specify initial window state (i - iconify, m - maximize, n - normal).
-s server
Specify Photon server node or device name.
-T tocfile | tocdir
Use tocfile as the topic file or use tocdir for topic files.
-t topic
Display the help file referred to by the topic path.
-w width
Set initial width of window to width pixels.
-x x_pos
Initial x_pos position of window.
-y y_pos
Initial y_pos position of window.
Display the help file referred to by the URL.


The helpviewer application displays online help, with several navigational aids including contents, text search, history, and bookmarks. For information on using helpviewer, see the section "Using the Helpviewer" in the Getting Help chapter in the Photon User's Guide.

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

You can specify which HTML file to open using either Universal Resource Locators (URLs) or topic paths.

The URL specifies the filesystem path where the help text is located on the local network. Here's an example of a URL:


Note: URLs are case-sensitive. These URLs are restricted in scope to the local help files; they can't be used to access the Web.

A topic path comprises a number of concatenated topic titles, as defined in the current table of contents. Here's an example of a topic path:

/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 /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 1.0 with some extensions. You can create HTML help files using a text editor or special HTML editors or word processors.

Note: Since HTML has now progressed to level 3.0, you should take care not to include features above level 1.0 in your help files (which 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 (")
&trade; Trademark TM

Creating topic files

The helpviewer uses a table of contents 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


The heading level. A value of 1 represents a top level heading, which users can access directly from the Contents tree.
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.

Usually there will be 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 will be displayed when the topic is selected. If the topic refers to a topic file, helpviewer will read the subtopics from that file and display them, but no HTML will be displayed.

If the HTML file is in a subdirectory of the enclosing topic, helpviewer will scan 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 don't have to specify the full directory path for each topic if it's the same as the enclosing topic. For example, the topic file shown below contains a single book with two chapters:

1 | Book | /help/book.html
2 | Chapter 1 | chapter1/chapter.html
3 | Section 1 | section1.html
4 | Subsection 1 | #subsection1
4 | Subsection 2 | #subsection2
3 | Section 2 | section2.html
2 | Chapter 2 | chapter2/chapter.html
3 | Section 1 | section1.html
3 | Section 2 | section2.html

Note: If the .toc files contain non-ASCII characters, they must be in multibyte format to be displayed correctly in the Contents pane. For information on compose sequences used by Photon, see the section "Composing international characters" in the Unicode Multilingual Support chapter.

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.

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.

To load your own table of contents, start the helpviewer like this:

helpviewer -T /home/user/topics.toc /home/user/home.html

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


Default home page.
Default topic directory.
Configuration file.
Bookmarks save file.
History save file.

[Previous] [Contents] [Index] [Next]