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

