DVX Help Viewer

The DVX Help Viewer displays .hlp help files compiled from .dhs source documents. It provides a tree-based table of contents, scrollable content with word-wrapped text, clickable hyperlinks, full-text search, and a keyword index.

Opening Help

Press F1 from any DVX application to open context-sensitive help. Applications can register their own help file and topic so F1 opens the relevant page.

You can also launch the help viewer from an application's Help menu, or by clicking the DVX Help icon in the Program Manager.

Navigation

• Click a topic in the tree on the left to display it
• Click underlined links in the content to jump to other topics
• Use the Back and Forward buttons (or Navigate menu) to retrace your steps
• Use Navigate > Index to browse an alphabetical keyword list

Use Navigate > Search to find topics by keyword

Keyboard Shortcuts

  Alt+Left     Back
  Alt+Right    Forward
  Ctrl+F       Search
  Escape       Close viewer

Help Source Format (.dhs)

Help files are authored as plain text .dhs source files using a simple line-oriented directive format. Lines beginning with a period at column 0 are directives. All other lines are body text, which is automatically word-wrapped by the viewer at display time.

Topic Directives

  .topic <id>          Start a new topic with a unique string ID
  .title <text>        Set the topic's display title
  .toc <depth> <text>  Add a table of contents entry (0=root, 1=child, etc.)
  .default             Mark this topic as the one shown when the file opens

Content Directives

  .h1 <text>           Level 1 heading (colored bar)
  .h2 <text>           Level 2 heading (underlined)
  .h3 <text>           Level 3 heading (plain)
  .hr                  Horizontal rule
  .link <id> <text>    Hyperlink to another topic
  .image <file.bmp>    Inline image (BMP format)

Block Directives

  .list                Start a bulleted list
  .item <text>         List item (must be inside .list)
  .endlist             End the bulleted list
  .table               Start a preformatted table block
  .endtable            End table block
  .code                Start a preformatted code block
  .endcode             End code block
  .note [info|tip|warning]   Start a callout box
  .endnote             End callout box

Index Directives

  .index <keyword>     Add a keyword to the index pointing to this topic

Example

.topic intro
.title Welcome
.toc 0 Welcome
.default
.index Welcome

.h1 Welcome

This is a paragraph of body text. It will be
automatically word-wrapped by the viewer.

.list
.item First item
.item Second item
.endlist

.link other.topic See also: Other Topic

.note info
This is an informational note.
.endnote

.note tip
This is a helpful tip.
.endnote

.note warning
This is a warning message.
.endnote

Callout Boxes

Three types of callout boxes are available, each with a distinct colored accent bar:

Note: Use info notes for general supplementary information.

Tip: Use tip notes for helpful suggestions and best practices.

Warning: Use warning notes for important cautions the reader should be aware of.

Help Compiler (dvxhlpc)

The dvxhlpc tool runs on the host (Linux) and compiles .dhs source files into binary .hlp files for the viewer, and optionally into self-contained HTML.

Usage

dvxhlpc -o output.hlp [-i imagedir] [--html out.html] input.dhs [...]

Options

  -o output.hlp       Output binary help file (required)
  -i imagedir         Directory to find .image files (default: current dir)
  --html out.html     Also emit a self-contained HTML file

Multiple input files are merged into a single help file. This allows per-widget or per-feature documentation fragments to be combined automatically.

Build Integration

The standard build pattern globs all fragments:

dvxhlpc -o dvxhelp.hlp docs/src/overview.dhs widgets/*/*.dhs

New widgets or features just drop a .dhs file in their source directory and it appears in the help on the next build.

HTML Output

The --html flag produces a single self-contained HTML file with a sidebar table of contents, styled headings, lists, code blocks, notes, and embedded images (base64 data URIs). This is useful for viewing documentation on the host machine without running the DOS help viewer.

Application Integration

Any DVX application can provide context-sensitive help via the F1 key.

Setting Up Help

In your appMain, set the help file path on the app context:

snprintf(ctx->helpFile, sizeof(ctx->helpFile),
         "%s%cMYAPP.HLP", ctx->appDir, DVX_PATH_SEP);

Context-Sensitive Topics

Update helpTopic as the user navigates your application:

snprintf(ctx->helpTopic, sizeof(ctx->helpTopic), "settings.video");

When the user presses F1, the shell launches the help viewer with your help file opened to the specified topic.

Launching Help from Menus

To add a Help menu item that opens your help file:

shellLoadAppWithArgs(ctx, viewerPath, helpFilePath);