Is there a standard for writing a command synopsis?

Question

It appears to me that everyone has their own idea on how to write a synopsis describing command usage for the end user.

For example, this is the format from man grep:

grep [OPTIONS] PATTERN [FILE...]
grep [OPTIONS] [-e PATTERN | -f FILE] [FILE...]

Now this has some syntax that appears in other manpages. [] is recognized as optional, and ... makes sense as multiple of the same input.

But people use | or / for OR and there are others that will reverse what [] means. Or they do not give any indication as to where [OPTIONS] goes.

I would like to follow a standard for what I write, but every website I look at tells me something different.

Is there an actual standard way of writing synopses, or is the convention just what people have been doing over time?

Answer 1

The classic standard for this is from POSIX, Utility Argument Syntax (thanks to @illuminÉ for the updated link). It describes the syntax to be used in man pages, for example

utility_name[-a][-b][-c option_argument]
    [-d|-e][-f[option_argument]][operand...]

Being classic, it recommends using single-character options, with -W recommended for use by vendors, and that is how multi-character options are accommodated (see, for example, gcc Option Summary).

GNU software introduced multi-character options that start with --. Some guidelines from GNU for formatting man pages with those options can be found in the help2man reference.

Answer 2

Actually one answer can be found looking for SYNOPSIS (surprise!) in man 7 man-pages; it says:

       SYNOPSIS      A brief summary of the command or function's interface.

                     For commands, this shows the syntax of  the  command  and
                     its  arguments  (including options); boldface is used for
                     as-is text and italics are used to  indicate  replaceable
                     arguments.   Brackets  ([])  surround optional arguments,
                     vertical bars (|) separate choices,  and  ellipses  (...)
                     can  be  repeated.   For functions, it shows any required
                     data declarations or #include directives, followed by the
                     function declaration.

                     Where  a  feature  test macro must be defined in order to
                     obtain the declaration of a function (or a variable) from
                     a header file, then the SYNOPSIS should indicate this, as
                     described in feature_test_macros(7).