Changing the Table of Contents

The driver help file table of contents is specified in a special XML file in the Template folder of the driver help project. This file is referred to as the help template manifest file, and it is always named Manifest.xml.

The code below is an excerpt from the manifest file for an IVI.NET driver:

Manifest.xml

  <HelpTOC Resource="IviNetDriver.TocRoot.html">
    <HelpTOCNode Resource="GettingStarted.html">
      <HelpTOCNode Resource="IviBackgrounder.html">
        <HelpTOCNode Resource="InherentCapabilities.html"/>
        <HelpTOCNode Resource="Interchangeability.html"/>
        <HelpTOCNode Resource="InstrumentSpecificCapabilities.html"/>
        <HelpTOCNode Resource="IviSharedComponents.html"/>
        <HelpTOCNode Resource="RepeatedCapabilities.html"/>
        <HelpTOCNode Resource="LxiFundamentals.html"/>
      </HelpTOCNode>
      <HelpTOCNode Resource="Installation.html"/>
      <HelpTOCNode Resource="IviCompliance.html" Condition="NotNoClass" Output="IviCompliance.html"/>
      <HelpTOCNode Resource="IviComplianceNoClass.html" Condition="NoClass" Output="IviCompliance.html"/>
      <HelpTOCNode Resource="IviConfigStore.html"/>
    </HelpTOCNode>
    <HelpTOCNode Resource="IviNetDriver.html">
      <HelpTOCNode Resource="IviNetInitialize.html"/>

The \<HelpTOC\> element is the root of the help table of contents. Child \<HelpTOCNode\> elements are used to create a hierarchy of help topics. The Resource attribute refers to the HTML file that contains the content for the topic. The title is established by a special \<MSHelp:TOCTitle\> element within the HTML file itself.

Topics can be removed from the help file by simply deleting them from the manifest file. Alternatively, the help topics can be rearranged by simply moving the desired \<HelpTOCNode\> elements in the desired order.

Tip

Nimbus installs the schema file (including documentation comments) for the manifest file. This provides IntelliSense support for available XML elements and attributes when editing the help template manifest file in Visual Studio.

Special Content Topics

Most of the help topics that appear in the final driver help file are not listed explicitly in the help template manifest file. For instance, the help topics for the driver methods and properties (or functions and attributes, in the case of IVI-C drivers) do not explicitly appear in this XML file. These topics are far too numerous to include in the help template manifest file, so they are instead generated dynamically and placed under special topics that have a Content attribute.

The special content topics are included in the manifest file so that other topics can be arranged around them to produce the desired table of contents. The following code snippet shows all of the special content topics for an IVI.NET driver.

Manifest.xml

<!-- ... -->

    <HelpTOCNode Resource="IviNetDriverReference.html">
      <HelpTOCNode Title="Driver Hierarchy" Content="IviNetHierarchy"/>
      <HelpTOCNode Title="Driver Interfaces" Content="IviNetFlat"/>
      <HelpTOCNode Resource="IviNetCommandReference.html"/>
    </HelpTOCNode>

<!-- ... -->

Conditionally Including Help Topics

Help topics can be conditionally included by use of the Condition attribute. In the example below, the help topic for “AccessingRepCaps.html” will only be included in the help file if the condition “RepCap” is true. This particular condition is true as long as the driver includes one or more repeated capabilities. Similarly, the help topic for “IviNetClassCompliant-IviDCPwr.html” will only be included if the driver implements the IviDCPwr instrument class. Conditions are generally used when adding custom boilerplate help content.

IviNetDriverHelpTemplate.xml

<HelpTOCNode Resource="IviNetClassCompliant-IviDCPwr.html" Condition="IviDCPwr" Output="IviNetClassCompliant.html"/>

<!-- ... -->

<HelpTOCNode Resource="AccessingRepCaps.html" Condition="RepCap"/>

The table below lists all of the pre-built conditions that can be used for conditionally including help file content:

Condition	Description
Lxi	True if the driver is compliant with the LXI Core 2016 base class.
NotLxi	True if the driver is not compliant with the LXI Core 2016 base class.
LxiClockSynchronization	True if the driver supports the LXI Clock Synchronization extended function.
LxiEventLogs	True if the driver supports the LXI Event Logs extended function.
LxiEventMessaging	True if the driver supports the LXI Event Messaging extended function.
LxiTimestampedData	True if the driver supports the LXI Timestamped Data extended function.
LxiWiredTriggerBus	True if the driver supports the LXI Wired Trigger Bus extended function.
RepCap	True if the driver has at least one repeated capability.
NotRepCap	True if the driver does not have any repeated capabilities.
NoClass	True if the driver does not implement an instrument class.
NotNoClass	True if the driver implements at least one instrument class.
IviCounter	True if the driver implements the IviCounter instrument class.
IviDCPwr	True if the driver implements the IviDCPwr instrument class.
IviDigitizer	True if the driver implements the IviDigitizer instrument class.
IviDmm	True if the driver implements the IviDmm instrument class.
IviDownconverter	True if the driver implements the IviDownconverter instrument class.
IviFgen	True if the driver implements the IviFgen instrument class.
IviPwrMeter	True if the driver implements the IviPwrMeter instrument class.
IviRFSigGen	True if the driver implements the IviRFSigGen instrument class.
IviScope	True if the driver implements the IviScope instrument class.
IviSpecAn	True if the driver implements the IviSpecAn instrument class.
IviSwtch	True if the driver implements the IviSwtch instrument class.
IviUpconverter	True if the driver implements the IviUpconverter instrument class.

Using the Output Attribute to Change Content File Names

When help pages are conditionally included as described in the previous section, it can be difficult or impossible to manage links to the conditionally included pages. For example, consider the following portion of a help template manifest file:

Manifest.xml

<HelpTOC>
  <HelpTOCNode Resource="GettingStarted.html">
    <HelpTOCNode Resource="Installation.html"/>
    <HelpTOCNode Resource="IviComplianceWithClass.html" Condition="NotNoClass"/>
    <HelpTOCNode Resource="IviComplianceNoClass.html" Condition="NoClass"/>
    <HelpTOCNode Resource="IviConfigStore.html"/>
  </HelpTOCNode>

If the driver complies with at least one instrument class, the content file “IviComplianceWithClass.html” will be included in the help file. If the driver does not comply with any instrument class, the content file “IviComplianceNoClass.html” will be included in the help file. Other pages within the help file may wish to create a link to whichever of these two files was included. For instance, the first help topic “GettingStarted.html” is a parent of the two pages and likely needs to include a link to all of its child topics. Since links cannot be conditional, this presents a fundamental problem.

Nimbus provides the Output attribute to enable links to be created to conditionally included content. The Output attribute simply renames a content file from the name indicated by the Resource attribute to that specified with the Output attribute. Conditionally included topics use the Output attribute to “re-direct” multiple mutually exclusive topics to the same file name so that links can be created to the conditionally included topics.

The following example demonstrates use of the Output attribute.

IviNetDriverHelpTemplate.xml

<HelpTOC>
  <HelpTOCNode Resource="GettingStarted.html">
    <HelpTOCNode Resource="Installation.html"/>
    <HelpTOCNode Resource="IviComplianceWithClass.html" Condition="NotNoClass"  Output="IviCompliance.html"/>
    <HelpTOCNode Resource="IviComplianceNoClass.html" Condition="NoClass" Output="IviCompliance.html"/>
    <HelpTOCNode Resource="IviConfigStore.html"/>
  </HelpTOCNode>

In the above example, the Output attribute has been used with the conditionally included topics “IviComplianceWithClass.html” and “IviComplianceNoClass.html”. Irrespective of which of these topics is included in the help file, the resulting file name will be “IviCompliance.html”. This allows other help pages to create links to the “IviCompliance.html” page without regard to the conditional inclusion logic.

See also

• Using the Help Template Previewer
• Adding Boilerplate Pages
• Editing Template Pages
• Sharing Help Templates Across Projects