 | 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 explicity 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 speical 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