1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
|
<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>
|
