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
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
|
<refentry id="olink.element">
<?dbhtml filename="olink.html"?>
<refentryinfo>
<pubdate>$Date$</pubdate>
<releaseinfo>$Revision$</releaseinfo>
</refentryinfo>
<refmeta>
<indexterm><primary>elements</primary>
<secondary>olink</secondary></indexterm>
<refentrytitle>olink</refentrytitle>
<refmiscinfo>Element</refmiscinfo>
</refmeta>
<refnamediv>
<refname>olink</refname>
<refpurpose>&olink.purpose;</refpurpose>
</refnamediv>
&olink.synopsis.gen;
<refsect1 condition='ref.description'><title>Description</title>
<para>
Unlike <sgmltag>Link</sgmltag> and <sgmltag>ULink</sgmltag>, the semantics of
<sgmltag>OLink</sgmltag> are application-specific. <sgmltag>OLink</sgmltag> provides
a mechanism for establishing links across documents, where
ID/IDREF linking is not possible and <sgmltag>ULink</sgmltag> is inappropriate.
</para>
<para>
In general terms, the strategy employed by <sgmltag>OLink</sgmltag> is to
point to the target document via an
<link linkend="s-egenent">external general entity</link>, and point
into that document in some application-specific way.
</para>
<refsect2><title>Processing expectations</title>
<para>
&format.inline;
</para>
<para>
<sgmltag>OLink</sgmltag> points to its target primarily with the
<sgmltag class='attribute'>TargetDocEnt</sgmltag> attribute.
<sgmltag class='attribute'>TargetDocEnt</sgmltag> must be the name of an
entity (previously declared in the &DTD; or in the <glossterm>document
subset</glossterm>).
</para>
<para>
Because <sgmltag class='attribute'>TargetDocEnt</sgmltag> is an entity attribute,
the entity used as its value must be declared with a notation.
Because the target is usually another &SGML; or &XML; document, the
notation <literal>SGML</literal> is most often used:
<screen>
<![CDATA[
<!ENTITY myotherdoc SYSTEM "myotherdoc.sgm" NDATA SGML>
]]>
</screen>
</para>
<para>
The semantics of the link are controlled by three other attributes:
<sgmltag class='attribute'>LinkMode</sgmltag>,
<sgmltag class='attribute'>LocalInfo</sgmltag>, and
<sgmltag class='attribute'>Type</sgmltag>.
The <sgmltag class='attribute'>LinkMode</sgmltag>
attribute points to a <sgmltag>ModeSpec</sgmltag>. The content of
<sgmltag>ModeSpec</sgmltag> describes the semantic of the link in an entirely
application-specific way.
</para>
<para>
The values of
<sgmltag class='attribute'>LocalInfo</sgmltag> and
<sgmltag class='attribute'>Type</sgmltag> may also influence the application.
For example, if the <sgmltag>ModeSpec</sgmltag> describes some sort of query,
<sgmltag class='attribute'>LocalInfo</sgmltag> might hold the query text
(allowing multiple <sgmltag>OLink</sgmltag>s to use the same <sgmltag>ModeSpec</sgmltag>
to achieve different queries with the same query engine).
</para>
<para>
Linking elements must not be nested within other linking
elements (including themselves). Because DocBook is harmonizing
towards &XML;, this restriction cannot easily be enforced by the &DTD;. The
processing of nested linking elements is undefined.
</para>
</refsect2>
<refsect2 role='fu' revision="4.0"><title>&FutureChanges;</title>
<para>
<!--do not index this occurance-->
&fu.interfacedefinition;
</para>
</refsect2>
&olink.parents.gen;
&olink.children.gen;
</refsect1>
<refsect1 condition='ref.elem.attrdesc'><title>Attributes</title>
<variablelist>
<varlistentry><term>linkmode</term>
<listitem>
<para>
<sgmltag class="attribute">LinkMode</sgmltag> points to the <sgmltag>ModeSpec</sgmltag>
which provides additional application-specific information for resolving this
<sgmltag>OLink</sgmltag>.
</para>
</listitem>
</varlistentry>
<varlistentry><term>localinfo</term>
<listitem>
<para>
<sgmltag class="attribute">LocalInfo</sgmltag> hold additional information
that may be used with the <sgmltag>ModeSpec</sgmltag>
(pointed to by <sgmltag class="attribute">LinkMode</sgmltag>) by the application
when resolving this <sgmltag>OLink</sgmltag>.
</para>
</listitem>
</varlistentry>
<varlistentry><term>targetdocent</term>
<listitem>
<para>
<sgmltag class="attribute">TargetDocEnt</sgmltag> specifies the name of an entity
that is to be used as part of the <sgmltag>OLink</sgmltag>. Exactly how the
link is resolved is application dependent and may be influenced by the
<sgmltag class="attribute">MoreInfo</sgmltag> and
<sgmltag class="attribute">LocalInfo</sgmltag> attributes.
</para>
</listitem>
</varlistentry>
<varlistentry><term>type</term>
<listitem>
<para>
<sgmltag class="attribute">Type</sgmltag> is available for application-specific
customization of the linking behavior.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 condition='ref.elem.seealso'><title>See Also</title>
&olink.seealso.gen;
</refsect1>
<refsect1><title>Examples</title>
<para>
In this example, we see how an <sgmltag>OLink</sgmltag> might be used for
searching. Here the <sgmltag>ModeSpec</sgmltag> describes the search query
(in a fictitious and entirely concocted syntax): <quote>look in the titles
of sections and return links using the title as the text of the link</quote>.
When the user selects the link, the application is expected to perform
the query and then might display the list of titles as a pop-up window
in the user interface.
</para>
<informalexample role="example-source">
<programlisting>&olink.example.1.txt;</programlisting>
</informalexample>
&olink.example.seealso.gen;
</refsect1>
</refentry>
|
