optional

$Revision: 1666 $

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

optional — Optional information

Synopsis

Mixed Content Model

optional ::=
(#PCDATA|link|olink|ulink|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|anchor|remark|subscript|
 superscript|inlinegraphic|inlinemediaobject|indexterm|beginpage)*

Attributes

Common attributes

Description

The Optional element indicates that a specified argument, option, or other text is optional. The precise meaning of “optional” varies according to the application or process begin documented.

Processing expectations

Formatted inline.

Optional arguments in a Synopsis are usually given special typographic treatment, often they are surrounded by square brackets. The Optional tag is expected to generate the brackets.

Outside a Synopsis, the typographic treatment of Optional is application-specific.

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.

See Also

computeroutput, constant, literal, markup, option, parameter, prompt, replaceable, sgmltag, userinput, varname.

Examples

The UNIX ls command could be documented as follows:

<!DOCTYPE synopsis PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<synopsis>
ls <optional><option>-abcCdfFgilLmnopqrRstux1</option></optional>
   <optional>names</optional>
</synopsis>
ls [-abcCdfFgilLmnopqrRstux1]
   [names]

which might generate the following output:

ls [ -abcCdfFgilLmnopqrRstux1 ] 
   [names]