52

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?
Improve this question
3
  • 3
    If you want a reference, they are loosely based on EBNF. Commented Aug 1, 2011 at 21:32
  • 2
    Related: "Utility Conventions" in the POSIX standard: pubs.opengroup.org/onlinepubs/9699919799/basedefs/… Commented Jul 11, 2018 at 21:01
  • Please consider stating the version of man. The local version (v2.12.0, 2023-09-23) synopsis compared greatly differs. Commented Oct 29, 2024 at 13:00

3 Answers 3

Reset to default
36
  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.
Improve this answer
4
  • Thanks! Are there some references explaining the syntax of synopsis? Commented Aug 1, 2011 at 20:24
  • @Tim: That's one of the craziest ones I've seen, I think if you read a few more you'll get the hang of it. It's just convention, not magic. Commented Aug 1, 2011 at 20:46
  • 1
    The synopsis section does not give usage examples. The idea is that it shows all correct ways of invoking the command. Commented Jun 15, 2020 at 9:40
  • Just in case, there's an explicit section EXAMPLES in the man-files. Commented Oct 29, 2024 at 13:02
15

From man man page :

The following conventions apply to the SYNOPSIS section and can be used as a guide in other sections. man synopsis description

Exact rendering may vary depending on the output device. For instance, man will usually not be able to render italics when running in a terminal, and will typically use underlined or coloured text instead.

The command or function illustration is a pattern that should match all possible invocations. In some cases it is advisable to illustrate several exclusive invocations as is shown in the SYNOPSIS section of this manual page.

Improve this answer
5

Another source for understanding the meaning of the command line utility argument syntax would be the Utility Argument Syntax conventions documented in Chapter 12 and Regular Expressions documented in Chapter 9 of the POSIX.1-2008 (2013 Edition) standard.

Improve this answer
1
  • Finally... Dear... Thank you! Apparently, there is no example for an explicit denotation of support for double-dash (--) but just a guideline for it to be expected. Commented Oct 29, 2024 at 12:55

You must log in to answer this question.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.