optional

$Revision: 1666 $

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

optional — Optional information

Synopsis

Mixed Content Model

optional ::=
(%cptr.char.mix;)*

Attributes

Common attributes

Parameter Entities

The following parameter entities contain optional:

Parameter Entities
`%cptr.char.mix;`	`%ndxterm.char.mix;`	`%para.char.mix;`
`%refinline.char.mix;`	`%refname.char.mix;`	`%tbl.entry.mdl;`
`%tech.char.class;`	`%title.char.mix;`

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.

Parents

These elements contain optional: action, application, attribution, bibliomisc, bridgehead, citation, citetitle, classsynopsisinfo, code, command, computeroutput, database, emphasis, entry, filename, firstterm, foreignphrase, funcparams, funcsynopsisinfo, function, glosssee, glossseealso, glossterm, hardware, interfacename, keycap, lineannotation, link, literal, literallayout, lotentry, member, msgaud, olink, option, optional, para, parameter, phrase, primary, primaryie, productname, programlisting, property, quote, refdescriptor, refentrytitle, refname, refpurpose, remark, replaceable, screen, screeninfo, secondary, secondaryie, see, seealso, seealsoie, seeie, seg, segtitle, simpara, subtitle, synopsis, systemitem, td, term, termdef, tertiary, tertiaryie, th, title, titleabbrev, tocback, tocentry, tocfront, trademark, ulink, userinput.

Children

The following elements occur in optional: action, anchor, application, beginpage, classname, code, command, computeroutput, constant, database, email, envar, errorcode, errorname, errortext, errortype, exceptionname, filename, function, guibutton, guiicon, guilabel, guimenu, guimenuitem, guisubmenu, hardware, indexterm, inlinegraphic, inlinemediaobject, interface, interfacename, keycap, keycode, keycombo, keysym, link, literal, markup, medialabel, menuchoice, methodname, mousebutton, nonterminal, olink, ooclass, ooexception, oointerface, option, optional, package, parameter, prompt, property, remark, replaceable, returnvalue, sgmltag, structfield, structname, subscript, superscript, symbol, systemitem, token, type, ulink, uri, 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]


option		orderedlist