olink
Prev | DocBook Element Reference | Next

This is an alpha version of this book.

# olink

## Name

olink — A link that addresses its target indirectly, through an entity

##

# Synopsis

### Mixed Content Model

    olink ::=
    (#PCDATA|footnoteref|xref|abbrev|acronym|citation|citerefentry|
     citetitle|emphasis|firstterm|foreignphrase|glossterm|footnote|
     phrase|quote|trademark|wordasword|link|olink|ulink|action|
     application|classname|methodname|interfacename|exceptionname|
     ooclass|oointerface|ooexception|command|computeroutput|database|
     email|envar|errorcode|errorname|errortype|filename|function|
     guibutton|guiicon|guilabel|guimenu|guimenuitem|guisubmenu|
     hardware|interface|keycap|keycode|keycombo|keysym|literal|
     constant|markup|medialabel|menuchoice|mousebutton|option|
     optional|parameter|prompt|property|replaceable|returnvalue|
     sgmltag|structfield|structname|symbol|systemitem|token|type|
     userinput|varname|nonterminal|anchor|author|authorinitials|
     corpauthor|modespec|othercredit|productname|productnumber|
     revhistory|remark|subscript|superscript|inlinegraphic|
     inlinemediaobject|inlineequation|synopsis|cmdsynopsis|
     funcsynopsis|classsynopsis|fieldsynopsis|constructorsynopsis|
     destructorsynopsis|methodsynopsis|indexterm|beginpage)*

### Attributes

Common attributes

Name | Type | Default
type | CDATA | None
linkmode | IDREF | None
targetdocent | ENTITY | None
localinfo | CDATA | None

### Parameter Entities

The following parameter entities contain olink:

Parameter Entities
`%cptr.char.mix;` | `%docinfo.char.mix;` | `%indexdivcomponent.mix;`
`%link.char.class;` | `%ndxterm.char.mix;` | `%para.char.mix;`
`%refinline.char.mix;` | `%tbl.entry.mdl;` | `%title.char.mix;`
`%word.char.mix;` |  |

## Description

Unlike `Link` and `ULink`, the semantics of `OLink` are application-specific. `OLink` provides a mechanism for establishing links across documents, where ID/IDREF linking is not possible and `ULink` is inappropriate.

In general terms, the strategy employed by `OLink` is to point to the target document via an external general entity, and point into that document in some application-specific way.

### Processing expectations

Formatted inline.

`OLink` points to its target primarily with the `TargetDocEnt` attribute. `TargetDocEnt` must be the name of an entity (previously declared in the DTD or in the document subset).

Because `TargetDocEnt` 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 `SGML` is most often used:

    <!ENTITY myotherdoc SYSTEM "myotherdoc.sgm" NDATA SGML>

The semantics of the link are controlled by three other attributes: `LinkMode`, `LocalInfo`, and `Type`. The `LinkMode` attribute points to a `ModeSpec`. The content of `ModeSpec` describes the semantic of the link in an entirely application-specific way.

The values of `LocalInfo` and `Type` may also influence the application. For example, if the `ModeSpec` describes some sort of query, `LocalInfo` might hold the query text (allowing multiple `OLink`s to use the same `ModeSpec` to achieve different queries with the same query engine).

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.

### Future Changes

The `InterfaceDefinition` element will be discarded in DocBook V4.0. It will no longer be available in the content model of this element.

### Parents

These elements contain olink: `abbrev`, `ackno`, `acronym`, `application`, `artpagenums`, `attribution`, `authorinitials`, `bibliomisc`, `bridgehead`, `citation`, `citetitle`, `city`, `classsynopsisinfo`, `collabname`, `command`, `computeroutput`, `confdates`, `confnum`, `confsponsor`, `conftitle`, `contractnum`, `contractsponsor`, `contrib`, `corpauthor`, `corpname`, `country`, `date`, `edition`, `email`, `emphasis`, `entry`, `fax`, `figure`, `firstname`, `firstterm`, `foreignphrase`, `funcparams`, `funcsynopsisinfo`, `function`, `glosssee`, `glossseealso`, `glossterm`, `holder`, `honorific`, `indexdiv`, `informalfigure`, `invpartnumber`, `isbn`, `issn`, `issuenum`, `jobtitle`, `label`, `lineage`, `lineannotation`, `link`, `literal`, `literallayout`, `lotentry`, `manvolnum`, `member`, `modespec`, `msgaud`, `olink`, `optional`, `orgdiv`, `orgname`, `otheraddr`, `othername`, `pagenums`, `para`, `phone`, `phrase`, `pob`, `postcode`, `primary`, `primaryie`, `productname`, `productnumber`, `programlisting`, `pubdate`, `publishername`, `pubsnumber`, `quote`, `refentry`, `refentrytitle`, `refmiscinfo`, `refnamediv`, `refpurpose`, `releaseinfo`, `remark`, `replaceable`, `revnumber`, `revremark`, `screen`, `screeninfo`, `secondary`, `secondaryie`, `see`, `seealso`, `seealsoie`, `seeie`, `seg`, `segtitle`, `seriesvolnums`, `shortaffil`, `simpara`, `state`, `street`, `subscript`, `subtitle`, `superscript`, `surname`, `synopsis`, `term`, `tertiary`, `tertiaryie`, `title`, `titleabbrev`, `tocback`, `tocentry`, `tocfront`, `trademark`, `ulink`, `userinput`, `volumenum`, `wordasword`, `year`.

### Children

The following elements occur in olink: `abbrev`, `acronym`, `action`, `anchor`, `application`, `author`, `authorinitials`, `beginpage`, `citation`, `citerefentry`, `citetitle`, `classname`, `classsynopsis`, `cmdsynopsis`, `command`, `computeroutput`, `constant`, `constructorsynopsis`, `corpauthor`, `database`, `destructorsynopsis`, `email`, `emphasis`, `envar`, `errorcode`, `errorname`, `errortype`, `exceptionname`, `fieldsynopsis`, `filename`, `firstterm`, `footnote`, `footnoteref`, `foreignphrase`, `funcsynopsis`, `function`, `glossterm`, `guibutton`, `guiicon`, `guilabel`, `guimenu`, `guimenuitem`, `guisubmenu`, `hardware`, `indexterm`, `inlineequation`, `inlinegraphic`, `inlinemediaobject`, `interface`, `interfacename`, `keycap`, `keycode`, `keycombo`, `keysym`, `link`, `literal`, `markup`, `medialabel`, `menuchoice`, `methodname`, `methodsynopsis`, `modespec`, `mousebutton`, `nonterminal`, `olink`, `ooclass`, `ooexception`, `oointerface`, `option`, `optional`, `othercredit`, `parameter`, `phrase`, `productname`, `productnumber`, `prompt`, `property`, `quote`, `remark`, `replaceable`, `returnvalue`, `revhistory`, `sgmltag`, `structfield`, `structname`, `subscript`, `superscript`, `symbol`, `synopsis`, `systemitem`, `token`, `trademark`, `type`, `ulink`, `userinput`, `varname`, `wordasword`, `xref`.

## Attributes

linkmode

  `LinkMode` points to the `ModeSpec` which provides additional application-specific information for resolving this `OLink`.

localinfo

  `LocalInfo` hold additional information that may be used with the `ModeSpec` (pointed to by `LinkMode`) by the application when resolving this `OLink`.

targetdocent

  `TargetDocEnt` specifies the name of an entity that is to be used as part of the `OLink`. Exactly how the link is resolved is application dependent and may be influenced by the `MoreInfo` and `LocalInfo` attributes.

type

  `Type` is available for application-specific customization of the linking behavior.

## See Also

`anchor`, `link`, `ulink`, `xref`.

## Examples

In this example, we see how an `OLink` might be used for searching. Here the `ModeSpec` describes the search query (in a fictitious and entirely concocted syntax): “look in the titles of sections and return links using the title as the text of the link”. 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.

    <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
                      "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
    <!ENTITY refbook SYSTEM "refbook.sgm" CDATA SGML>
    ]>
    <chapter>
    <chapterinfo>
      <modespec id="s1query">query in sect*, title return link text title</modespec>
    </chapterinfo>
    <title>Printing</title>

    <para>
    Blah, blah, blah.
    </para>

    <sect1><title>See Also</title>
    <para>
    For more information <olink targetdocent="refbook" linkmode="s1query"
    localinfo="print or printing">about printing</olink>, consult
    the <ulink url="refbook.sgm">reference manual</ulink>.
    </para>
    </sect1>

    </chapter>

Prev | Home | Next
objectinfo | Up | ooclass

Copyright © 1999, 2000, 2001 O'Reilly & Associates, Inc.