$Revision: 1666 $
$Date: 2002-06-12 07:19:37 -0400 (Wed, 12 Jun 2002) $
synopfragmentref — A reference to a fragment of a command synopsis
synopfragmentref ::= (#PCDATA)
Name | Type | Default |
linkend | IDREF | Required |
A complex CmdSynopsis
can be made more manageable
with SynopFragment
s. 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 SynopFragment
s
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 IndexTerm
s. 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
.
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.