optional
Synopsis
Mixed Content Model
optional ::= (#PCDATA|link|olink|ulink|action|application|classname|methodname| interfacename|exceptionname|ooclass|oointerface|ooexception| command|computeroutput|database|email|envar|errorcode|errorname| errortype|filename|function|guibutton|guiicon|guilabel|guimenu| guimenuitem|guisubmenu|hardware|interface|keycap|keycode| keycombo|keysym|literal|constant|markup|medialabel|menuchoice| mousebutton|option|optional|parameter|prompt|property| replaceable|returnvalue|sgmltag|structfield|structname|symbol| systemitem|token|type|userinput|varname|nonterminal|anchor| remark|subscript|superscript|inlinegraphic|inlinemediaobject| indexterm|beginpage)*
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.
![[4.0]](figures/rev_4.0.png)
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: application, attribution, bibliomisc, bridgehead, citation, citetitle, classsynopsisinfo, command, computeroutput, emphasis, entry, foreignphrase, funcparams, funcsynopsisinfo, function, glosssee, glossseealso, glossterm, lineannotation, link, literal, literallayout, lotentry, member, msgaud, olink, optional, para, phrase, primary, primaryie, productname, programlisting, quote, refdescriptor, refentrytitle, refname, refpurpose, remark, replaceable, screen, screeninfo, secondary, secondaryie, see, seealso, seealsoie, seeie, seg, segtitle, simpara, subtitle, synopsis, term, tertiary, tertiaryie, title, titleabbrev, tocback, tocentry, tocfront, trademark, ulink, userinput.
Children
The following elements occur in optional: action, anchor, application, beginpage, classname, command, computeroutput, constant, database, email, envar, errorcode, errorname, 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, parameter, prompt, property, remark, replaceable, returnvalue, sgmltag, structfield, structname, subscript, superscript, symbol, systemitem, token, type, ulink, userinput, varname.
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]