DocBook: The Definitive GuideBy Norman Walsh & Leonard Muellner1st Edition October 1999 1-56592-580-7, Order Number: 5807 652 pages, $36.95 , Includes CD-ROM |
Optional
Synopsis
Mixed Content Model
Optional ::= ((#PCDATA|Link|OLink|ULink|Action|Application|ClassName|Command| ComputerOutput|Database|Email|EnVar|ErrorCode|ErrorName| ErrorType|Filename|Function|GUIButton|GUIIcon|GUILabel|GUIMenu| GUIMenuItem|GUISubmenu|Hardware|Interface|InterfaceDefinition| KeyCap|KeyCode|KeyCombo|KeySym|Literal|Constant|Markup| MediaLabel|MenuChoice|MouseButton|MsgText|Option|Optional| Parameter|Prompt|Property|Replaceable|ReturnValue|SGMLTag| StructField|StructName|Symbol|SystemItem|Token|Type|UserInput| VarName|Anchor|Comment|Subscript|Superscript|InlineGraphic| InlineMediaObject|IndexTerm)+)Attributes
Tag Minimization
Both the start- and end-tags are required for this element.
Parameter Entities
%cptr.char.mix; %ndxterm.char.mix; %para.char.mix; %programlisting.content; %refinline.char.mix; %refname.char.mix; %screen.content; %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, Command, Comment, ComputerOutput, Database, Emphasis, entry, Filename, ForeignPhrase, FuncParams, FuncSynopsisInfo, Function, GlossSee, GlossSeeAlso, GlossTerm, Hardware, Interface, InterfaceDefinition, KeyCap, LineAnnotation, Link, Literal, LiteralLayout, LoTentry, Member, MsgAud, OLink, Option, Optional, Para, Parameter, Phrase, Primary, PrimaryIE, ProductName, ProgramListing, Property, Quote, RefDescriptor, RefEntryTitle, RefName, RefPurpose, Replaceable, Screen, ScreenInfo, Secondary, SecondaryIE, See, SeeAlso, SeeAlsoIE, SeeIE, Seg, SegTitle, SimPara, Subtitle, Synopsis, SystemItem, Term, Tertiary, TertiaryIE, Title, TitleAbbrev, ToCback, ToCentry, ToCfront, Trademark, ULink, UserInput.
Children
The following elements occur in Optional: Action, Anchor, Application, ClassName, Command, Comment, ComputerOutput, Constant, Database, Email, EnVar, ErrorCode, ErrorName, ErrorType, Filename, Function, GUIButton, GUIIcon, GUILabel, GUIMenu, GUIMenuItem, GUISubmenu, Hardware, IndexTerm, InlineGraphic, InlineMediaObject, Interface, InterfaceDefinition, KeyCap, KeyCode, KeyCombo, KeySym, Link, Literal, Markup, MediaLabel, MenuChoice, MouseButton, MsgText, OLink, Option, Optional, Parameter, Prompt, Property, Replaceable, ReturnValue, SGMLTag, StructField, StructName, Subscript, Superscript, Symbol, SystemItem, Token, Type, ULink, UserInput, VarName.
In some contexts, the following elements are allowed anywhere: BeginPage, IndexTerm.
In some contexts, the following elements are excluded: IndexTerm.
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 V3.1//EN"> <synopsis> ls <optional><option>-abcCdfFgilLmnopqrRstux1</option></optional> <optional>names</optional> </synopsis>ls [-abcCdfFgilLmnopqrRstux1] [names]which might generate the following output:
ls [ -abcCdfFgilLmnopqrRstux1 ] [names]
Back to: DocBook: The Definitive Guide
© 2001, O'Reilly & Associates, Inc.