$arg-choice-def-close-str, …
$arg-choice-def-close-str, $v:arg-choice-def-open-str, $v:arg-choice-opt-close-str, $v:arg-choice-opt-open-str, $v:arg-choice-plain-close-str, $v:arg-choice-plain-open-str, $v:arg-choice-req-close-str, $v:arg-choice-req-open-str, $v:arg-or-sep, $v:arg-rep-def-str, $v:arg-rep-norepeat-str, $v:arg-rep-repeat-str — Punctuation marks used in formatting cmdsynopsis
.
Synopsis
|<xsl:variable name="v:arg-choice-opt-open-str">
| <span class="cmdpunct">[</span>
|</xsl:variable>
|<xsl:variable name="v:arg-choice-opt-close-str">
| <span class="cmdpunct">]</span>
|</xsl:variable>
|<xsl:variable name="v:arg-choice-req-open-str">
| <span class="cmdpunct">{</span>
|</xsl:variable>
|<xsl:variable name="v:arg-choice-req-close-str">
| <span class="cmdpunct">}</span>
|</xsl:variable>
|<xsl:variable name="v:arg-choice-plain-open-str">
| <xsl:text/>
|</xsl:variable>
|<xsl:variable name="v:arg-choice-plain-close-str">
| <xsl:text/>
|</xsl:variable>
|<xsl:variable name="v:arg-choice-def-open-str">
| <span class="cmdpunct">[</span>
|</xsl:variable>
|<xsl:variable name="v:arg-choice-def-close-str">
| <span class="cmdpunct">]</span>
|</xsl:variable>
|<xsl:variable name="v:arg-rep-repeat-str">
| <span class="cmdpunct">…</span>
|</xsl:variable>
|<xsl:variable name="v:arg-rep-norepeat-str">
| <xsl:text/>
|</xsl:variable>
|<xsl:variable name="v:arg-rep-def-str">
| <xsl:text/>
|</xsl:variable>
|<xsl:variable name="v:arg-or-sep">
| <span class="cmdpunct"> | </span>
|</xsl:variable>
Description
The cmdsynopsis
element is used to model the syntax of
command line interfaces. Broadly, a command line interface consists of a command
followed by a variety of options. These options can be optional or required
and may or may not be repeatable.
User expections about how these should be formatted vary by platform and publisher. The $v:arg-… variables are designed to make it easy to adapt to many common forms of presentation. Each contains (usually) a single character used as a delimiter:
Variable | Use in a synopsis | Defaulta |
---|---|---|
$v:arg-choice-def-close-str | Follows a default option | ] |
$v:arg-choice-def-open-str | Precedes a default option | [ |
$v:arg-choice-opt-close-str | Follows an optional option | ] |
$v:arg-choice-opt-open-str | Precedes an optional option | [ |
$v:arg-choice-plain-close-str | Follows an option identified as “plain” | (empty string) |
$v:arg-choice-plain-open-str | Precedes an option identified as “plain” | (empty string) |
$v:arg-choice-req-close-str | Follows a required option | } |
$v:arg-choice-req-open-str | Precedes a required option | { |
$v:arg-or-sep | Separator between options in an “or” group | | |
$v:arg-rep-def-str | Identifies a repeatable default option | (empty string) |
$v:arg-rep-norepeat-str | Identifies a non-repeatable option | (empty string) |
$v:arg-rep-repeat-str | Identifies an explicitly repeatable option | … |
Each of the default characters is placed
in an HTML span
with the class “cmdpunct
”.
A contrived cmdsynopsis
appears in
Example 1, “An example of a cmdsynopsis
”.
|<cmdsynopsis>
| <command>command</command>
| <arg choice="plain">
| <option>--path <replaceable>PATH</replaceable>
| </option>
| </arg>
| <arg>-opt</arg>
| <arg choice="req">-req</arg>
| <arg rep="repeat">-D<replaceable>name</replaceable>
| </arg>
| <group>
| <arg choice="plain">-M</arg>
| <arg choice="plain">-MD</arg>
| </group>
|</cmdsynopsis>
cmdsynopsis
One possible rendering of such a synopsis:
--path PATH
[-opt] {-req} [-Dname…] [-M | -MD]