Re: DOCBOOK: command description: arg and option

["Jens M. Felderhoff" <j.m.f@gmx.li>]

"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.)