    | DocBook: The Definitive Guide 2.0.17 (Alpha) |
| | DocBook: The Definitive Guide 2.0.17 (Alpha) |
$Revision: 1666 $
$Date: 2002-06-12 07:19:37 -0400 (Wed, 12 Jun 2002) $
refdescriptor — A description of the topic of a reference page
Reference pages (RefEntrys) are usually identified
by a short, succinct topic name, such as the name of a function
or command. The RefName (or one of the
RefNames, in the case of a reference page that has
several) is generally used as the topic name. When none of the
RefNames 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.
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.
The InterfaceDefinition
element will be discarded in DocBook V4.0. It will no longer be available
in the content model of this element.
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.
| | | |
| refclass | | refentry |