| DocBook: The Definitive Guide 2.0.17 (Alpha)

# xref

$Revision$

$Date$

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`.

wordasword |  | year

Copyright © 1999, 2000, 2001, 2002, 2003 O'Reilly & Associates, Inc. All rights reserved.