DocBook: The Definitive Guide
By Norman Walsh & Leonard Muellner1st Edition October 1999
1-56592-580-7, Order Number: 5807
652 pages, $36.95 , Includes CD-ROM
|
|
|
|
|
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 |
SynopFragmentRef
Synopsis
Declared Content
SynopFragmentRef ::= RCDATAAttributes
Name
Type
Default
Linkend IDREF Required Tag Minimization
Both the start- and end-tags are required for this element.
Description
A complex CmdSynopsis can be made more manageable with SynopFragments. Rather than attempting to present the entire synopsis in one large piece, parts of the synopsis can be extracted out and presented elsewhere.
At the point where each piece was extracted, insert a SynopFragmentRef that points to the fragment. The content of the SynopFragmentRef will be presented inline.
The extracted pieces are placed in SynopFragments at the end of the CmdSynopsis.
The content model of SynopFragmentRef is unique in the SGML version of DocBook because it contains RCDATA declared content. What this means is that all markup inside a SynopFragmentRef is ignored, except for entity references.
How, you might ask, is this different from a content model that includes only #PCDATA? The difference is only apparent when you consider inclusions. Recall that an inclusion provides a list of elements that can occur anywhere inside an element. So, for example, the fact that Chapter lists IndexTerm as an inclusion means that IndexTerm can legally occur inside of a SynopFragmentRef that's nested inside a chapter, even if the content model of SynopFragmentRef does not explicitly allow IndexTerms. Making the content RCDATA ensures that the markup will not be recognized, even if it's allowed by inclusion. A neat trick.
XML does not support RCDATA.
Processing expectations
Formatted as a displayed block.
The presentation system is responsible for generating text that makes the reader aware of the link. This can be done with numbered bullets, or any other appropriate mechanism.
Online systems have additional flexibility. They may generate hot links between the references and the fragments, for example, or place the fragments in pop-up windows.
Back to: DocBook: The Definitive Guide
© 2001, O'Reilly & Associates, Inc.
