Unix - Read the synopsis of a man page

December 2016





The synopsis of a man, it's part of a manual page called with the command man, describing the use of a command line in a shell.

This is not always easy to read the synopsis of a man as the explanations about organization options, may vary from on to another.

Fortunately, there are some common ground.

Generally, man pages use brackets to delimit an optional block.

Example with the synopsis of "man lynx":

Lynx [options] [path or URL]


At least, this one is straight forward and intuitive ... In fact, the synopsis defines more of the "use" of a man.
It thus indicates the first options (which are reported later in the man), then the path to a file or directory, or a URL. For example:

lynx-color [www.ccm.net]
    • to display the homepage of Kioskea in color.



Now, there are often optionsavailable in the synopsis. Meaning that you will often have a choice between several alternatives for the same argument:
  • A Short option of type -f or -a..
  • A Long option of type "--force"


So in the same block, you can find these two alternatives separated by a "pipe", ie the character | means "or".

So for example:

command [-f | --force] [filename]


To say that you can type -f or -force, the choice for these two arguments have the same meaning. Then you can follow this option by a space then the path to a file.

With that, the synopsis of "man mysql" should be clear. Click here

You will notice a few exceptions:
For [-p[pwd]] you have a block inside a block, and no space to separate them.
This means you can type the password (optional) just after the -p argument (optional too) without spaces.

Example for a connection to a local mysql database with the root and the password(pass):

mysql -u root -ppass -h localhost


Then there are the synopsis even more complicated, like the one for tar

Here, | mean "or" is sometimes but replaced by commas.
The major command are reported at the beginning, starting with a [-] to specify that the arguments are short (optional) take a dash, then we have the big block.

You have the choice between a (you can replace - or -concatenate) or -c or -x etc. .... The a the commands that are major to tar are "extract", "create an archive" ... So you must choose one major according to your needs, so there is a | between each.

Then you're free to add an option, you must put a file (or several) or a directory.
To extract a .tar.gz file:

tar -zxvf machin.tar.gz
  • x is the major option (extract) and the options are z, v and f, respectively,
  • Z compressed with gzip,
  • V verbal (see details),
  • f for file (extract file).

Related :

This document entitled « Unix - Read the synopsis of a man page » from CCM (ccm.net) is made available under the Creative Commons license. You can copy, modify copies of this page, under the conditions stipulated by the license, as this note appears clearly.