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]

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

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

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:

• a folder and top level TOC for the IDE help, ide_en and ide_en.toc.
• The TOC has a single level-1 entry pointing to the top level HTML file for the bookset, ide_en/bookset.html.

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:

• bookset.html -- the base HTML page for the bookset
• user_guide -- a directory for the User's Guide book
• user_guide.toc -- a TOC file with a single level-2 entry pointing to the top level HTML file for the book, user_guide/about.html.

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:

• about.html -- an HTML file that contains all the content for the book
• book.toc -- a TOC file that contains all the help topic entries for the table of contents.

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.

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.

Indluding 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