| DocBook: The Definitive Guide 2.0.17 (Alpha)

# synopfragmentref

$Revision: 1666 $

$Date: 2002-06-12 07:19:37 -0400 (Wed, 12 Jun 2002) $

synopfragmentref — A reference to a fragment of a command synopsis

## Synopsis

### Mixed Content Model

    synopfragmentref ::=
    (#PCDATA)

### Attributes

Common attributes

Name | Type | Default
linkend | IDREF | Required

## Description

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

### Note

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

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

### Parents

These elements contain synopfragmentref: `arg`, `group`.

## Attributes

linkend

  `Linkend` points to the `SynopFragment` referenced.

## See Also

`arg`, `cmdsynopsis`, `group`, `refsynopsisdiv`, `sbr`, `synopfragment`.

## Examples

For examples, see `synopfragment`.

synopfragment |  | synopsis

Copyright © 1999, 2000, 2001, 2002, 2003 O'Reilly & Associates, Inc. All rights reserved.