Unix - Read the synopsis of a man page

March 2017

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


Published by jak58.
This document, titled "Unix - Read the synopsis of a man page," is available under the Creative Commons license. Any copy, reuse, or modification of the content should be sufficiently credited to CCM (ccm.net).