This is the mail archive of the
docbook@lists.oasis-open.org
mailing list for the DocBook project.
Re: command description: arg and option
- From: "Jens M. Felderhoff" <j dot m dot f at gmx dot li>
- To: "Fischer, Oliver" <plexus at snafu dot de>
- Cc: docbook at lists dot oasis-open dot org
- Date: Sat, 25 Jan 2003 19:53:53 +0100
- Subject: Re: DOCBOOK: command description: arg and option
- References: <3E302E34.2030601@snafu.de>
"Fischer, Oliver" <plexus@snafu.de> wrote:
> I don't get the difference between arg and option. OK, according
> to the dtd. The syntactial difference is clear, but not the
> semantical one.
>
> If I describe, I can use <arg> for -a or -dontkillit and so one.
> But why can I use option als child of arg?
> And why can't I use <arg> within <para> as <option>?
My interpretation is that there are several types of arguments:
- An option is a special argument that influences the behavior of the
command, like the "-l" option of the Unix ls command that tells the
command to create a long listing:
<arg><option>-l</option></arg>
- An option with an option argument, possibly replaceable, that
provides extra parameters to the commend like "-o outputfile":
<arg>
<option>-o</option><replaceable>outfile</replaceable>
</arg>
or
<arg>
<option>-b</option>
<group choice="req">
<arg>dec</arg>
<arg>hex</arg>
<arg>oct</arg>
</group>
</arg>
- An argument not prefixed by an option, e.g., that tells the command
on what to operate, e.g., "ls thisdir":
<arg choice=plain><replaceable>filename</replaceable></arg>
The difference should become apparent when rendered. Usually options
and required arguments are rendered in boldface while replaceable
arguments are rendered in italics or underlined.
> My concrete situation is, that I described a command with
> cmdsynopsis, using <arg> for all the options as -file and so on.
> But within the text I must use option if I write something as:
>
> Use the <option>-file</option> to specify an file...
To remain consistent, you can also use <cmdsynopsis> with all its
children within a <para>.
Cheers
Jens
--
(Intentionally left blank.)