DVX Help Viewer

DVX Help shows help pages. The list on the left is the table of contents, the page you are reading is on the right, and underlined words are links to other pages. You can also look things up in the Index or with Search.

Tip: New to DVX? Click the Program Manager window and press F1, or choose DVX Help from the Program Manager's Help menu, to open the DVX user guide. It explains how to start programs, work with windows, menus, and dialog boxes, and everything else that works the same in every program. Each program's own commands are explained in that program's help: press F1 while you work in it.

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.

If the help viewer is already running, F1 reuses its window: the requested page is shown there (loading the other application's help file if needed, which starts a fresh Back/Forward history) and the window is brought to the front. The Help menu of the Program Manager does the same. F1 pressed in the help viewer itself shows this help about the viewer. While the viewer's Index or Search dialog is open, the page asked for with F1 is shown once the dialog closes.

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

Searching

Search looks through the title and text of every topic. Type one or more words separated by spaces; a topic matches when it contains all of them, in any order and in any mix of upper and lower case. Words may be partial: "scroll" also finds "ScrollPane". Index keywords that contain the whole search text match as well. Words need at least three letters or digits in a row to be looked up in topic text; a search made only of shorter words (such as "if" or "a b") matches topic titles and index keywords only. When one topic matches it is shown at once; otherwise pick one from the list of matching topics.

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 in the same help
                       file (see Links below)
  .image <file> [left|center|right]
                       Inline image (BMP, PNG, JPEG, or GIF), path
                       relative to the -i directory

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

File Directives

  .include <file>      Insert another source file here (path absolute or
                       relative to the including file)
  .section <name>      Group the following table of contents entries of
                       this file under a <name> heading
  .section <a>|<b>     Nest the group: heading <b> sits under heading <a>
                       (any depth; entries filed under <a> come first)

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] [--quiet] input.dhs [@filelist] [...]

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
  --quiet             Suppress progress output
  @filelist           Read more input file names from filelist, one per
                      line (blank lines and lines starting with # are
                      skipped)

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

Input Files

Each input file starts fresh: no topic is current and no .list, .note, .code, or .table block is left open from the previous file. Text before a file's first .topic is ignored, and directives there are errors. A .code or .table block still open at the end of a file is closed with a warning. Files named with .include are different: they are read in place, as if their lines were part of the including file.

Source lines longer than 4094 characters, and lines that contain a NUL byte, are errors. The .image directive may name a path relative to the -i directory, including a subdirectory (for example sub/pic.png).

If any error is reported the compile stops and the previous output file is kept.

Links

Every .link must name a topic that is compiled into the same help file: a topic in any of the input files or the files they include, before or after the link. A link to any other ID is an error that names the file, the line, and the missing ID. The one exception is the help DVX rebuilds by itself when it starts after programs, widgets, or libraries were added or removed: there a link to a topic that is no longer present shows as plain text instead, so removing a piece of DVX never breaks the rest of the help. Links cannot reach into another help file; name the other file's page in the text instead. A .link line inside a .code block is example text and is never checked.

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

Every DVX application should have its own help file. F1 in the application, and the Contents command of its Help menu, open it. An application with no help file of its own gets the DVX user guide on F1.

Applications in the DVX Source Tree

For an application built with DVX itself, write the help source as <app>.dhs in the application's source directory, next to <app>.c or <app>.dbp, where <app> is the name of the application's .app file. The build finds it by that name: it compiles it to <app>.hlp next to <app>.app, deploys the source, and writes an <APP>.HCF so the help is rebuilt on the target too. Nothing else needs to be listed anywhere.

C Applications

Name the help file after the application (myapp.hlp beside myapp.app) and F1 works with no code: before appMain runs, DVX sets ctx->helpFile to that file when it exists. A help file with any other name or location is set in appMain instead:

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

To open it from a Help menu item, call shellOpenHelp. It reuses a running help viewer (and brings it to the front) instead of starting another one:

shellOpenHelp(ctx->shellCtx, ctx->helpFile);

The argument is "helpfile [topicId]", so a menu item can also open a particular topic. An empty help file name opens the DVX user guide, as F1 does for an application without a help file.

Context-Sensitive Topics

Update helpTopic as the user moves around your application, or set onHelpQuery to a function that fills it in when F1 is pressed:

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

When the user presses F1, the help viewer opens your help file at that topic.

DVX BASIC Applications

A DVX BASIC program gets its help file from its project: set Help File in Project Properties. The file is copied next to the compiled program, and F1 opens it at the HelpTopic of the focused control, or else of the form. As for C applications, a myapp.hlp next to myapp.app is used when the project names no help file. To open it from a Help menu item, add help.bas to the project and call HelpView with the file name; a name without a folder is looked for next to the program:

SUB mnuHelpContents_Click
    HelpView "myapp.hlp"
END SUB