Skip to content

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.

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.

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:

  1. Its build process emits the help files discussed above.
  2. It houses the help template files used to control the look and feel of the driver help files.

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\IviNet
    • NimbusInstallDir\HelpTemplates\Default\IviCom
    • NimbusInstallDir\HelpTemplates\Default\IviC
  • Legacy

    The legacy HTML template system — HTML template pages with $$PLACEHOLDER$$ tags and a Manifest.xml table 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\IviNet
    • NimbusInstallDir\HelpTemplates\Legacy\IviCom
    • NimbusInstallDir\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”
  1. From Solution Explorer, right click on the driver help project node and select Properties access the help project’s properties.

  2. Click on the Template tab.

  3. Choose a template from the Available templates combo box. The list that appears contains the templates present in the NimbusInstallDir\HelpTemplates folder.

  4. Click the Switch to this template button.

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:

  • IviCAttribute
  • IviCBranch
  • IviCCallbackFunction
  • IviCErrorsWarnings
  • IviCFunction
  • IviCLibrary

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.