3.1.1.4.3 linkpool

The <linkpool> element defines a group of links that have common characteristics, such as type or audience or source. When links are in <related-links> or <linkpool> elements, the organization of links on final output is determined by the output process, not by the order that the links actually occur in the DITA topic.

There are two ways to organize related information links within a topic. First, you can add them all in no particular order, either by using <linkpool> elements or by placing <link> elements directly within <related-links>, in which case the rendering is implementation dependent. For example, tools may choose to sort all links based on the role or type; tools may also move or remove links to fit the context (for example, moving a prerequisite link to the top of a browser window, or removing links to the next topic if it is rendered on the same page in a PDF). These behaviors are examples only and are not required.

Second, links may be grouped using one or more <linklist> elements. When you group them using <linklist>, then the order of the links within each <linklist> is preserved when rendered. You may also use a combination of the two approaches, which will allow some links to be automatically sorted while the others are left as-is.

Attributes set on the <linkpool> and <linklist> elements are inherited by their descendants. For example, if you have a <linklist> element that contains all external links, you can set scope="external" on that outer <linklist> element and leave it off the <link> elements within that <linklist>.

Contains

Doctype

Content model

topic, concept, ditabase, glossary, glossentry, glossgroup, reference, task, machineryTask, learningAssessment, learningContent, learningOverview, learningPlan, learningSummary

(linkpool or link) (any number)

Contained by

Doctype

Content model

topic (base), topic (technical content), concept, ditabase, glossary, glossentry, glossgroup, reference, task (strict), task (general), machineryTask, learningAssessment, learningContent, learningOverview, learningPlan, learningSummary

related-links, linkpool

Inheritance

- topic/linkpool

Example
<related-links>
  <linkpool type="concept">
    <link href="czez.dita#czez" role="next"></link>
    <link href="czunder.dita"></link>
    <link format="html" href="czover.htm#sqljsupp" role="parent">
      <linktext>Overview of the CZ</linktext>
    </link>
    <link format="html" href="czesqlj.htm#sqljemb">
      <linktext>Working with CZESQLJ</linktext>
      <desc>When you work with CZESQLJ, you need to know...</desc>
    </link>
  </linkpool>
<related-links>
Attributes

Name

Description

Data Type

Default Value

Required?

collection-type

Collection types describe how links relate to each other. The processing default is "unordered", although no default is specified in the DTD or Schema.

unordered

Indicates that the order of the child topics is not significant.

sequence

Indicates that the order of the child topics is significant; output processors will typically link between them in order.

choice

Indicates that one of the children should be selected.

family

Represents a tight grouping in which each of the referenced topics not only relates to the current topic but also relate to each other.

Usage of the collection-type attribute on <reltable> and <relcolspec> is currently undefined and reserved for future use.

(unordered | sequence | choice | family | -dita-use-​conref-​target)

#IMPLIED

No

duplicates

Specifies whether or not duplicate links will be filtered out of a linklist. Allowable values are: "yes" (allow duplicate links), or "no" (filter out duplicate links). In general, duplicate links in linklists are preserved.. Note that links are regarded as duplicates only if their content plus all attributes match.

#IMPLIED

The attribute value is currently ignored, but should default to yes for links in linklists and no for all other links.

No

mapkeyref

Identifies the map, if any, from which the contained links are derived. This value is automatically generated by the same process that creates the links from the map, as a way to identify which map the links came from. If the <linklist> or <linkpool> is manually created by the author, there is no need to use this attribute. Note that this attribute is not related to the keyref attribute, and is not used for key based processing.

CDATA

#IMPLIED

No

type

Describes the target of a reference. See 3.4.2.8 The type attribute for detailed information on supported values and processing implications.

CDATA

#IMPLIED

No

role

The role attribute defines the role the target topic plays in relationship with the current topic. For example, in a parent/child relationship, the role would be "parent" when the target is the parent of the current topic, and "child" when the target is the child of the current topic. This structure could be used to sort and classify links at display time. See 3.4.2.11 The role attribute for information on supported values. The role attribute values

sample and external are deprecated.

(parent | child | sibling | friend | next | previous | cousin | ancestor | descendant | sample | external | other | -dita-use-​conref-​target)

#IMPLIED

No

otherrole

Indicates an alternate role. This value is used when the role attribute is set to other.

CDATA

#IMPLIED

No

format

The format attribute identifies the format of the resource being referenced. See 3.4.2.9 The format attribute for details on supported values.

CDATA

#IMPLIED

No

scope

The scope attribute identifies the closeness of the relationship between the current document and the target resource. See 3.4.2.10 The scope attribute for more information on values.

(local | peer | external | -dita-use-​conref-​target)

#IMPLIED

No

univ-atts attribute group (includes select-atts, id-atts, and localization-atts groups)

A set of related attributes, described in 3.4.1.3 univ-atts attribute group

     

global-atts attribute group (xtrf, xtrc)

A set of related attributes, described in 3.4.1.2 global-atts attribute group

     

class, outputclass

Common attributes described in 3.4.1.9 Other common DITA attributes

     

Previous Topic:  3.1.1.4.2 linklist

Next Topic:  3.1.1.4.4 linktext

Parent Topic:  3.1.1.4 Related links elements

Sibling Topics:

3.1.1.4.1 link

3.1.1.4.2 linklist

3.1.1.4.4 linktext

3.1.1.4.5 linkinfo