Click or drag to resize

Using the Help Editor

The Help Editor allows you to enter raw HTML content for each portion of the help page for items such as methods, properties, enums, etc. The behavior of the Help Editor is very similar for each item type, so the information in this topic applies equally well to all item types (methods, properties, parameters, etc.).

Help Editor Basics

Each help page for an item, such as a method, is divided into independently editable regions termed fields. Available fields are listed along the top of the Help Editor. Every item has a Summary tab. Other fields, such as Return value or Remarks, appear long the top of the Help Editor when those fields are available for the selected item.

The Preview tab allows you to preview how the generated driver help will look based on the edits you're making and the selected help template, which is controlled by the help project properties.

For details on customizing help templates to add custom fields, see the topic Working with Help Templates.

Entering Help Content

Help content is entered using the Help Editor by selecting the field you wish to modify (which appear as separate tabs along the top of the Help Editor), and then using the editor to make the desired changes.

When editing the Summary and Return value fields, there are special limitations in what may be entered. First, the text is limited to 256 characters total. Secondly, a plain text editor is used to enter the help content.

For all other fields, such as the Remarks field, the native Visual Studio HTML editor is used. The reason plain text must be used for the Summary field is that this field is used in places that do not support HTML -- such as driver installers and XML IntelliSense files. See the topic Basics of Driver Help Files for details on where the driver help content is used.

The Visual Studio HTML editor is used to for editing the Remarks field as well as other fields (including those defined by help template customizations). An example entry is shown below.

XML
Copy
The <b>StartFrequency</b> property gets or sets the frequency at which the frequency sweep
will begin.  The units are Hz.
Important note Important

Even though the built-in Visual Studio HTML editor is used for editing HTML content, the contents of these fields must be XHTML, which is a stricter form of HTML. Among other things, this means that all HTML tags must be closed just like XML tags are. For example, instead of using <hr> to insert a horizontal separator, you must use <hr/> or <hr></hr>. If any XHTML rules are violated, the driver help previewerwill display an error, and the help project will fail to build.

Help content is required to be XHTML in order to integrate with the Microsoft Help Viewer that's used by Visual Studio.

Adding links to the help content

Nimbus supports adding help content with links to pages and other content. By using the standard HTML anchor tag (<a>), you can create the following kinds of links:

  • External links, such as to a support website.

  • Links to auto-generated pages, such as method and property help pages.

  • Links to fixed-content, boilerplate help pages.

Links to external content, such as web pages, is done in the standard fashion with standard URIs, such as www.pacificmindworks.com. Links to boilerplate pages is also simple in that only the name of the page (without any path information) is used as the URI in the <a> tag.

Since the help pages for Nimbus-generated content are created when the help project is built, the pages themselves are not actually available at development time. Thus, Nimbus supports a simple syntax for creating links to Nimbus-generated pages. The syntax for these links depends upon the type of driver under development. However, the simplest way to obtain a link to a particular item is to use the Copy help link to clipboard command available from the Driver Designer context menu.

To insert a link to a driver item:

  1. Within the Driver Designer, right-click on the item (interface, method, property, etc) that you wish to link to.

  2. Select Copy help link to clipboard.

  3. Navigate to the Remarks field or other HTML-enabled custom field for the item in which you wish to insert the link.

  4. Paste the clipboard contents at the desired location. Nimbus will have created a properly formatted HTML anchor tag for the item of interest. Note that the display text for the anchor tag must still be supplied.

Format for Help Links

Because the type system for IVI.NET drivers is much richer than that of either IVI-COM or IVI-C, it is difficult to use a help link format based on type name and type member names. Method overloading and .NET generics introduce considerable complexity into any name-based scheme for uniquely identifying IVI.NET items. Thus, Nimbus uses GUIDs to name the generated help HTML files. These GUIDS are persisted in the driver design file, so they are stable across builds and Visual Studio sessions. This also makes the GUIDs a logical candidate for creating IVI.NET help links.

Tip Tip

Because the GUIDs associated with IVI.NET items are maintained internally, the Copy help link to clipboard command mentioned earlier should be used to create IVI.NET driver help links.

For IVI-COM and IVI-C drivers, the Copy help link to clipboard is also the preferred way to create help links. However, because of the relative simplicity of the IVI-COM and IVI-C type systems, the help links for these drivers use simple type and member names. The example below demonstrates how to create some of these links and the table following the example specifies the syntax for all supported IVI-COM and IVI-C link types.

XML
Copy
<!-- Link to the Configure method on the IAcme4321Trigger interface -->
This method differs from the <a href="IAcme4321Trigger.Configure">Configure</a> method in that...

<!-- Link to the Acme4321TriggerMode enum -->
The <i>Mode</i> parameter can take on any value in the <a href="Acme4321TriggerMode">Acme4321TriggerMode</a> enum.

<!-- Link to the error and warnings page.  Note that all errors and warnings appear on a single page. -->
If the instrument cannot switch to <i>Mode</i>, the <a href="ErrorsAndWarnings">E_ACME4321_BAD_MODE</a> error is returned.

<!-- Link to an external website -->
For more information, see the whitepaper on our <a href="http://www.acme.com/support">website</a>.

The following table specifies the URI syntax for all supported IVI-COM and IVI-C link types.

Link Type

URI Syntax

Example

External link

Standard URI syntax

http://www.acme.com/support

Boilerplate page

Page name, including extension (no path)

AcmeDriverBasics.html

IVI-COM interface

Full interface name

IAcme4321Trigger

IVI-COM method

<interface>.<method>

IAcme4321Trigger.Configure

IIviScopeMeasurement.Fetch

IVI-COM property

<interface>.<property>

IAcme4321Trigger.Source

IIviScopeAcquisition.NumberOfAverages

IVI-COM enum

Full enum name

Acme4321TriggerSourceEnum

IviScopeAcquisitionTypeEnum

IVI-COM error

Special string "ErrorsAndWarnings"

All IVI-COM errors and warnings for a typelib appear on a single page.

ErrorsAndWarnings

IviScope.ErrorsAndWarnings

IVI-COM warning

Special string "IviComErrorsAndWarnings"

All IVI-COM errors and warnings for a typelib appear on a single page.

IviComErrorsAndWarnings

IviScope.IviComErrorsAndWarnings

IVI-C function

Function name (no prefix)

ConfigureTrigger

IVI-C attribute

Attribute name (no prefix)

TRIGGER_SOURCE

IVI-C error

Special string "IviCErrorsAndWarnings"

All IVI-C errors and warnings appear on a single page.

IviCErrorsAndWarnings

IVI-C warning

Special string "IviCErrorsAndWarnings"

All IVI-C errors and warnings appear on a single page.

IviCErrorsAndWarnings

See Also

Download a complete CHM version of this documentation here.