Formatting Command Synopsis Diagrams

The following guidelines describe how to format command
synopsis diagrams.
 
Put all optional items, including both flags and arguments, in 
brackets; for example [file].  
Put an optional argument to an optional flag in
its own pair of brackets, following the flag 
(which is within its pair of brackets).
For example, [-a] [file] indicates an optional flag -a
with its optional argument file, as opposed to [-a file],
which indicates an optional flag -a and its required argument
file.  

This may incorrectly imply that the argument could be specified
without the flag; when in doubt, consult the Flags section of the
reference page.

Use the default font for brackets.  Include a space before the 
left bracket and after the right bracket.
 
Group flags that do not take arguments together.
If these flags are optional, group them in a pair of brackets.  
If some are required and some are optional, group them separately --
the required flags with no brackets followed by the optional flags 
in brackets: for example, -ajkv. 
Show flags that have associated arguments separately.  
However, do not group flags that are mutually exclusive, that is, flags
that cannot be used together.
 
Put flags, including  groups of flags, in alphabetical order
(U.S. English), with uppercase letters following lowercase letters; for
example, -aAjkKv.
 
Put command arguments in the order required by the command, if any.
Put mandatory arguments before optional arguments, unless the command
requires otherwise.
If an argument represents the primary object of the command (for example,
a file or directory) put it before the other arguments if possible.	
 
Indicate arguments of indeterminate number with an ellipsis
following the argument name; for example, [-a file ...].  
However, do not use plural argument names 
even if the argument may be repeated.
 
When two or three flags or arguments are mutually exclusive -- that is, they
may not be used together -- list them next to each other separated by 
vertical bars; for example,
-a | -j or [-k file | directory].
Use the default font for the vertical bar.
Include a space before and after the vertical bar.

NOTE 
If you cannot describe all possible combinations or necessary information
using the previous guidelines, 
show different combinations as separate syntax diagrams on separate lines
(as if they were separate commands).


For files that are not invoked from the command line,
put the pathname to the file in the Files section, and do
not include a Synopsis section.
For daemons that are not invoked from the command line, put  
the name of the daemon in Synopsis. However, if the reference page
discusses subcommands of the daemon
that are invoked from the command line, diagram the subcommands.

