Howto Style
PrevNext

Function and Command Synopsis

The elements of the Synopsis family are used to give the reader the usage of a function or command.

Function Synopsis

A function synopsis is introduced with the element <FuncSynopsis>. A function synopsis is composed of one or more function prototypes (<FuncPrototype>), preceded and followed by optional function synopsis information (<FuncSynopsisInfo>).

Example 7. Function synopsis structure

<FuncSynopsis>
  <FuncSynopsisInfo> </FuncSynopsisInfo> <!-- optional -->

  <FuncPrototype> </FuncPrototype>       <!-- REQUIRED -->
  <FuncPrototype> </FuncPrototype>       <!-- optional -->
  <FuncPrototype> </FuncPrototype>       <!-- optional -->

  <FuncSynopsisInfo> </FuncSynopsisInfo> <!-- optional -->
</FuncSynopsis>

The function prototype, introduced by <FuncPrototype>, is composed of a function definition, followed by the function arguments.

The function definition, introduced by <FuncDef>, is the function name and its return type.

The functions arguments can be <Void> if the function does not take any argument, or <VarArgs> if the function takes a variable number of arguments, or one or more parameters (<ParamDef>).

A function parameter, introduced by <ParamDef>, is the parameter name and its name.

Example 8. Function prototype structure

<FuncSynopsis>

  <FuncPrototype>
    <FuncDef>int <Function>rand</Function></FuncDef>
    <Void>
  </FuncPrototype>
  
  <FuncPrototype>
    <FuncDef>int <Function>max</Function></FuncDef>
    <VarArgs>
  </FuncPrototype>
  
  <FuncPrototype>
    <FuncDef>int <Function>max</Function></FuncDef>
    <ParamDef>int <Parameter>int1</Parameter></ParamDef>
    <ParamDef>int <Parameter>int2</Parameter></ParamDef>
  </FuncPrototype>
  
</FuncSynopsis>
	  
int rand(void);
int max(...);
int max(int int1, int int2);

The function synopsis information can be used to give the header file defining a function:

Example 9. Function synopsis information

<FuncSynopsis>
  <FuncSynopsisInfo>
    #include &lt;<filename class="headerfile">varargs.h</filename>&gt;
  </FuncSynopsisInfo>
<FuncPrototype>
  <FuncDef>int <Function>max</Function></FuncDef>
  <VarArgs>
</FuncPrototype>
</FuncSynopsis>
	    
#include <varargs.h>
	      
int max(...);

Command Synopsis

A command synopsis is introduced with the element <CmdSynopsis>. A command synopsis is composed of the command name, followed by its arguments.

Because a command can have a huge number of arguments, the <SBR> element is provided to explicitly break the line at a correct place in a command synopsis.

The <Group> element defines a group of arguments, to be used when a user can choose between several arguments.

Example 10. Groups of arguments

<cmdsynopsis>
  <command>command</command>
  <arg>-R</arg>
  <group>
    <arg>-H</arg>
    <arg>-L</arg>
    <arg>-P</arg>
  </group>
</cmdsynopsis>
command  [-R] [-H | -L | -P]

An argument or a group of arguments can be optional or required. You can specify that an argument or a group of arguments is optional or required with the attribute choice. A value of Opt indicates that the argument or group is optional. A value of Req indicates that the argument is required. A value of Plain indicates that the argument is required, but is shown without additional decoration.

Example 11. Optional and required arguments

  <!-- file is optional -->
<cmdsynopsis>
  <command>command</command>
  <arg><replaceable>file</replaceable></arg>
</cmdsynopsis>
  
  <!-- file or - is optional -->
  <cmdsynopsis>
  <command>command</command>
  <group>
    <arg><replaceable>file</replaceable></arg>
    <arg>-</arg>
  </group>
</cmdsynopsis>
  
  <!-- file is required -->
<cmdsynopsis>
  <command>command</command>
  <arg choice=plain><replaceable>file</replaceable></arg>
</cmdsynopsis>
  
  <!-- file or - is required -->
<cmdsynopsis>
  <command>command</command>
  <group choice=plain>
    <arg><replaceable>file</replaceable></arg>
    <arg>-</arg>
  </group>
</cmdsynopsis>
  
  <!-- file is required -->
<cmdsynopsis>
  <command>command</command>
  <arg choice=req><replaceable>file</replaceable></arg>
</cmdsynopsis>
  
  <!-- file or - is required -->
<cmdsynopsis>
  <command>command</command>
  <group choice=req>
    <arg><replaceable>file</replaceable></arg>
    <arg>-</arg>
  </group>
</cmdsynopsis>
command  [file]

	  
command  [file | -]

	  
command   file 

	  
command   file | - 

	  
command  {file}

	  
command  {file | -}

An argument or group of elements can be repeated several times in the command line. To indicate that an argument is repeatable, use the attribute rep with the value repeat. The default value for the attribute rep is norepeat, which means that the argument is not repeatable.

Example 12. Repeatable arguments and groups

<cmdsynopsis>
  <command>command</command>
  <arg rep=repeat choice=plain><replaceable>file</replaceable></arg>
</cmdsynopsis>

<cmdsynopsis>
  <command>command</command>
  <group rep=repeat choice=plain>
    <arg choice=plain><replaceable>file</replaceable></arg>
    <arg choice=plain><replaceable>directory</replaceable></arg>
  </group>
</cmdsynopsis>
command   file... 

	  
command   file | directory...

Some arguments, replaceable, must not be included "as is" in the command line, but replaced by a specific value. An example of such an argument if file, which must be replaced my the name of the file the user wants to process. You indicate that an argument is replaceable with the element <replaceable>.

PrevHomeNext
Main Body Keyboard, mouse and GUI related elements