Structure of the related-links section

The related-links section of a topic contains link elements which can optionally be grouped into linklist and linkpool container elements. The structure of those elements influences how the links are displayed in the output, and how metadata attributes for the links are managed.

One of the methods of defining links in DITA content is through a related-links section at the end of a topic, outside the topic body.

The related-links section has the following structure: 

<topic>
  <title>...</title>
  <body>
  ...
  </body>
  <related-links>
    <link href="URL of referenced topic or resource">
      <linktext>Display text for link</linktext>
    </link>
    <link>...</link>
    .
    .
    .
  </related-links>
</topic>

To better organise links, the link elements can be grouped into linklist and linkpool container elements. These container elements allow metadata attributes to be applied to a set of links as a whole.

For example, if you wanted to nominate that all links in a linklist have a product attribute of lite, you could use the following mark-up: 
<related-links>
  <linklist product="lite">
    <link>...</link>
    <link>...</link>
    .
    .
  </linklist>

The linklist container is used when the order of the links is important, as that order will be maintained when the content is processed to an output format. The linkpool container does not imply any particular order. (In this respect, linklist is like an ordered list, while linkpool is like an unordered list.)

When in a linklist container, links in the output will typically be displayed without a heading, and in the same order as the links are defined in the linklist. When in a linkpool container, or when not contained (as simple link elements within the related-links section), links in the output will be grouped according to their information type (such as under headings of Related Concepts, Related Tasks, Related References, and Related Information).

Within the link structure, the linktext element, which defines the display text for the link, is optional. When there is no linktext element, the title of the referenced DITA topic will be used as the display text for the link.

You should not include the linktext element when linking to DITA topics. This will force the title of the target to be used as the link text, and ensures that the link text matches the target topic title. However, for links to non-DITA resources such as Web sites or PDF documents, you should define the link text.

Note:
Some sample links are included in the related-links section of this topic. These links will only appear in hypertext versions of The DITA Style Guide. The code for the sample links is:
Type of link Code
Link to another DITA topic with no linktext element 
<link href="c_Scope_Attribute.dita">
</link>
Link to another DITA topic with a linktext element 
<link href="c_Scope_Attribute.dita>
  <linktext>Alternative link to Scope Attribute
  </linktext>
</link>
Link to an external Web site 
<link format="html" scope="external" 
href="http://www.hyperwrite.com/">
  <linktext>HyperWrite Web Site</linktext>
</link>
The three sample links are included in the related-links section twice: the first set of links is not contained in a container element, while the second set of links is contained within a linklist element.