238 lines
6.8 KiB
Text
238 lines
6.8 KiB
Text
# The MIT License (MIT)
|
|
#
|
|
# Copyright (C) 2026 Scott Duensing
|
|
#
|
|
# Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
# of this software and associated documentation files (the "Software"), to
|
|
# deal in the Software without restriction, including without limitation the
|
|
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
|
|
# sell copies of the Software, and to permit persons to whom the Software is
|
|
# furnished to do so, subject to the following conditions:
|
|
#
|
|
# The above copyright notice and this permission notice shall be included in
|
|
# all copies or substantial portions of the Software.
|
|
#
|
|
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
|
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
|
|
# IN THE SOFTWARE.
|
|
|
|
.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
|