Click or drag to resize

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

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 create the following:

  • HTML 1.0 help file (.chm)

    This is a standalone help file that is used by nearly all IDEs except for Visual Studio.

  • Microsoft Help Viewer help file (.mshc or .cab)

    This is a help file that is 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 the help content 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.

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

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.

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, we will refer to all supported help file formats 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 one pre-built template:

  • Classic

    Generates a driver help file that mimics the classic MSDN help file appearance. Separate templates are maintained for each type of driver (IVI.NET, IVI-COM, and IVI-C). These are installed in the following folders:

    • NimbusInstallDir\HelpTemplates\Classic\IviNet

    • NimbusInstallDir\HelpTemplates\Classic\IviCom

    • NimbusInstallDir\HelpTemplates\Classic\IviC

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

  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.

    Caution note Caution

    This step deletes all of the files in the current driver help project's Template subfolder. Any customizations done to this point are lost. Make sure no files of interest remain in the help project's Templates subfolder before clicking the Switch to this template button.

    Note Note

    If your driver help project is integrated with a Visual Studio source control system, this operation automatically performs the necessary source code control operations to add, remove and otherwise update the help template files included in the driver help project.

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:

  • IviCAttribute

  • IviCBranch

  • IviCCallbackFunction

  • IviCErrorsWarnings

  • IviCFunction

  • IviCLibrary

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. The topic Working with Help Templates explains in detail how to control every aspect of driver help file appearance.

Important note Important

It is critical to never directly edit the pre-built help template files installed in the NimbusInstallDir\HelpTemplates folder. To customize a help template, you must first make a copy of the entire template and then edit the copy. Refer here for details on creating custom help templates.

See Also

Download a complete CHM version of this documentation here.