<refentry id="group.element">
<?dbhtml filename="group.html"?>
<refentryinfo>
<pubdate>$Date$</pubdate>
<releaseinfo>$Revision$</releaseinfo>
</refentryinfo>

<refmeta>
<indexterm><primary>elements</primary>
<secondary>group</secondary></indexterm>
<refentrytitle>group</refentrytitle>
<refmiscinfo>Element</refmiscinfo>
</refmeta>
<refnamediv>
<refname>group</refname>
<refpurpose>&group.purpose;</refpurpose>
</refnamediv>

&group.synopsis.gen;
<refsect1 condition='ref.description'><title>Description</title>

<para>
A <sgmltag>Group</sgmltag> surrounds several related items. Usually, they are
grouped because they are mutually exclusive. The user is expected to select
one of the items.
</para>

<refsect2><title>Processing expectations</title>
<para>
&format.inline; The additional processing expectations of a
<sgmltag>Group</sgmltag> are significant.  For a complete discussion,
see <sgmltag>CmdSynopsis</sgmltag>.
</para>
<itemizedlist>
<listitem><para>
Multiple arguments within a group are considered exclusive and are
separated by vertical bars.
</para></listitem>
<listitem><para>
Brackets are used to distinguish between optional, required, or plain
arguments.  Usually square brackets are placed around optional
arguments, <option>[-f | -g]</option>, and curly brackets are placed
around required arguments, <option>{-f | -g}</option>.  Plain
arguments are required, but are not decorated with brackets.
</para></listitem>
<listitem><para>
Repeatable arguments are followed by an ellipsis.
</para></listitem>
</itemizedlist>
</refsect2>

<refsect2 role='fu' revision="4.0"><title>&FutureChanges;</title>
<para>
<indexterm><primary>DocBook DTD</primary><secondary>Changes for <acronym>V4.0</acronym></secondary>
</indexterm>
The <literal>OptMult</literal> and <literal>ReqMult</literal> values for the
<sgmltag class='attribute'>Choice</sgmltag> attribute will be removed in
DocBook <acronym>V4.0</acronym>.  Use the <sgmltag class='attribute'>Rep</sgmltag> attribute
instead to indicate that the choice is repeatable.
</para>
</refsect2>



&group.parents.gen;
&group.children.gen;
</refsect1>
<refsect1 condition='ref.elem.attrdesc'><title>Attributes</title>
<variablelist>
<varlistentry><term>choice</term>
<listitem>
<para>
<sgmltag class="attribute">Choice</sgmltag> indicates whether the <sgmltag>Arg</sgmltag>
is required (<literal>Req</literal> or <literal>Plain</literal>) or
optional (<literal>Opt</literal>). Arguments identified as <literal>Plain</literal>
are required, but are shown without additional decoration. The
<literal>OptMult</literal> and <literal>ReqMult</literal> choices will
be removed in DocBook V4.0; use the <sgmltag class="attribute">Rep</sgmltag>
attribute instead.
</para>
</listitem>
</varlistentry>
<varlistentry><term>rep</term>
<listitem>
<para>
A <sgmltag class="attribute">Rep</sgmltag> value of <literal>Repeat</literal> indicates that
the <sgmltag>Group</sgmltag> is reapeatable. This is frequently rendered with an
ellipsis.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1 condition='ref.elem.seealso'><title>See Also</title>
&group.seealso.gen;
</refsect1>
<refsect1><title>Examples</title>

&group.example.seealso.gen;
</refsect1>
</refentry>

