Man Pages – Understand Synopsis in Manpage

man

I have not been able to understand the SYNOPSIS section in the manpage of a command. For example, let's see the manpage of man itself. By man man:

SYNOPSIS
       man  [-C  file]  [-d]  [-D]  [--warnings[=warnings]]  [-R encoding] [-L
       locale] [-m system[,...]] [-M path] [-S list]  [-e  extension]  [-i|-I]
       [--regex|--wildcard]   [--names-only]  [-a]  [-u]  [--no-subpages]  [-P
       pager] [-r prompt] [-7] [-E encoding] [--no-hyphenation] [--no-justifi‐
       cation]  [-p  string]  [-t]  [-T[device]]  [-H[browser]] [-X[dpi]] [-Z]
       [[section] page ...] ...
       man -k [apropos options] regexp ...
       man -K [-w|-W] [-S list] [-i|-I] [--regex] [section] term ...
       man -f [whatis options] page ...
       man -l [-C file] [-d] [-D] [--warnings[=warnings]]  [-R  encoding]  [-L
       locale]  [-P  pager]  [-r  prompt]  [-7] [-E encoding] [-p string] [-t]
       [-T[device]] [-H[browser]] [-X[dpi]] [-Z] file ...
       man -w|-W [-C file] [-d] [-D] page ...
       man -c [-C file] [-d] [-D] page ...
       man [-hV]
  1. Does the SYNOPSIS section describe the syntax for the command?
  2. what do those [...]and [...] inside [...] mean? Do they mean
    something optional?
  3. Does | mean OR?
  4. What does , mean in [-m system[,...]]?
  5. Does the SYNOPSIS section follow the rules used for Regular Expressions?

Best Answer

  1. The synopsis section usually gives some example use-cases. Sometimes sub-commands have different options, so several examples might be shown.
  2. Brackets [] always denote optional switches, arguments, options, etc.
  3. Yes, the pipe | means or, particularly when inside brackets or parenthesis.
  4. Brackets in brackets just means that the second part is dependent on the first, and also itself optional. Some switches you can use on their own or add a value to them. Commas at the start of a bracket would indicate there can be multiple comma separated values.
  5. They lean on Regex concepts, but are meant to be human readable so don't follow all the escaping rules etc.
Related Question