xref

xref — A cross reference to another part of the document

Synopsis

Content Model

xref ::=
EMPTY

Attributes

Common attributes

Name	Type	Default
xrefstyle	CDATA	None
endterm	IDREF	None
linkend	IDREF	Required

Description

The XRef element forms a cross-reference from the location of the XRef to the element to which it points. Unlike Link and the other cross-referencing elements, XRef is empty. The processing system has to generate appropriate cross-reference text for the reader.

Processing expectations

Under ordinary circumstances, the xref points to the some element with its linkend attribute and the processing system generates appropriate cross reference text. There are three ways for the author to influence the generated text:

1. If the endterm attribute is specified on xref, the content of the element pointed to by endterm will be used as the text of the cross-reference.

2. Otherwise, if the object pointed to has a specified XRefLabel, the content of that attribute will be used as the cross-reference text.

3. Finally, the author may specify a keyword (or other information) in the xrefstyle attribute. Unlike endterm and xreflabel which have rigid semantics, the content of the xrefstyle attribute is simply additional information for the processing system. What effect it has, if any, is dependent on the processing system.

Parents

These elements contain xref: application, attribution, bibliomisc, bridgehead, citation, citetitle, emphasis, entry, firstterm, foreignphrase, glosssee, glossseealso, glossterm, lineannotation, link, literallayout, lotentry, member, msgaud, olink, para, phrase, primary, primaryie, productname, programlisting, quote, refentrytitle, refpurpose, remark, screen, screeninfo, secondary, secondaryie, see, seealso, seealsoie, seeie, seg, segtitle, simpara, subtitle, synopsis, td, term, termdef, tertiary, tertiaryie, th, title, titleabbrev, tocback, tocentry, tocfront, ulink.

Attributes

endterm

Endterm points to the element whose content is to be used as the text of the link.

linkend

Linkend points to the target of the cross reference.

See Also

anchor, link, olink, ulink.

Examples

Consider the following example:

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book><title>An Example Book</title>
<chapter id="ch01"><title>XRef Samples</title>
<para>
This paragraph demonstrates several features of
<sgmltag>XRef</sgmltag>.
</para>
<itemizedlist>
<listitem><para>A straight link generates the
cross-reference text: <xref linkend="ch02"/>.
</para></listitem>
<listitem><para>A link to an element with an
<sgmltag class="attribute">XRefLabel</sgmltag>:
<xref linkend="ch03"/>.
</para></listitem>
<listitem><para>A link with an
<sgmltag class="attribute">EndTerm</sgmltag>:
<xref linkend="ch04" endterm="ch04short"/>.
</para></listitem>
</itemizedlist>
</chapter>

<chapter id="ch02">
  <title>The Second Chapter</title>
  <para>Some content here</para>
</chapter>

<chapter id="ch03" xreflabel="Chapter the Third">
  <title>The Third Chapter</title>
  <para>Some content here</para>
</chapter>

<chapter id="ch04">
  <title>The Fourth Chapter</title>
  <titleabbrev id="ch04short">Chapter 4</titleabbrev>
  <para>Some content here</para>
</chapter>
</book>

One reasonable rendering for the content of the first chapter of this book is the following:

This paragraph demonstrates several features of XRef.

• A straight link generates the cross-reference text: Chapter 2, “The Second Chapter”

• A link to an element with an XRefLabel: Chapter the Third.

• A link with an EndTerm: Chapter 4.

Of course, in an online system, these references would also be links to the appropriate chapters.

For additional examples, see also part.