DocBook 5.1: The Definitive Guide  (Version 1.5.3 for DocBook 5.1)

optional

optional — Optional information.

Synopsis

optional ::= [-]

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 being documented.

Processing expectations

Formatted inline.

Optional arguments in a synopsis are usually given special typographic treatment, and 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.

Children

The following elements occur in optional: text, abbrev, acronym, alt, anchor, annotation, biblioref, coref, date, emphasis (db._emphasis), firstterm (db._firstterm), footnote, footnoteref, foreignphrase (db._foreignphrase), glossterm (db._glossterm), indexterm (db.indexterm.endofrange), indexterm (db.indexterm.singular), indexterm (db.indexterm.startofrange), inlinemediaobject, link, olink, phrase (db._phrase), quote (db._quote), remark, replaceable, subscript, superscript, trademark, wordasword, xref.

Examples

<article xmlns='http://docbook.org/ns/docbook'>
<title>Example optional</title>

<synopsis>
ls <option>-abcCdfFgilLmnopqrRstux1</option>
   <optional>names</optional>
</synopsis>

</article>

ls -abcCdfFgilLmnopqrRstux1
   names