As of today, there are about 50% of man pages follow the syntax introduced by Ivan, the other half follows the old syntax.

I have noticed the following differences:

(1) '...n' vs. '...':

Unix man page uses '...' (3 dots) to denote an item that can be repeated 0 or more times, but not '...n' (3 dots followed by an 'n').

Examples:
   alias [NAME[=VALUE]...n]
   vs.
   mv [OPTION]... SOURCE... DIRECTORY


(2) Indicating a required item using curly braces:

Here is an example from the \compare man page:
   compare [OPTION]...n { FILE_A } { FILE_B }  <------------ (2-a)
   DESCRIPTION
       Compare FILE_A vs FILE_B and generates comparison results in a new tab...
   OPTIONS
       -es { STRING_VALUE }   <------------ (2-b)
              Defines the character used to indicate an explicit SQL buffer request.
       -ec { STRING_VALUE }

   (2-a) : Unix man page does not enclose a required command line argument in curly braces in the SYNOPSIS section.
   (2-b) : Unix man page does not enclose a required option argument in curly braces in the OPTIONS section.

On UNIX, if an argument is required, then it is described as the way it would appear; if an argument is optional, then it is surrounded by square brackets. For examples:
   grep [OPTIONS] PATTERN [FILE...]
   OPTIONS
       -f FILE
       --color[=WHEN]
UNIX seldom uses curly braces in man page, below is an example from tail's man page:
   -f, --follow[={name|descriptor}]
which is similar to the -ca and -ct options described in the \connect man page.


(3) Using curly braces in the SYNOPSIS section:

UNIX does not use curly braces in the SYNOPSIS section as the \change command does:
   change { database [DATABASE_NAME] | schema [SCHEMA_NAME] }
If we follow this convention, the SYNOPSIS of the \list command would be lengthy and hard to read:
   list database
   list [-h] databases
   list [-d DATABASE] [-h] schemas
   list [-d DATABASE] [-h] [-s SCHEMA] tables
   list [-d DATABASE] [-h] [-s SCHEMA] views


(4) Describing non-option command line argument (i.e. argument not starts with '-' character) in the OPTIONS section:

Here is an example from the \alias command:
   alias [NAME[=VALUE]...n]
   OPTIONS
      [NAME]  Name of the alias
      [VALUE] Value of the alias

UNIX man page would explain NAME and VALUE in the DESCRIPTION section but not the OPTIONS section.  The OPTIONS section is for options only.
 

We will follow UNIX man page conventions:

>>>> (1) '...n' vs. '...':
Go with '...', for examples: FILE..., [FILE...]

>>>> (2) Indicating a required item using curly braces:
Will not enclose a required command line argument in curly braces.

>>>> (3) Using curly braces in the SYNOPSIS section:
Will not use curly braces in the SYNOPSIS section.

>>>> (4) Describing non-option command line argument (i.e. argument not starts with '-' character) in the OPTIONS section:
Will not do this.

SVN r27862, r27879, r27972.


In addition, man page layout has changed; 2 new sections, NAME and SYNOPSIS, are added. Please see issue #6837 for more info.
   https://www.aquaclusters.com/app/home/project/public/aquadatastudio/issue/6837

The presence of the 3 mandatory sections (NAME, SYNOPSIS, DESCRIPTION) in the man page of each command, verified here.

NAME part verified in #6837 - fluid shell - \help -d -> you will notice that we do not have a standard for command descriptions

SYNOPSIS part verified in #7082 - Help pattern for COMMAND_USAGE

OPTIONS part verified here, (i.e., "the OPTIONS section is for options only").

Closing current issue.