helpviewer

Start Photon Helpviewer

Syntax:

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]

Options:

-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.

-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 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.

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. 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:

/usr/help/product/photon/user_guide/pdm.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.

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.

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:

Supported entities

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

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

where:

level

The heading level. A value of 1 represents a top level heading, which users can access directly from the Contents tree.

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.

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

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.

Files:

/usr/help/product/photon/bookset.html

Default home page.

/usr/help/product

Default topic directory.

~/.photon/helpviewer/options

Configuration file.

~/.photon/helpviewer/hotlist

Bookmarks save file.

~/.photon/helpviewer/history

History save file.