Linking to a glossary entry

Linking to a glossary entry
	Chapter 16. Glossaries

You can form a link from your text to a glossary entry by adding an id attribute to a glossentry that contains a glossterm in a glossary (don't put the id on the glossterm). Then add a matching linkend attribute to an inline glossterm in your text. Note that the element glossterm is used in both places, but they serve different functions.

<para>Set your <glossterm linkend="NetAddr">network address</glossterm>.
</para>
...
<glossary>
  <glossentry id="NetAddr">
    <glossterm>Network address</glossterm>
    <glossdef><para>Four numbers separated by periods</para></glossdef>
  </glossentry>
</glossary>

In this method of linking, the inline text can differ from the text of the term in the glossary. That's useful if you need to change capitalization or a word ending.

The other type of glossary link can be formed automatically. To turn this feature on, set the stylesheet parameter glossterm.auto.link to 1. Then you can skip adding the id and linkend attributes. To form the link, the stylesheet tries to match the words of the inline glossterm with the words in any glossterm child of a glossentry, which must appear in a glossary. What about capitalization and word ending variations? In those cases, add a baseform attribute to the inline glossterm in your text, and set its value to match the words of the glossterm in the glossary. It will use the baseform to find the match to form the link but will display the text content of the inline glossterm as you have entered it. Here are two examples. The matching words are highlighted.

<para>Set your 
<glossterm baseform="Network address">network address</glossterm>.
</para>
<para><glossterm>Domain name</glossterm> 
is expressed as part of the address.</para>
...
<glossary>
  <glossentry>
    <glossterm>Domain name</glossterm>
    <glossdef><para>First part of a network address.</para></glossdef>
  </glossentry>
  <glossentry>
    <glossterm>Network address</glossterm>
    <glossdef><para>Domain name plus machine name.</para></glossdef>
  </glossentry>
</glossary>

Caution

If you edit the words on just one end of such automatic links, the link will be broken and the stylesheet will issue a warning message. This could easily happen if you edit a glossary entry, without realizing there are inline references to it elsewhere. The id and linkend method is more robust since it doesn't depend on matching text. You can also use both methods within a document, and the linkend method will take precedence in a given reference.

You can also form links in a glossary from one related glossary entry to another using glosssee and glossseealso elements. The glosssee element is used in place of a glossdef element when you want to refer the reader to another entry for the entire definition. The glossseealso element can be put into a glossdef element to supplement a definition with a reference to another.

To form active links, you put an id attribute on the destination glossentry (or its glossterm), and then point to that id with an otherterm attribute. Here are some examples:

<glossary>
  <glossentry id="DomainName">
    <glossterm>Domain name</glossterm>
    <glossdef><para>First part of a network address.</para>
        <glossseealso otherterm="NetAddr"/>
    </glossdef>
  </glossentry>
  <glossentry>
    <glossterm>Machine address</glossterm>
    <glosssee otherterm="NetAddr">network address</glosssee>
  </glossentry>
  <glossentry>
    <glossterm id="NetAddr">Network address</glossterm>
    <glossdef><para>Domain name plus machine name.</para> 
        <glossseealso otherterm="DomainName"/>
    </glossdef>
  </glossentry>
</glossary>

If the matchup between otherterm and id is made, then the stylesheet will generate a link and its text, using the words of the destination glossterm. If the matchup fails, then it falls back to using the content of the glosssee or glossseealso.

What about link and xref?

You might wonder why you can't use link or xref elements to link to a glossary entry. Actually, a link element can be used, but it will act exactly like an inline glossterm since you have to supply the text for the link.

Trying to use xref can be a problem, because the stylesheets don't know how to generate text for the link. Usually xref resolves to the title of the target element, but a glossentry doesn't have a title. The glossentry's glossterm is similar, but it can contain inline markup and graphics, so it is considered too complex to use for generated text. However, if you keep your entries simple, you can force the stylesheet to use the text of the glossentry's glossterm. Just add an id attribute to the glossterm and add a matching endterm attribute to the xref element. Here is an example:

<xref linkend="ge-xslfoprocessor" endterm="gt-xslfoprocessor"/>
...

<glossentry id="ge-xslfoprocessor">
<glossterm id="gt-xslfoprocessor">XSL-FO processor</glossterm>
<glossdef>
<para>Software component that converts an XSL-FO document into a
formatted document.</para>
</glossdef>
</glossentry>

The linkend attribute in the xref points to the glossentry element's id, but the endterm attribute points to the glossterm inside the entry. Using endterm causes the generated text to come from the children of the element whose id is referenced in the endterm, which is the glossterm in this case. This xref should generate a link whose hot text is XSL-FO processor.

You have another option if the glossterm is too long to use as the generated cross reference text. You could put some link text in an xreflabel attribute on the target glossentry element. Then the xref will copy that text to form the link. See the section “Attach an xreflabel to a target element” for more information.