.topic help.overview
.title DVX Help Viewer
.toc 0 DVX Help Viewer
.default
.index DVX Help
.index Help Viewer

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

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

.h2 Navigation

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

.h2 Keyboard Shortcuts

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

.topic help.format
.title Help Source Format (.dhs)
.toc 0 Help Source Format
.index .dhs
.index Source Format
.index Directives

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

.h2 Topic Directives

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

.h2 Content Directives

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

.h2 Block Directives

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

.h2 Index Directives

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

.h2 Example

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

.h2 Callout Boxes

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

.note info
Use info notes for general supplementary information.
.endnote

.note tip
Use tip notes for helpful suggestions and best practices.
.endnote

.note warning
Use warning notes for important cautions the reader should be aware of.
.endnote

.topic help.compiler
.title Help Compiler (dvxhlpc)
.toc 0 Help Compiler
.index dvxhlpc
.index Compiler

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

.h2 Usage

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

.h2 Options

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

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

.h2 Build Integration

The standard build pattern globs all fragments:

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

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

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

.topic help.integration
.title Application Integration
.toc 0 Application Integration
.index F1
.index Context Help
.index helpFile
.index helpTopic
.index shellLoadAppWithArgs

.h1 Application Integration

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

.h2 Setting Up Help

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

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

.h2 Context-Sensitive Topics

Update helpTopic as the user navigates your application:

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

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

.h2 Launching Help from Menus

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

.code
shellLoadAppWithArgs(ctx, viewerPath, helpFilePath);
.endcode