Linking to API Topics
Conceptual topics and custom fields such as a method’s Remarks frequently need to link to a generated API topic — for example, “call this after setting TriggerSource,” where TriggerSource should link to that property’s help page. Nimbus does this with a cross-reference, which it resolves to the correct page in every output format when the help builds.
A cross-reference names its target in one of two ways. An identifier, copied from the Driver Designer, is exact and survives renames. A name is the one to write by hand. Both are covered below.
Inserting a cross-reference
Section titled “Inserting a cross-reference”-
In the Driver Designer, right-click the item to link to — an interface, method, property, function, attribute, enum, and so on.
-
Choose Copy help link to clipboard.
-
Paste into a conceptual topic or a custom field (such as Remarks).
The pasted text is an ordinary Markdown link whose target is the item’s stable identifier:
[TriggerSource](xref:60cbe70b-1d2e-4f3a-9c10-2b8e4a1f77d2)The link text (TriggerSource) is seeded from the item’s name and may be edited freely to
suit the surrounding sentence (“the trigger source,” and so on). The xref: target must be
left as generated.
The identifier is opaque, so this form is one to copy rather than to type. To write a link by hand, name the item instead — see Linking by name below.
Why an identifier survives renames
Section titled “Why an identifier survives renames”The target identifies the item by its stable internal ID, not by its name or page path, which
is why the link survives renames. When a link is made to TriggerSource and that property is
later renamed, the cross-reference still resolves to the renamed page on the next build, with
nothing to find and correct. The visible link text is authored prose and does not change
automatically, but the link continues to point at the correct topic.
Because the target is the item’s identity rather than a path, the generated folder structure never has to be known or kept in sync. The same cross-reference resolves correctly in every output format: CHM, Microsoft Help Viewer, Markdown, Semantic HTML, MadCap Flare, and the Starlight web site.
Linking by name
Section titled “Linking by name”An xref: target may also name the item, which is the form to use when writing prose without the
Driver Designer at hand:
[Abort](xref:Abort)[the channel's Configure method](xref:Acme4301Channel.Configure)Names resolve the same way in every output format, and against the same folder structure, as an identifier does. A member may be named on its own or qualified by its declaring type; for IVI.NET, the namespace-qualified form resolves as well.
Choosing between overloads
Section titled “Choosing between overloads”Where a name belongs to more than one item, add a qualifier. Neither qualifier character can appear in an identifier, so a name is never mistaken for one:
| Form | Selects |
|---|---|
xref:Configure-2 | The overload taking two parameters. |
xref:Transform`1 | The generic overload with one type parameter. |
xref:Transform`2-6 | One type parameter count and one parameter count together. |
A qualifier is optional and only ever narrows: a name that already identifies one item needs none.
When a name is not specific enough
Section titled “When a name is not specific enough”A name that still matches several items after its qualifiers are applied does not resolve, and is reported as an ambiguous help link (NIM0003). The message lists the items that share the name, so that one can be selected.
When a target no longer exists
Section titled “When a target no longer exists”If an xref: target’s item has been deleted, the link cannot resolve and is reported as a
broken help link (NIM0001) in the build output, the same diagnostic reported
for any other broken link in help content. A stale cross-reference surfaces as a warning rather than
silently breaking.
Where the link lands
Section titled “Where the link lands”None of this is configurable, but a link resolves to the same place the navigation leads:
- IVI.NET — a link to a member that appears in the driver hierarchy resolves to that member’s page in the hierarchy (the implementing-class page). Members that are not part of the hierarchy (enums, structs, standalone types) link to their own page.
- IVI-COM — a link to a repeated-capability interface resolves to the coclass page, where that interface is documented.
- IVI-C — links resolve to the corresponding function, attribute, and branch pages.