`<glossref>`

Glossary reference topic references are a convenience element for creating references to glossary topics. It has a required @keys attribute, which forces the author to create a key by which inline terms can reflect the glossary terms and become navigable links to the glossary definition. For example, when <glossentry> topics are used to define acronyms, this reminds authors to create a key that <abbreviated-form> elements can use to refer to the short and expanded versions of the acronyms.

Usage information

Note that the key names defined in the @keys attribute do not need to match the target term or acronym. Using more qualified values or distinct key scopes for the keys will reduce conflicts in situations where the same key name might be associated with different terms. For example, an information set could use cars.abs as the key for the term Anti-lock Braking System, and ship.abs to refer to the term American Bureau of Shipping.

Specialization hierarchy

The <glossref> element is specialized from <topicref>. It is defined in the glossary reference domain module.

Attributes

The following attributes are available on this element: link-relationship attributes, universal attributes, @chunk, @collection-type, @keyref, @linking, @processing-role, @search, and @toc.

For this element:

The @href attribute is a reference to a glossary definition, typically a <glossentry> topic.
The @keys attribute is required.
The @linking attribute has a default value of none.
The @toc attribute has a default value of no.
The @search attribute has a default value of no.

The following attributes are available on this element: universal attributes and the attributes defined below.

@chunk (common map attributes)

Specifies how a processor should render a map or branch of a map. For example, it can be used to specify that individual topic documents should be rendered as a single document, or that a single document with multiple topics should be rendered as multiple documents.

The following values are valid:

combine: Instructs a processor to combine the referenced source documents for rendering purposes. This is intended for cases where a publishing process normally results in a single output artifact for each source XML document.
split: Instructs a processor to split each topic from the referenced source document into its own document for rendering purposes. This is intended for cases where a publishing process normally results in a single output artifact for each source XML document, regardless of how many DITA topics exist within each source document.

Processors can also define custom, implementation-specific tokens for this attribute.

For a detailed description of the @chunk attribute and its usage, see Chunking.

@collection-type (common map attributes)

Specifies how topics or links relate to each other. The processing default is unordered, although no default is specified in the OASIS-provided grammar files. The following values are valid:

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: Indicates a tight grouping in which each of the referenced topics not only relates to the current topic but also relate to each other.

@format (link-relationship attributes)

Specifies the format of the resource that is referenced. See STUB CONTENT for detailed information on supported values and processing implications.

@href (link-relationship attributes)

Specifies a reference to a resource. See STUB CONTENT for detailed information on supported values and processing implications.

The @href attribute is a reference to a glossary definition, typically a <glossentry> topic.

@keyref

Specifies a key name that acts as a redirectable reference based on a key definition within a map. See STUB CONTENT for information on using this attribute.

For HDITA, the equivalent of @keyref is @data-keyref

@keys

The @keys attribute is required.

@linking (common map attributes)

Specifies linking characteristics of a topic specific to the location of this reference in a map. If the value is not specified locally, the value might cascade from another element in the map (for cascade rules, see Cascading of metadata attributes in a DITA map). The following values are valid:

targetonly: A topic can only be linked to and cannot link to other topics.
sourceonly: A topic cannot be linked to but can link to other topics.
normal: A topic can be linked to and can link to other topics. Use this to override the linking value of a parent topic.
none: A topic cannot be linked to or link to other topics.
-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

The @linking attribute has a default value of none.

@processing-role (common map attributes)

Specifies whether the referenced resource is processed normally or treated as a resource that is only included in order to resolve references, such as key or content references. The following values are valid:

normal: Indicates that the resource is a readable part of the information set. It is included in navigation and search results. This is the default value for the <topicref> element.
resource-only: Indicates that the resource should be used only for processing purposes. It is not included in navigation or search results, nor is it rendered as a topic. This is the default value for the <keydef> element.

-dita-use-conref-target: See Using the -dita-use-conref-target value for more information.

If no value is specified but the attribute is specified on a containing element within a map or within the related-links section, the value cascades from the closest containing element.

@scope (link-relationship attributes)

Specifies the closeness of the relationship between the current document and the referenced resource. The following values are valid: local, peer, external, and -dita-use-conref-target.

See STUB CONTENT for detailed information on supported values and processing implications.

@search (common map attributes)

Specifies whether the target is available for searching. If the value is not specified locally, the value might cascade from another element in the map (for cascade rules, see Cascading of metadata attributes in a DITA map). The following values are valid: yes, no, and -dita-use-conref-target.

The @search attribute has a default value of no.

@toc (common map attributes)

Specifies whether a topic appears in the table of contents (TOC) based on the current map context. If the value is not specified locally, the value might cascade from another element in the map (for cascade rules, see Cascading of metadata attributes in a DITA map). The following values are valid:

yes: The topic appears in a generated TOC.
no: The topic does not appear in a generated TOC.
-dita-use-conref-target: See STUB CONTENT for more information.

The @toc attribute has a default value of no.

@type (link-relationship attributes)

Describes the target of a reference. See STUB CONTENT for detailed information on supported values and processing implications.

Example

This section is non-normative.

The following code sample demonstrates using a <glossref> element to include a car-specific glossary entry in the map. The glossary reference has the key "abs". The <glossref> element is within the key scope "cars", so references to this glossary entry from outside the "cars" key scope will be of the form <keyword keyref="cars.abs"/>.

<map>
  <!-- ... -->
  <topicref href="car-maintenance.dita"/>
  <!-- ... -->
  <topichead keyscope="cars">
   <topicmeta><navtitle>Car Terminalogy</navtitle></topicmeta>
   <glossref keys="abs" href="glossary/a/antiLockBrake.dita"/>
   <!-- ... key declarations for other referenced acronyms ... -->
  </topichead>
</map>

When this is map is rendered using typical output processing, the table of contents will have an entry for the topic head "Car Terminology" but will not have entries for the glossary entries because <glossref> sets the value of @toc to no by default.