Basics of Driver Help Files
This topic presents an overview of how Nimbus help files are created, managed, and customized. Other topics under the topic Creating a Driver Help File present detailed information on specific driver help issues.
Authoring Help Content
Section titled “Authoring Help Content”Nimbus constructs help files and other documentation artifacts from the content entered in the various Help Editors. Methods, properties, parameters, interfaces, enums, errors, and warnings all have a Help Editor that is accessed by selecting a specific item in the Driver Designer.
The content created using the Help Editors is stored in the Nimbus design file and ultimately used for several purposes. IVI drivers may be used in numerous IDEs, so the driver documentation must be rendered in several formats to create a complete user experience. Nimbus uses the help content from the Help Editors to automatically produce a range of documentation artifacts. The classic help formats are available with either template system:
-
HTML 1.0 help file (.chm)
A standalone compiled help file used by nearly all IDEs except Visual Studio.
-
Microsoft Help Viewer help file (.mshc or .cab)
A help file used by Visual Studio. It integrates with the Visual Studio local help so that driver help content appears alongside Visual Studio’s own help content as well as that of other products that integrate with Visual Studio. Microsoft Help Viewer files may be digitally signed using a certificate (.cab) or distributed without being signed (.mshc). The topic Signing Microsoft Help Viewer Content explains how help file signing works.
-
XML IntelliSense file
IVI drivers used within .NET programming languages, such as Visual C#, require a specially formatted XML file to present IntelliSense help as end users type code.
The Markdown help template system additionally produces:
-
Markdown
Clean GitHub-Flavored Markdown files for hosting on GitHub, GitLab, or any Markdown-native platform.
-
Semantic HTML
Chrome-free HTML with stable class names, for integrating the content into another website or toolchain.
-
MadCap Flare HTML
Content prepared for import into a MadCap Flare project.
-
Starlight web site
A complete, ready-to-deploy documentation site (Astro Starlight) with search, navigation, and responsive layout.
Which artifacts are produced depends on the template in use and the formats selected; see Output Formats.
Since all of the help content is consolidated in a single location via the Help Editors, managing the various help artifacts is simple. Changing the content for a particular item in the Help Editor updates the help information for that item in all of the above locations.
The set of help file formats produced for an IVI driver is controlled via help project properties. The default settings chosen for new help projects can be controlled by per-user preferences.
The Driver Help Project
Section titled “The Driver Help Project”Every Nimbus driver solution includes a driver help project named as follows:
<projectName>Help
The driver help project serves two roles in IVI driver development:
- Its build process emits the help files discussed above.
- It houses the help template files used to control the look and feel of the driver help files.
Help File Appearance and Help Templates
Section titled “Help File Appearance and Help Templates”The Template subfolder of the driver help project contains a number of files used to control the appearance of the driver HTML 1.0 Microsoft Help Viewer files. (For convenience, all supported help file formats are referred to here as simply the “driver help file”, since they contain the same content and since the help template applies to them identically.) Collectively, these files are referred to as the help template and they are used to control nearly every aspect of the driver help file appearance.
Nimbus ships with two pre-built template families, each maintained separately for every driver type (IVI.NET, IVI-COM, and IVI-C):
-
Default (recommended)
The Markdown help template system. It uses Markdown and Mustache and can produce the full range of output formats, including a complete web site. Installed in:
NimbusInstallDir\HelpTemplates\Default\IviNetNimbusInstallDir\HelpTemplates\Default\IviComNimbusInstallDir\HelpTemplates\Default\IviC
-
Legacy
The legacy HTML template system — HTML template pages with
$$PLACEHOLDER$$tags and aManifest.xmltable of contents — which mimics the classic MSDN help appearance. It remains fully supported and produces the CHM and Microsoft Help Viewer formats. Installed in:NimbusInstallDir\HelpTemplates\Legacy\IviNetNimbusInstallDir\HelpTemplates\Legacy\IviComNimbusInstallDir\HelpTemplates\Legacy\IviC
Nimbus selects the system automatically from the template: a template with a manifest.yaml uses the Markdown system; a template with a Manifest.xml uses the legacy system.
When a new driver project is created with the New Project Wizard, Nimbus copies all of the files from the selected help template folder to the driver’s help project folder. This allows help template customizations to be done on a per-driver basis, without affecting the pre-installed help templates.
To change the help template after a driver has been created
Section titled “To change the help template after a driver has been created”-
From Solution Explorer, right click on the driver help project node and select Properties access the help project’s properties.
-
Click on the Template tab.
-
Choose a template from the Available templates combo box. The list that appears contains the templates present in the
NimbusInstallDir\HelpTemplatesfolder. -
Click the Switch to this template button.
Special note on IVI-COM Help Templates
Section titled “Special note on IVI-COM Help Templates”IVI-COM help templates that include an IVI-C wrapper use template files from the IVI-C template for portions of the driver help file. The following folders within the IVI-C template are used by the IVI-COM help template:
IviCAttributeIviCBranchIviCCallbackFunctionIviCErrorsWarningsIviCFunctionIviCLibrary
Customizing Help File Appearance
Section titled “Customizing Help File Appearance”Nimbus provides complete flexibility in controlling nearly all aspects of the driver help file. Content and appearance can be controlled by customizing the help template. Everything from custom boilerplate content to vendor-specific branding can be implemented with the Nimbus help template customization features. For the recommended Markdown templates, see The Markdown Help Template System; for the legacy HTML templates, see Legacy HTML Templates.