DocBook: The Definitive GuideBy Norman Walsh & Leonard Muellner1st Edition October 1999 1-56592-580-7, Order Number: 5807 652 pages, $36.95 , Includes CD-ROM |
OLink
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|Command|ComputerOutput|Database|Email| EnVar|ErrorCode|ErrorName|ErrorType|Filename|Function|GUIButton| GUIIcon|GUILabel|GUIMenu|GUIMenuItem|GUISubmenu|Hardware| Interface|InterfaceDefinition|KeyCap|KeyCode|KeyCombo|KeySym| Literal|Constant|Markup|MediaLabel|MenuChoice|MouseButton| MsgText|Option|Optional|Parameter|Prompt|Property|Replaceable| ReturnValue|SGMLTag|StructField|StructName|Symbol|SystemItem| Token|Type|UserInput|VarName|Anchor|Author|AuthorInitials| CorpAuthor|ModeSpec|OtherCredit|ProductName|ProductNumber| RevHistory|Comment|Subscript|Superscript|InlineGraphic| InlineMediaObject|InlineEquation|Synopsis|CmdSynopsis| FuncSynopsis|IndexTerm)+)Attributes
Name
Type
Default
Type CDATA None LinkMode IDREF None TargetDocEnt ENTITY None LocalInfo CDATA None Tag Minimization
Both the start- and end-tags are required for this element.
Parameter Entities
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 OLinks 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, Action, Application, ArtPageNums, Attribution, AuthorInitials, BiblioMisc, BridgeHead, Citation, CiteTitle, City, CollabName, Command, Comment, ComputerOutput, ConfDates, ConfNum, ConfSponsor, ConfTitle, ContractNum, ContractSponsor, Contrib, CorpAuthor, CorpName, Country, Database, Date, Edition, Email, Emphasis, entry, Fax, Figure, Filename, FirstName, FirstTerm, ForeignPhrase, FuncParams, FuncSynopsisInfo, Function, GlossSee, GlossSeeAlso, GlossTerm, Hardware, Holder, Honorific, IndexDiv, InformalFigure, Interface, InterfaceDefinition, InvPartNumber, ISBN, ISSN, IssueNum, JobTitle, KeyCap, Label, Lineage, LineAnnotation, Link, Literal, LiteralLayout, LoTentry, ManVolNum, Member, ModeSpec, MsgAud, OLink, Option, Optional, OrgDiv, OrgName, OtherAddr, OtherName, PageNums, Para, Parameter, Phone, Phrase, POB, Postcode, Primary, PrimaryIE, ProductName, ProductNumber, ProgramListing, Property, PubDate, PublisherName, PubsNumber, Quote, RefEntry, RefEntryTitle, RefMiscInfo, RefNameDiv, RefPurpose, ReleaseInfo, Replaceable, RevNumber, RevRemark, Screen, ScreenInfo, Secondary, SecondaryIE, See, SeeAlso, SeeAlsoIE, SeeIE, Seg, SegTitle, SeriesVolNums, ShortAffil, SimPara, State, Street, Subscript, Subtitle, Superscript, Surname, Synopsis, SystemItem, 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, Citation, CiteRefEntry, CiteTitle, ClassName, CmdSynopsis, Command, Comment, ComputerOutput, Constant, CorpAuthor, Database, Email, Emphasis, EnVar, ErrorCode, ErrorName, ErrorType, Filename, FirstTerm, Footnote, FootnoteRef, ForeignPhrase, FuncSynopsis, Function, GlossTerm, GUIButton, GUIIcon, GUILabel, GUIMenu, GUIMenuItem, GUISubmenu, Hardware, IndexTerm, InlineEquation, InlineGraphic, InlineMediaObject, Interface, InterfaceDefinition, KeyCap, KeyCode, KeyCombo, KeySym, Link, Literal, Markup, MediaLabel, MenuChoice, ModeSpec, MouseButton, MsgText, OLink, Option, Optional, OtherCredit, Parameter, Phrase, ProductName, ProductNumber, Prompt, Property, Quote, Replaceable, ReturnValue, RevHistory, SGMLTag, StructField, StructName, Subscript, Superscript, Symbol, Synopsis, SystemItem, Token, Trademark, Type, ULink, UserInput, VarName, WordAsWord, XRef.
In some contexts, the following elements are allowed anywhere: BeginPage, IndexTerm.
In some contexts, the following elements are excluded: Acronym, Footnote, IndexTerm.
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.
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 V3.1//EN" [ <!ENTITY refbook SYSTEM "refbook.sgm" CDATA SGML> ]> <chapter> <docinfo> <modespec id=s1query>query in sect*, title return link text title</modespec> </docinfo> <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> </chapter>
Back to: DocBook: The Definitive Guide
© 2001, O'Reilly & Associates, Inc.