| DocBook: The Definitive Guide 2.0.17 (Alpha)

# refdescriptor

$Revision: 1666 $

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

refdescriptor — A description of the topic of a reference page

## Synopsis

### Mixed Content Model

    refdescriptor ::=
    (#PCDATA|action|application|classname|methodname|interfacename|
     exceptionname|ooclass|oointerface|ooexception|package|command|
     computeroutput|database|email|envar|errorcode|errorname|
     errortype|errortext|filename|function|guibutton|guiicon|guilabel|
     guimenu|guimenuitem|guisubmenu|hardware|interface|keycap|keycode|
     keycombo|keysym|literal|code|constant|markup|medialabel|
     menuchoice|mousebutton|option|optional|parameter|prompt|property|
     replaceable|returnvalue|sgmltag|structfield|structname|symbol|
     systemitem|uri|token|type|userinput|varname|nonterminal)*

### Attributes

Common attributes

## Description

Reference pages (`RefEntry`s) are usually identified by a short, succinct topic name, such as the name of a function or command. The `RefName` (or one of the `RefName`s, in the case of a reference page that has several) is generally used as the topic name. When none of the `RefName`s is appropriate, `RefDescriptor` is used to specify the topic name.

`RefDescriptor` is unnecessary when an appropriate `RefName` can be selected automatically. At least one `RefName` is required, so `RefDescriptor` cannot be used in place of a name, only in addition to it.

### Processing expectations

May be formatted inline or as a displayed block, depending on context.

Formatting reference pages may require a fairly sophisticated processing system. Much of the meta-information about a reference page (its name, type, purpose, title, and classification) is stored in wrappers near the beginning of the `RefEntry`.

Common presentational features, such as titles and running heads, may require data from several of these wrappers plus some generated text. Other formatting often requires that these elements be reordered.

If a `RefDescriptor` is present, it should be used for the short topic name. This name usually appears in the running header along with the `ManVolNum` in print media. It may also appear in tables of contents and the index.

### 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 refdescriptor: `refnamediv`.

### Children

The following elements occur in refdescriptor: `action`, `application`, `classname`, `code`, `command`, `computeroutput`, `constant`, `database`, `email`, `envar`, `errorcode`, `errorname`, `errortext`, `errortype`, `exceptionname`, `filename`, `function`, `guibutton`, `guiicon`, `guilabel`, `guimenu`, `guimenuitem`, `guisubmenu`, `hardware`, `interface`, `interfacename`, `keycap`, `keycode`, `keycombo`, `keysym`, `literal`, `markup`, `medialabel`, `menuchoice`, `methodname`, `mousebutton`, `nonterminal`, `ooclass`, `ooexception`, `oointerface`, `option`, `optional`, `package`, `parameter`, `prompt`, `property`, `replaceable`, `returnvalue`, `sgmltag`, `structfield`, `structname`, `symbol`, `systemitem`, `token`, `type`, `uri`, `userinput`, `varname`.

## See Also

`refentrytitle`, `refname`.

## Examples

For examples, see `reference`.

refclass |  | refentry

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