<refentry id="xref.element">
<?dbhtml filename="xref.html"?>
<refentryinfo>
<pubdate>$Date$</pubdate>
<releaseinfo>$Revision$</releaseinfo>
</refentryinfo>

<refmeta>
<indexterm><primary>elements</primary>
<secondary>xref</secondary></indexterm>
<refentrytitle>xref</refentrytitle>
<refmiscinfo>Element</refmiscinfo>
</refmeta>
<refnamediv>
<refname>xref</refname>
<refpurpose>&xref.purpose;</refpurpose>
</refnamediv>

&xref.synopsis.gen;
<refsect1 condition='ref.description'><title>Description</title>

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

<refsect2 id="dbreproc.xref"><title>Processing expectations</title>

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

<orderedlist>
<listitem>
<para>If the <sgmltag class='attribute'>endterm</sgmltag> attribute is specified
on <sgmltag>xref</sgmltag>, the
content of the element pointed to by <sgmltag class='attribute'>endterm</sgmltag>
will be used as the text of the cross-reference.
</para>
</listitem>

<listitem>
<para>Otherwise, if the object <emphasis>pointed to</emphasis> has a
specified <sgmltag class='attribute'>XRefLabel</sgmltag>, the content of
that attribute will be used as the cross-reference text.
</para>
</listitem>

<listitem>
<para>Finally, the author may specify a keyword (or other information) in the
<sgmltag class="attribute">xrefstyle</sgmltag> attribute. Unlike
<sgmltag class="attribute">endterm</sgmltag> and
<sgmltag class="attribute">xreflabel</sgmltag> which have rigid semantics,
the content of the <sgmltag class="attribute">xrefstyle</sgmltag> attribute is simply
additional information for the processing system. What effect it has, if any,
is dependent on the processing system.</para>
</listitem>
</orderedlist>

</refsect2>

&xref.parents.gen;

</refsect1>
<refsect1 condition='ref.elem.attrdesc'><title>Attributes</title>
<variablelist>
<varlistentry><term>endterm</term>
<listitem>
<para>
<sgmltag class="attribute">Endterm</sgmltag> points to the element whose content
is to be used as the text of the link.
</para>
</listitem>
</varlistentry>
<varlistentry><term>linkend</term>
<listitem>
<para>
<sgmltag class="attribute">Linkend</sgmltag> points to the target of the cross reference.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 condition='ref.elem.seealso'><title>See Also</title>
&xref.seealso.gen;
</refsect1>
<refsect1><title>Examples</title>

<para>
Consider the following example:
</para>

<informalexample role="example-source">
<programlisting>&xref.example.1.txt;</programlisting>
</informalexample>

<para>
One reasonable rendering for the content of the first chapter of
this book is the following:
</para>

<para>
This paragraph demonstrates several features of
<sgmltag>XRef</sgmltag>.
</para>

<itemizedlist>
<listitem><para>A straight link generates the
cross-reference text: Chapter 2, <quote>The Second Chapter</quote>
</para></listitem>
<listitem><para>A link to an element with an
<sgmltag class="attribute">XRefLabel</sgmltag>:
Chapter the Third.
</para></listitem>
<listitem><para>A link with an
<sgmltag class="attribute">EndTerm</sgmltag>:
Chapter 4.
</para></listitem>
</itemizedlist>

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

&xref.example.seealso.gen;
</refsect1>
</refentry>

