Skip to content

Using the Help Editor

The Help Editor is where the content for each portion of the help page is authored, for items such as methods, properties, and enums. The rich fields are authored as Markdown or HTML depending on the help template the project uses — see Which editor appears below. 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.).

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 along the top of the Help Editor when those fields are available for the selected item.

The Preview tab shows how the generated driver help will look, based on the edits in progress and the selected help template, which is controlled by the help project properties.

For details on customizing help templates to add custom fields, see Custom Fields (Markdown templates) or Editing Template Pages (legacy HTML templates).

Which editor appears

The Help Editor adapts to the help template the project uses:

  • With a Markdown template (the recommended Markdown help template system), rich fields such as Remarks are authored in an embedded Markdown editor with a live, side-by-side preview. Because Markdown allows embedded HTML, raw HTML can still be dropped in where a topic needs custom layout.
  • With a legacy HTML template, those fields are authored as HTML in the embedded Visual Studio HTML editor (see the XHTML note below).

The Summary and Return value fields are always plain text (described below), regardless of which template is in use.

Help content is entered using the Help Editor by selecting the field 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. An item left without a summary is reported as NIM0002 when the driver is analyzed.

The reason plain text must be used for the Summary field is that this field is used in places that do not support markup — 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.

All other fields, such as Remarks (including fields defined by help template customizations), are authored in the editor that matches the template — Markdown or HTML. For example, the same Remarks content might be authored as Markdown:

The **StartFrequency** property gets or sets the frequency at which the frequency sweep
will begin. The units are Hz.

or, with a legacy HTML template, as XHTML:

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

Help content can link to three kinds of targets:

  • External pages, such as a support website — use an ordinary link with a standard URL (for example, https://www.pacificmindworks.com).
  • Boilerplate help pages — use the page name including its extension, with no path information.
  • Driver items — interfaces, methods, properties, functions, attributes, enums, and so on.

To link to a driver item, right-click it in the Driver Designer, choose Copy help link to clipboard, and paste it into the content (the display text is supplied by the author). Nimbus produces the right form for the project’s template system and resolves it to the correct generated page when the help is built:

  • In a Markdown template, the command produces a Markdown cross-reference of the form [text](xref:{id}) that survives renames. See Linking to API Topics.
  • In a legacy HTML template, it produces an HTML anchor whose target uses a name- or GUID-based syntax. See Linking to Driver Items.

A link whose target doesn’t resolve when the help is built is reported as NIM0001.