Creating Topic Links

Both the TechWriter comment models and Annotation editor support creating topic links that allow the readers of your documentation to navigate from one topic through a reference to another topic. If you are creating topic links using the Annotation editor, it takes care of all of the details for you. But if you are manually creating the links directly within your XML schema comments, you will need to know the details on the syntax of the target of your link.

While JavaDoc, XHTML and XML Comments all use different tags for formatting links, the syntax of the link target is independent of the comment model. Link targets that start with http: or https: are considered external link targets and should represent a URL to a web page. Link targets that do not start with http: or https: are considered topic link targets and should have the following syntax:

<Item Type>.<XML Schema Name>[#<Local Item Name>]

or

<Item Type>.<Qualified Item Name>

where

<Item Type> is type of item that is being linked to. This part of the link target is required and must have one of the following values:

Schemas
Elements
Attributes
Complex+Types
Simple+Types

<XML Schema Name> is the friendly name given to the schema containing the topic that is being linked to. This part of the link target is required.

<Local Item Name> is the name of the item whose topic is being linked to. If this part of the link target is omitted, the link target will reference the summary topic for the specified item type.

<Qualified Item Name> is the name of the item whose topic is being linked to that is qualified with the target namespace of the defining schema. Qualified item names have the following syntax:

<Namespace>:<Local Item Name>

where

<Namespace> is the URL form of the target namespace, not the prefix.

Link targets must not contain any spaces. If any of the names used to create the link target do have spaces, they should be replaced with plus sign (+) characters.

See the table below for example topic links.

Type of Topic Link Example

XML Schema Summary Topic Schemas.MARCXML

Element Summary Topic Elements.MARCXML

Element Topic Elements.MARCXML#collection

Element Topic (qualified name) Elements.http://www.loc.gov/MARC21/slim:collection

Attribute Topic Attributes.MARCXML#id+[type+collectionType]

Attribute Topic (qualified name) Attributes.http://www.loc.gov/MARC21/slim:id+[type+collectionType]

Complex Type Topic Complex+Type.MARCXML#collectionType

Simple Type Topic Simple+Type.MARCXML#tagDataType

Type of Topic Link	Example
XML Schema Summary Topic	Schemas.MARCXML
Element Summary Topic	Elements.MARCXML
Element Topic	Elements.MARCXML#collection
Element Topic (qualified name)	Elements.http://www.loc.gov/MARC21/slim:collection
Attribute Topic	Attributes.MARCXML#id+[type+collectionType]
Attribute Topic (qualified name)	Attributes.http://www.loc.gov/MARC21/slim:id+[type+collectionType]
Complex Type Topic	Complex+Type.MARCXML#collectionType
Simple Type Topic	Simple+Type.MARCXML#tagDataType