ada: Update gnatpp documentation with --layout switch

Update legacy switches.

gcc/ada/

	* doc/gnat_ugn/gnat_utility_programs.rst: add gnatpp --layout
	switch and update legacy switches.

1 files changed, 325 insertions, 506 deletions

diff --git a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
index 7df45d5..639534d 100644
--- a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
+++ b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
@@ -496,18 +496,18 @@ building specialized scripts.
 
    where
 
-   * ``switches`` is an optional sequence of switches defining such properties as
-     the formatting rules, the source search path, and the destination for the
-     output source file
+   * ``switches`` is an optional sequence of switches defining such properties
+     as the formatting rules, the source search path, and the destination for
+     the output source file
 
    * ``filename`` is the name of the source file to reformat; wildcards
      or several file names on the same gnatpp command are allowed. The
      file name may contain path information; it does not have to follow
      the GNAT file naming rules
 
-     Note that it is no longer necessary to specify the Ada language version;
-     ``gnatpp`` can process Ada source code written in any version from
-     Ada 83 onward without specifying any language version switch.
+   Note that it is no longer necessary to specify the Ada language version;
+   ``gnatpp`` can process Ada source code written in any version from Ada 83
+   onward without specifying any language version switch.
 
 
    .. _Switches_for_gnatpp:
@@ -519,8 +519,8 @@ building specialized scripts.
    ``gnatpp``, organized by category.
 
    You specify a switch by supplying a name and generally also a value.
-   In many cases the values for a switch with a given name are incompatible with
-   each other
+   In many cases the values for a switch with a given name are incompatible
+   with each other
    (for example the switch that controls the casing of a reserved word may have
    exactly one value: upper case, lower case, or
    mixed case) and thus exactly one such switch can be in effect for an
@@ -532,191 +532,267 @@ building specialized scripts.
    Abbreviated forms (the name appearing once, followed by each value) are
    not permitted.
 
-   .. _Alignment_Control:
 
-   Alignment Control
-   ^^^^^^^^^^^^^^^^^
+   .. _Layout_Control:
 
-   .. index:: Alignment control in gnatpp
-
-   Programs can be easier to read if certain constructs are vertically aligned.
-   By default, alignment of the following constructs is set ON:
-
-     * ``:`` in declarations,
-     * ``:=`` in initializations in declarations,
-     * ``:=`` in assignment statements,
-     * ``=>`` in associations, and
-     * ``at`` keywords in the component clauses in record representation clauses.
-
-   In addition, ``in`` and ``out`` in parameter specifications are lined up.
+   Layout Control
+   ^^^^^^^^^^^^^^
 
-   .. index:: --no-alignment (gnatpp)
-   .. index:: --alignment (gnatpp)
-   .. index:: --no-align-modes (gnatpp)
+   .. index:: Layout control in gnatpp
 
+   ``gnatpp`` provides a layout switch which controls the general
+   formatting style:
 
-   :switch:`--no-alignment`
-     Set alignment to OFF
+   .. index:: layout(gnatpp)
 
+   :switch:`--layout=default|minimal|compact|tall`
 
-   :switch:`--alignment`
-     Set alignment to ON
+   :switch:`default`
+     The default layout will follow a compact style but add aligment and put
+     some keywords on a separate line.
+     
+     Alignment is added in the the following constructs:
 
+     * ``:`` in declarations,
+     * ``:=`` in initializations in declarations,
+     * ``:=`` in assignment statements,
+     * ``=>`` in associations, and
+     * ``at`` keywords in the component clauses in record representation
+       clauses.
+
+     In addition, ``in`` and ``out`` keywords in parameter specifications are
+     also lined up.
+
+     The keyword ``is`` is placed on a separate line in a subprogram body in
+     case the spec occupies more than one line.
+
+     The keyword ``return`` is placed on a separate line if a subprogram spec
+     does not fit on one line.
+
+   :switch:`minimal`
+     The minimal layout will avoid changing the source layout by keeping all
+     line breaks from the original source (it will not insert or delete any).
+     It will add indentation where appropriate as long as it does not exceed
+     the line length limit.
+
+   :switch:`compact`
+     The compact layout will avoid adding line breaks and alignment by packing
+     as many subexpressions on the same line as possible.
+
+     Whole-line comments that form a paragraph will be filled in typical word
+     processor style (that is, moving words between lines to make them similar
+     in length, except the last one which may be shorter).
+
+     For each whole-line comment that does not end with two hyphens, inserts
+     spaces if necessary after the starting two hyphens to ensure that there
+     are at least two spaces preceding the first non-blank character of the
+     comment.
+
+   :switch:`tall`
+     The tall layout will favor adding lines breaks and alignment. It adds
+     all the alignment and line breaks defined in the ``default`` option,
+     and in addition:
+
+     * Places the keyword ``loop`` in FOR and WHILE loop statements on a
+       separate line
+     * Places the keyword ``then`` in IF statements on a separate line
+     * Places each keyword ``use`` in USE clauses on a separate line
+     * Splits the line just before the keyword ``record`` in a RECORD type
+       declaration
+     * Indents named blocks and loop statments with respect to the name
+     * When necessary, splits binary operators always before the operator
+     * Inserts an extra blank before various occurrences of ``(`` and ``:``
+     * When it is necessary to split a line between two subexpressions (because
+       otherwise the construct would exceed --max-line-length), then all such
+       subexpressions are placed on separate lines
+     * Formats enumeration type declarations “vertically”, e.g. each
+       enumeration literal goes on a separate line
+     * Formats array type declarations “vertically”, e.g. for multidimensional
+       arrays, each index_subtype_definition or discrete_subtype_definition
+       goes on a separate line
+     * Format aggregates “vertically” if named notation is used for all
+       component_associations, e.g. each component_association goes on a
+       separate line
+     * Formats case statements, case expressions, and variant parts with
+       additional line breaks
+     * Inserts blank lines where appropriate (between bodies and other large
+       constructs)
+     * Similarly to the :switch:`compact` layout, two spaces are added in the
+       beginning of a whole-line comment when needed
 
-   :switch:`--no-align-modes`
-     Do not line up ``in`` and ``out`` in parameter specifications.
 
    .. _Casing_Control:
 
-
    Casing Control
    ^^^^^^^^^^^^^^
 
    .. index:: Casing control in gnatpp
 
-   ``gnatpp`` allows you to specify the casing for reserved words,
-   pragma names, attribute designators and identifiers.
-   For identifiers you may define a
-   general rule for name casing but also override this rule
-   via a set of dictionary files.
+   ``gnatpp`` allows you to specify the casing for reserved words, pragma
+   names, attribute designators and identifiers. For identifiers you may define
+   a general rule for name casing but also override this rule via a set of
+   dictionary files.
 
-   Three types of casing are supported: lower case, upper case, and mixed case.
-   'Mixed case' means that the first letter, and also each letter immediately
-   following an underscore, are converted to their uppercase forms;
-   all the other letters are converted to their lowercase forms.
-
-   (Note: the casing switches are not yet fully supported in the
-   libadalang-based version of gnatpp.)
+   Three types of casing are supported: 'Lower Case', 'Upper Case', and
+   'Mixed Case'. 'Mixed case' means that the first letter, and also each
+   letter immediately following an underscore, are converted to their
+   uppercase forms and all the other letters are converted to their lowercase
+   forms.
 
    .. index:: --name-case-as-declared (gnatpp)
 
-   :switch:`--name-case-as-declared`
+   :switch:`--name-case-as-declared, -nD`
      Name casing for defining occurrences are as they appear in the source file
-     (this is the default)
+     (this is the default).
 
    .. index:: --name-upper-case (gnatpp)
 
-   :switch:`--name-upper-case`
-     Names are in upper case
+   :switch:`--name-upper-case, -nU`
+     Names are in upper case.
 
    .. index:: --name-lower-case (gnatpp)
 
-   :switch:`--name-lower-case`
-     Names are in lower case
+   :switch:`--name-lower-case, -nL`
+     Names are in lower case.
 
    .. index:: --name-mixed-case (gnatpp)
 
-   :switch:`--name-mixed-case`
-     Names are in mixed case
+   :switch:`--name-mixed-case, -nM`
+     Names are in mixed case.
 
    .. index:: --attribute-lower-case (gnatpp)
 
-   :switch:`--attribute-lower-case`
-     Attribute designators are lower case
+   :switch:`--attribute-lower-case, -aL`
+     Attribute designators are lower case.
 
    .. index:: --attribute-upper-case (gnatpp)
 
-   :switch:`--attribute-upper-case`
-     Attribute designators are upper case
+   :switch:`--attribute-upper-case, -aU`
+     Attribute designators are upper case.
 
    .. index:: --attribute-mixed-case (gnatpp)
 
-   :switch:`--attribute-mixed-case`
-     Attribute designators are mixed case (this is the default)
+   :switch:`--attribute-mixed-case, -aM`
+     Attribute designators are mixed case (this is the default).
 
    .. index:: --keyword-lower-case (gnatpp)
 
-   :switch:`--keyword-lower-case`
+   :switch:`--keyword-lower-case, -kL`
      Keywords (technically, these are known in Ada as *reserved words*) are
-     lower case (this is the default)
+     lower case (this is the default).
 
    .. index:: --keyword-upper-case (gnatpp)
 
-   :switch:`--keyword-upper-case`
-     Keywords are upper case
+   :switch:`--keyword-upper-case, -kU`
+     Keywords are upper case.
 
    .. index:: --enum-case-as-declared (gnatpp)
 
-   :switch:`--enum-case-as-declared`
-     Enumeration literal casing for defining occurrences are as they appear in the
-     source file. Overrides -n casing setting.
+   :switch:`--enum-case-as-declared, -neD`
+     Enumeration literal casing for defining occurrences are as they appear in
+     the source file. Overrides -n casing setting.
 
    .. index:: --enum-upper-case (gnatpp)
 
-   :switch:`--enum-upper-case`
+   :switch:`--enum-upper-case, -neU`
      Enumeration literals are in upper case. Overrides -n casing
      setting.
 
    .. index:: --enum-lower-case (gnatpp)
 
-   :switch:`--enum-lower-case`
+   :switch:`--enum-lower-case, -neL`
      Enumeration literals are in lower case. Overrides -n casing
      setting.
 
    .. index:: --enum-mixed-case (gnatpp)
 
-   :switch:`--enum-mixed-case`
+   :switch:`--enum-mixed-case, -neM`
      Enumeration literals are in mixed case. Overrides -n casing
      setting.
 
    .. index:: --type-case-as-declared (gnatpp)
 
-   :switch:`--type-case-as-declared`
+   :switch:`--type-case-as-declared, -ntD`
      Names introduced by type and subtype declarations are always
      cased as they appear in the declaration in the source file.
      Overrides -n casing setting.
 
    .. index:: --type-upper-case (gnatpp)
 
-   :switch:`--type-upper-case`
+   :switch:`--type-upper-case, -ntU`
      Names introduced by type and subtype declarations are always in
      upper case. Overrides -n casing setting.
 
    .. index:: --type-lower-case (gnatpp)
 
-   :switch:`--type-lower-case`
+   :switch:`--type-lower-case, -ntL`
      Names introduced by type and subtype declarations are always in
      lower case. Overrides -n casing setting.
 
    .. index:: --type-mixed-case (gnatpp)
 
-   :switch:`--type-mixed-case`
+   :switch:`--type-mixed-case, -ntM`
      Names introduced by type and subtype declarations are always in
      mixed case. Overrides -n casing setting.
 
    .. index:: --number-upper-case (gnatpp)
 
-   :switch:`--number-upper-case`
+   :switch:`--number-upper-case, -nnU`
      Names introduced by number declarations are always in
      upper case. Overrides -n casing setting.
 
    .. index:: --number-lower-case (gnatpp)
 
-   :switch:`--number-lower-case`
+   :switch:`--number-lower-case, -nnL`
      Names introduced by number declarations are always in
      lower case. Overrides -n casing setting.
 
    .. index:: --number-mixed-case (gnatpp)
 
-   :switch:`--number-mixed-case`
+   :switch:`--number-mixed-case, -nnM`
      Names introduced by number declarations are always in
      mixed case. Overrides -n casing setting.
 
    .. index:: --pragma-lower-case (gnatpp)
 
-   :switch:`--pragma-lower-case`
-     Pragma names are lower case
+   :switch:`--pragma-lower-case, -pL`
+     Pragma names are lower case.
 
    .. index:: --pragma-upper-case (gnatpp)
 
-   :switch:`--pragma-upper-case`
-     Pragma names are upper case
+   :switch:`--pragma-upper-case, -pU`
+     Pragma names are upper case.
 
    .. index:: --pragma-mixed-case (gnatpp)
 
-   :switch:`--pragma-mixed-case`
-     Pragma names are mixed case (this is the default)
+   :switch:`--pragma-mixed-case, -pM`
+     Pragma names are mixed case (this is the default).
+
+   .. index:: --constant-case-as-non-constant (gnatpp)
+
+   :switch:`--constant-case-as-non-constant, -cN`
+     Constant object declaration names have the same case as the name casing
+     (this is the default).
+
+   .. index:: --constant-case-as-declared (gnatpp)
 
+   :switch:`--constant-case-as-declared, -cD`
+     Constant object declaration names are as they appear in the source file.
+
+   .. index:: --constant-lower-case (gnatpp)
+
+   :switch:`--constant-lower-case, -cL`
+     Constant object declaration names are lower case.
+
+   .. index:: --constant-upper-case (gnatpp)
+
+   :switch:`--constan-upper-case, -cU`
+     Constant object declaration names are upper case.
+
+   .. index:: --constant-mixed-case (gnatpp)
+
+   :switch:`--constant-mixed-case, -cM`
+     Constant object declaration names are mixed case.
 
    .. index:: --syntax-only (gnatpp)
 
@@ -725,10 +801,9 @@ building specialized scripts.
      This means gnatpp will not be able to support any of the
      "as-declared" switches.
 
-
    .. index:: --dictionary (gnatpp)
 
-   :switch:`--dictionary={file}`
+   :switch:`--dictionary={file}, -D={file}`
      Use ``file`` as a *dictionary file* that defines
      the casing for a set of specified names,
      thereby overriding the effect on these names by
@@ -741,10 +816,9 @@ building specialized scripts.
      to define the casing for the Ada predefined names and
      the names declared in the GNAT libraries.
 
-
    .. index:: --dictionary=- (gnatpp)
 
-   :switch:`--dictionary=-`
+   :switch:`--dictionary=-, -D=-`
      Do not use the default dictionary file;
      instead, use the casing
      defined by a ``-n`` switch and any explicit
@@ -762,146 +836,6 @@ building specialized scripts.
    on their effect.
 
 
-   .. index:: -c (gnatpp)
-
-
-   :switch:`--comments-unchanged`
-     All comments remain unchanged.
-
-
-   :switch:`--comments-gnat-indentation`
-     GNAT-style comment line indentation.
-     This is the default.
-
-
-   :switch:`--comments-gnat-beginning`
-     GNAT-style comment beginning.
-
-
-   :switch:`--comments-fill`
-     Fill comment blocks.
-     The default is :switch:`--no-comments-fill`.
-
-
-   :switch:`--comments-special`
-     Keep unchanged special form comments.
-     The default is :switch:`--no-comments-special`.
-
-
-   .. index:: --comments-only (gnatpp)
-
-   :switch:`--comments-only`
-     Format just the comments.
-
-   .. index:: --no-end-id (gnatpp)
-
-
-   :switch:`--no-end-id`
-     Do not insert the name of a unit after ``end``; leave whatever comes
-     after ``end``, if anything, alone.
-
-   .. index:: --no-separate-is (gnatpp)
-
-
-   :switch:`--no-separate-is`
-     Do not place the keyword ``is`` on a separate line in a subprogram body in
-     case if the spec occupies more than one line.
-
-   .. index:: --no-separate-return (gnatpp)
-
-
-   :switch:`--no-separate-return`
-     In :switch:`--no-compact` mode, if a subprogram spec does not fit on
-     one line, try to place the ``return`` on the same line as the last
-     formal parameter.
-
-   .. index:: --separate-loop (gnatpp)
-
-
-   :switch:`--separate-loop`
-     Place the keyword ``loop`` in FOR and WHILE loop statements
-     on a separate line.
-
-   .. index:: --no-separate-then (gnatpp)
-
-
-   :switch:`--separate-then`
-     Place the keyword ``then`` in IF statements
-     on a separate line.
-
-   .. index:: --no-separate-loop (gnatpp)
-
-
-   :switch:`--no-separate-loop`
-     Do not place the keyword ``loop`` in FOR and WHILE loop statements
-     on a separate line. This option is
-     incompatible with the :switch:`--separate-loop` option.
-
-   .. index:: --no-separate-then (gnatpp)
-
-
-   :switch:`--no-separate-then`
-     Do not place the keyword ``then`` in IF statements
-     on a separate line. This option is
-     incompatible with the :switch:`--separate-then` option.
-
-   .. index:: --separate-loop-then (gnatpp)
-
-
-   :switch:`--separate-loop-then`
-     Equivalent to :switch:`--separate-loop` :switch:`--separate-then`.
-
-   .. index:: --no-separate-loop-then (gnatpp)
-
-
-   :switch:`--no-separate-loop-then`
-     Equivalent to :switch:`--no-separate-loop` :switch:`--no-separate-then`.
-
-   .. index:: --use-on-new-line (gnatpp)
-
-
-   :switch:`--use-on-new-line`
-     Start each USE clause in a context clause from a separate line.
-
-
-   .. index:: --insert-blank-lines (gnatpp)
-
-
-   :switch:`--insert-blank-lines`
-     Insert blank lines where appropriate (between bodies and other large
-     constructs).
-
-   .. index:: --preserve-blank-lines (gnatpp)
-
-
-   :switch:`--preserve-blank-lines`
-     Preserve blank lines in the input. By default, gnatpp will squeeze
-     multiple blank lines down to one.
-
-   .. index:: --preserve-line-breaks (gnatpp)
-
-   :switch:`--preserve-line-breaks`
-     Preserve line breaks in the input, to the extent possible.
-     By default, line breaks are also inserted at appropriate
-     places.
-
-   .. index:: --source-line-breaks (gnatpp)
-
-   :switch:`--source-line-breaks`
-     Keep the line breaks from the source; do not insert or delete any
-     line breaks.
-
-   .. index:: --spaces-only (gnatpp)
-
-   :switch:`--spaces-only`
-     Disable all formatting except for inserting and removing spaces.
-     This implies --source-line-breaks.
-
-   The ``--comments`` switches are compatible with one another, except
-   that the ``--comments-unchanged`` switch disables all other comment
-   formatting switches.
-
-
    .. _General_Text_Layout_Control:
 
    General Text Layout Control
@@ -911,19 +845,19 @@ building specialized scripts.
 
    .. index:: --max-line-length (gnatpp)
 
-   :switch:`--max-line-length={nnn}`
+   :switch:`--max-line-length={nnn}, -M={nnn}`
      Maximum line length, ``nnn`` from 32...256, the default value is 79
 
 
    .. index:: --indentation (gnatpp)
 
-   :switch:`--indentation={nnn}`
+   :switch:`--indentation={nnn}, -i={nnn}`
      Indentation level, ``nnn`` from 1...9, the default value is 3
 
 
    .. index:: --indent-continuation (gnatpp)
 
-   :switch:`--indent-continuation={nnn}`
+   :switch:`--indent-continuation={nnn}, -cl={nnn}`
      Indentation level for continuation lines (relative to the line being
      continued), ``nnn`` from 1...9.
      The default
@@ -956,63 +890,6 @@ building specialized scripts.
      example, with ``--based-grouping=4``, ``16#0001FFFE#`` will be
      changed to ``16#0001_FFFE#``.
 
-
-   .. index:: --split-line-before-record (gnatpp)
-
-   :switch:`--split-line-before-record`
-     Split the line just before ``record`` in a record type declaration.
-
-
-   .. index:: --indent-named-statements (gnatpp)
-
-   :switch:`--indent-named-statements`
-     Named block and loop statements are indented with respect to
-     the name.
-
-
-   .. index:: --split-line-before-op (gnatpp)
-
-   :switch:`--split-line-before-op`
-     If it is necessary to split a line at a binary operator, by default
-     the line is split after the operator. With this option, it is split
-     before the operator.
-
-
-   .. index:: --RM-style-spacing (gnatpp)
-
-   :switch:`--RM-style-spacing`
-     Do not insert an extra blank before various occurrences of
-     '(' and ':'. Alignment is off by default in this mode;
-     use :switch:`--alignment` to turn it on.
-
-
-   .. index:: --compact (gnatpp)
-   .. index:: --no-compact (gnatpp)
-
-   :switch:`--compact`
-     This is the default. In calls and similar, this packs as many
-     subexpressions on the same line as possible. Example:
-
-     .. code-block:: ada
-
-        Some_Procedure
-          (Short_One, Another_Short_One,
-           A_Very_Very_Very_Very_Very_Very_Very_Very_Long_One);
-
-   :switch:`--no-compact`
-     Turns off --compact mode. In calls and similar, if it is necessary
-     to split a line between two subexpressions (because otherwise the
-     construct would exceed --max-line-length), then all such subexpressions
-     are placed on separate lines. Example:
-
-     .. code-block:: ada
-
-        Some_Procedure
-          (Short_One,
-           Another_Short_One,
-           A_Very_Very_Very_Very_Very_Very_Very_Very_Long_One);
-
-
    .. index:: --call-threshold (gnatpp)
 
    :switch:`--call-threshold={nnn}`
@@ -1021,40 +898,14 @@ building specialized scripts.
      a new line. If ``nnn`` is 0, no check for the number of associations
      is made; this is the default.
 
-
    .. index:: --par-threshold (gnatpp)
 
    :switch:`--par-threshold={nnn}`
      If the number of parameter specifications is greater than ``nnn``
      (or equal to ``nnn`` in case of a function), start each specification from
-     a new line. If ``nnn`` is 0, and :switch:`--no-separate-is` was not specified, then
-     the ``is`` is placed on a separate line. This feature is disabled by default.
-
-   .. index:: --vertical-enum-types (gnatpp)
-
-   :switch:`--vertical-enum-types`
-     Format enumeration type declarations "vertically", e.g. each
-     enumeration literal goes on a separate line.
-
-   .. index:: --vertical-array-types (gnatpp)
-
-   :switch:`--vertical-array-types`
-     Format array type declarations "vertically", e.g. for
-     multidimensional arrays, each index_subtype_definition or
-     discrete_subtype_definition goes on a separate line.
-
-   .. index:: --vertical-named-aggregates (gnatpp)
-
-   :switch:`--vertical-named-aggregates`
-     Format aggregates "vertically" if named notation is used for all
-     component_associations, e.g. each component_association
-     goes on a separate line.
-
-   .. index:: --vertical-case-alternatives (gnatpp)
-
-   :switch:`--vertical-case-alternatives`
-     Format case statements, case expressions, and variant parts with
-     additional line breaks.
+     a new line. If ``nnn`` is 0, and :switch:`--no-separate-is` was not
+     specified, then the ``is`` is placed on a separate line. This feature is
+     disabled by default.
 
 
    .. _Setting_the_Source_Search_Path:
@@ -1090,7 +941,7 @@ building specialized scripts.
 
    .. index:: --replace (gnatpp)
 
-   :switch:`--replace`
+   :switch:`--replace, -rnb`
      This is the default.
      Replace the input source file with the reformatted output without
      creating any backup copy of the input source.
@@ -1108,13 +959,13 @@ building specialized scripts.
 
    .. index:: --pipe (gnatpp)
 
-   :switch:`--pipe`
+   :switch:`--pipe, -pipe`
      Send the output to ``Standard_Output``
 
 
    .. index:: --output (gnatpp)
 
-   :switch:`--output={output_file}`
+   :switch:`--output={output_file}, -o={output_file}`
      Write the output into ``output_file``.
      If ``output_file`` already exists, ``gnatpp`` terminates without
      reading or processing the input file.
@@ -1122,24 +973,24 @@ building specialized scripts.
 
    .. index:: --output-force (gnatpp)
 
-   :switch:`--output-force={output_file}`
+   :switch:`--output-force={output_file}, -of={output_file}`
      Write the output into ``output_file``, overwriting the existing file
      (if one is present).
 
 
    .. index:: --replace-backup (gnatpp)
 
-   :switch:`--replace-backup`
+   :switch:`--replace-backup, -r`
      Replace the input source file with the reformatted output, and copy the
-     original input source into the file whose name is obtained by appending the
-     :file:`.npp` suffix to the name of the input file.
+     original input source into the file whose name is obtained by appending
+     the :file:`.npp` suffix to the name of the input file.
      If a file with this name already exists, ``gnatpp`` terminates without
      reading or processing the input file.
 
 
    .. index:: --replace-force-backup (gnatpp)
 
-   :switch:`--replace-force-backup`
+   :switch:`--replace-force-backup, -rf`
      Like ``--replace-backup`` except that if the file with the specified name
      already exists, it is overwritten.
 
@@ -1159,7 +1010,7 @@ building specialized scripts.
 
    .. index:: --wide-character-encoding (gnatpp)
 
-   :switch:`--wide-character-encoding={e}`
+   :switch:`--wide-character-encoding={e}, -W={e}`
      Specify the wide character encoding method for the input and output
      files. ``e`` is one of the following:
 
@@ -1198,8 +1049,8 @@ building specialized scripts.
 
    :switch:`-P {file}`
      Indicates the name of the project file that describes the set of sources
-     to be processed. The exact set of argument sources depends on other options
-     specified; see below.
+     to be processed. The exact set of argument sources depends on other
+     options specified; see below.
 
 
    .. index:: -U  (gnatpp)
@@ -1207,9 +1058,8 @@ building specialized scripts.
    :switch:`-U`
      If a project file is specified and no argument source is explicitly
      specified (either directly or by means of ``--files`` option), process
-     all the units of the closure of the argument project. Otherwise this option
-     has no effect.
-
+     all the units of the closure of the argument project. Otherwise this
+     option has no effect.
 
    :switch:`-U {main_unit}`
      If a project file is specified and no argument source is explicitly
@@ -1255,13 +1105,13 @@ building specialized scripts.
    .. index:: --pp-on  (gnatpp)
 
    :switch:`--pp-on={xxx}`
-     Use :switch:`--xxx` as the command to turn pretty printing back on, instead
-     of the default ``--!pp on``.
+     Use :switch:`--xxx` as the command to turn pretty printing back on,
+     instead of the default ``--!pp on``.
 
 
    .. index:: --files (gnatpp)
 
-   :switch:`--files={filename}`
+   :switch:`--files={filename}, -files={filename}`
      Take as arguments the files listed in text file ``file``.
      Text file ``file`` may contain empty lines that are ignored.
      Each nonempty line should contain the name of an existing file.
@@ -1274,9 +1124,10 @@ building specialized scripts.
      Do not process the sources listed in a specified file. This option cannot
      be used in incremental mode.
 
+
    .. index:: --jobs (gnatpp)
 
-   :switch:`--jobs={n}`
+   :switch:`--jobs={n}, -j={n}`
      With ``--incremental``, use *n* ``gnatpp`` processes to perform
      pretty printing in parallel. If *n* is 0, then the maximum number
      processes is the number of core processors on the platform.
@@ -1284,13 +1135,13 @@ building specialized scripts.
 
    .. index:: --verbose (gnatpp)
 
-   :switch:`--verbose`
+   :switch:`--verbose, -v`
      Verbose mode
 
 
    .. index:: --quiet (gnatpp)
 
-   :switch:`--quiet`
+   :switch:`--quiet, -q`
      Quiet mode
 
    If a project file is specified and no argument source is explicitly
@@ -1304,9 +1155,9 @@ building specialized scripts.
    Formatting Rules
    ----------------
 
-   The following subsections show how ``gnatpp`` treats white space,
-   comments, program layout, and name casing.
-   They provide detailed descriptions of the switches shown above.
+   The following subsections show how ``gnatpp`` treats, comments, program
+   layout, name casing and how to disable ``gnatpp`` in source code regions.
+   They provide more details of the switches shown above.
 
 
    .. _Disabling_Pretty_Printing:
@@ -1353,32 +1204,13 @@ building specialized scripts.
    included in the argument to these switches.
 
 
-   .. _White_Space_and_Empty_Lines:
-
-   White Space and Empty Lines
-   ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-   ``gnatpp`` does not have an option to control space characters.
-   It will add or remove spaces according to the style illustrated by the
-   examples in the :title:`Ada Reference Manual`.
-   The output file will contain no lines with trailing white space.
-
-   By default, a sequence of one or more blank lines in the input is
-   converted to a single blank line in the output; multiple blank lines
-   are squeezed down to one.
-   The ``--preserve-blank-lines`` option
-   turns off the squeezing; each blank line in the input is copied
-   to the output.
-   The ``--insert-blank-lines`` option
-   causes additional blank lines to be inserted if not already
-   present in the input (e.g. between bodies).
-
-
    .. _Formatting_Comments:
 
    Formatting Comments
    ^^^^^^^^^^^^^^^^^^^
 
+   Only ``--layout=compact`` and ``--layout=tall`` format comments.
+
    Comments in Ada code are of two kinds:
 
    * a *whole-line comment*, which appears by itself (possibly preceded by
@@ -1390,38 +1222,21 @@ building specialized scripts.
    A whole-line comment is indented according to the surrounding code,
    with some exceptions. Comments that start in column 1 are kept
    there. If possible, comments are not moved so far to the right that
-   the maximum line length is exceeded. The ``--comments-unchanged``
-   option turns off comment formatting. Special-form comments such as
+   the maximum line length is exceeded. Special-form comments such as
    SPARK-style ``--#...`` are left alone.
 
    For an end-of-line comment, ``gnatpp`` tries to leave the same
    number of spaces between the end of the preceding Ada code and the
    beginning of the comment as appear in the original source.
 
-   The ``--comments-gnat-beginning`` switch (GNAT style comment
-   beginning) has the following effect:
-
-     * For each whole-line comment that does not end with two hyphens,
-       ``gnatpp`` inserts spaces if necessary after the starting two
-       hyphens to ensure that there are at least two spaces between
-       these hyphens and the first non-blank character of the comment.
+   For each whole-line comment that does not end with two hyphens or that are
+   not special-form comments, ``gnatpp`` inserts spaces if necessary after the
+   starting two hyphens to ensure that there are at least two spaces between
+   these hyphens and the first non-blank character of the comment.
 
-   The ``--comments-fill`` switch specifies that whole-line comments
-   that form a paragraph will be filled in typical word processor style
-   (that is, moving words between lines to make the lines other than the
-   last similar in length ).
-
-   The ``--comments-only`` switch specifies that only the comments are
-   formatted; the rest of the program text is left alone. The comments
-   are formatted according to the ``--comments-gnat-beginning`` and
-   ``--comments-fill`` switches; other formatting switches are ignored. For
-   example, ``--comments-only --comments-fill`` means to fill comment
-   paragraphs, and do nothing else. Likewise, ``--comments-only
-   --comments-gnat-beginning`` ensures comments start with at least two
-   spaces after ``--``, and ``--comments-only --comments-gnat-beginning
-   --comments-fill`` does both. If ``--comments-only`` is given without
-   ``--comments-gnat-beginning`` or ``--comments-fill``, then gnatpp
-   doesn't format anything.
+   With ``--layout=compact``, whole-line comments that form a paragraph will be
+   filled in typical word processor style (that is, moving words between lines
+   to make the lines other than the last similar in length).
 
 
    .. _Name_Casing:
@@ -1643,188 +1458,192 @@ building specialized scripts.
    Legacy Switches
    ^^^^^^^^^^^^^^^
 
-   Some switches have a short form, mostly for legacy reasons,
-   as shown below.
-
-   .. index:: -n (gnatpp)
-
-   :switch:`-nD`
-     :switch:`--name-case-as-declared`
-
-   :switch:`-nU`
-     :switch:`--name-upper-case`
-
-   :switch:`-nL`
-     :switch:`--name-lower-case`
-
-   :switch:`-nM`
-     :switch:`--name-mixed-case`
-
-   .. index:: -a (gnatpp)
-
-   :switch:`-aL`
-     :switch:`--attribute-lower-case`
-
-   :switch:`-aU`
-     :switch:`--attribute-upper-case`
+   .. index:: --alignment (gnatpp)
 
-   :switch:`-aM`
-     :switch:`--attribute-mixed-case`
+   :switch:`--alignment, --no-alignment`
+      Programs can be easier to read if certain constructs are vertically
+      aligned.
 
-   .. index:: -k (gnatpp)
+        * ``:`` in declarations,
+        * ``:=`` in initializations in declarations,
+        * ``:=`` in assignment statements,
+        * ``=>`` in associations, and
+        * ``at`` keywords in the component clauses in record representation
+          clauses.
 
-   :switch:`-kL`
-     :switch:`--keyword-lower-case`
+   .. index:: --align-modes (gnatpp)
 
-   :switch:`-kU`
-     :switch:`--keyword-upper-case`
+   :switch:`--align-modes, --no-align-modes`
 
-   .. index:: -ne (gnatpp)
+      Line up ``in`` and ``out`` in parameter specifications.
 
-   :switch:`-neD`
-     :switch:`--enum-case-as-declared`
+   .. index:: --compact (gnatpp)
 
-   :switch:`-neU`
-     :switch:`--enum-upper-case`
+   :switch:`--compact, --no-compact`
+     In calls and similar, ``--compact`` packs as many
+     subexpressions on the same line as possible. Example:
 
-   :switch:`-neL`
-     :switch:`--enum-lower-case`
+     .. code-block:: ada
 
-   :switch:`-neM`
-     :switch:`--enum-mixed-case`
+        Some_Procedure
+          (Short_One, Another_Short_One,
+           A_Very_Very_Very_Very_Very_Very_Very_Very_Long_One);
 
-   .. index:: -nt (gnatpp)
+     On the contrary, with ``--no-compact``, in calls and similar, if it is
+     necessary to split a line between two subexpressions (because otherwise
+     the construct would exceed --max-line-length), then all such
+     subexpressions are placed on separate lines. Example:
 
-   :switch:`-ntD`
-     :switch:`--type-case-as-declared`
+     .. code-block:: ada
 
-   :switch:`-ntU`
-     :switch:`--type-upper-case`
+        Some_Procedure
+          (Short_One,
+           Another_Short_One,
+           A_Very_Very_Very_Very_Very_Very_Very_Very_Long_One);
 
-   :switch:`-ntL`
-     :switch:`--type-lower-case`
+   .. index:: --end-id (gnatpp)
 
-   :switch:`-ntM`
-     :switch:`--type-mixed-case`
+   :switch:`--end-id, --no-end-id`
+     Insert the name of a unit after ``end``. Otherwise, leave whatever comes
+     after ``end``, if anything, alone.
 
-   :switch:`-nnU`
-     :switch:`--number-upper-case`
+   .. index:: --separate-is (gnatpp)
 
-   :switch:`-nnL`
-     :switch:`--number-lower-case`
+   :switch:`--separate-is, --no-separate-is`
+     Place the keyword ``is`` on a separate line in a subprogram body in
+     case if the spec occupies more than one line.
 
-   :switch:`-nnM`
-     :switch:`--number-mixed-case`
+   .. index:: --separate-return (gnatpp)
 
-   .. index:: -p (gnatpp)
+   :switch:`--separate-return, --no-separate-return`
+     If a subprogram spec does not fit on one line, place the ``return`` on
+     a separate line. Otherwise try to place it in the same line as the last
+     parameter specification.
 
-   :switch:`-pL`
-     :switch:`--pragma-lower-case`
+   .. index:: --separate-loop (gnatpp)
 
-   :switch:`-pU`
-     :switch:`--pragma-upper-case`
+   :switch:`--separate-loop, --no-separate-loop`
+     Place the keyword ``loop`` in FOR and WHILE loop statements
+     on a separate line.
 
-   :switch:`-pM`
-     :switch:`--pragma-mixed-case`
 
-   .. index:: -D (gnatpp)
+   .. index:: --separate-then (gnatpp)
 
-   :switch:`-D{file}`
-     :switch:`--dictionary={file}`
+   :switch:`--separate-then, --no-separate-then`
+     Place the keyword ``then`` in IF statements
+     on a separate line.
 
-   .. index:: -D- (gnatpp)
+   .. index:: --separate-loop-then (gnatpp)
 
-   :switch:`-D-`
-     :switch:`--dictionary=-`
+   :switch:`--separate-loop-then, --no-separate-loop-then`
+     Equivalent to :switch:`--separate-loop` :switch:`--separate-then`.
 
-   .. index:: -c (gnatpp)
+   .. index:: --split-line-before-record (gnatpp)
 
-   :switch:`-c0`
-     :switch:`--comments-unchanged`
+   :switch:`--split-line-before-record, --no-split-line-before-record`
+     Split the line just before ``record`` in a record type declaration.
 
-   :switch:`-c1`
-     :switch:`--comments-gnat-indentation`
+   .. index:: --indent-named-statements (gnatpp)
 
-   :switch:`-c3`
-     :switch:`--comments-gnat-beginning`
+   :switch:`--indent-named-statements, --no-indent-named-statements`
+     Named block and loop statements are indented with respect to
+     the name.
 
-   :switch:`-c4`
-     :switch:`--comments-fill`
+   .. index:: --split-line-before-op (gnatpp)
 
-   :switch:`-c5`
-     :switch:`--comments-special`
+   :switch:`--split-line-before-op, --no-split-line-before-op`
+     If it is necessary to split a line at a binary operator, by default
+     the line is split after the operator. With this option, it is split
+     before the operator.
 
-   .. index:: -M (gnatpp)
+   .. index:: --use-on-new-line (gnatpp)
 
-   :switch:`-M{nnn}`
-     :switch:`--max-line-length={nnn}`
+   :switch:`--use-on-new-line, --no-use-one-new-line`
+     Start each USE clause in a context clause from a separate line.
 
-   .. index:: -i (gnatpp)
+   .. index:: --vertical-enum-types (gnatpp)
 
-   :switch:`-i{nnn}`
-     :switch:`--indentation={nnn}`
+   :switch:`--vertical-enum-types, --no-vertical-enum-types`
+     Format enumeration type declarations "vertically", e.g. each
+     enumeration literal goes on a separate line.
 
-   .. index:: -cl (gnatpp)
+   .. index:: --vertical-array-types (gnatpp)
 
-   :switch:`-cl{nnn}`
-     :switch:`--indent-continuation={nnn}`
+   :switch:`--vertical-array-types, --no-vertical-array-types`
+     Format array type declarations "vertically", e.g. for
+     multidimensional arrays, each index_subtype_definition or
+     discrete_subtype_definition goes on a separate line.
 
-   .. index:: -pipe (gnatpp)
+   .. index:: --vertical-named-aggregates (gnatpp)
 
-   :switch:`-pipe`
-     :switch:`--pipe`
+   :switch:`--vertical-named-aggregates, --no-vertical-named-aggregates`
+     Format aggregates "vertically" if named notation is used for all
+     component_associations, e.g. each component_association
+     goes on a separate line.
 
-   .. index:: -o (gnatpp)
+   .. index:: --vertical-case-alternatives (gnatpp)
 
-   :switch:`-o {output-file}`
-     :switch:`--output={output-file}`
+   :switch:`--vertical-case-alternatives, --no-vertical-case-alternatives`
+     Format case statements, case expressions, and variant parts with
+     additional line breaks.
 
-   .. index:: -of (gnatpp)
+   .. index:: --RM-style-spacing (gnatpp)
 
-   :switch:`-of {output-file}`
-     :switch:`--output-force={output-file}`
+   :switch:`--RM-style-spacing`
+     Do not insert an extra blank before various occurrences of
+     '(' and ':'. Alignment is off by default in this mode;
+     use :switch:`--alignment` to turn it on.
 
-   .. index:: -r (gnatpp)
+   .. index:: --insert-blank-lines (gnatpp)
 
-   :switch:`-rnb`
-     :switch:`--replace`
+   :switch:`--insert-blank-lines, --no-insert-blank-lines`
+     Insert blank lines where appropriate (between bodies and other large
+     constructs).
 
-   :switch:`-r`
-     :switch:`--replace-backup`
+   .. index:: --preserve-blank-lines (gnatpp)
 
-   .. index:: -rf (gnatpp)
+   :switch:`--preserve-blank-lines, --no-preserve-blank-lines`
+     Preserve blank lines in the input. By default, gnatpp will squeeze
+     multiple blank lines down to one.
 
-   :switch:`-rf`
-     :switch:`--replace-force-backup`
+   .. index:: --preserve-line-breaks (gnatpp)
 
-   .. index:: -rnb (gnatpp)
+   :switch:`--preserve-line-breaks, --no-preserve-line-breaks`
+     Preserve line breaks in the input, to the extent possible.
+     By default, line breaks are also inserted at appropriate
+     places.
 
-   .. index:: --eol (gnatpp)
+   .. index:: --source-line-breaks (gnatpp)
 
-   .. index:: -W (gnatpp)
+   :switch:`--source-line-breaks, --no-source-line-breaks`
+     Keep the line breaks from the source; do not insert or delete any
+     line breaks.
 
-   :switch:`-W{e}`
-     :switch:`--wide-character-encoding={e}`
+   .. index:: --spaces-only (gnatpp)
 
-   .. index:: -files (gnatpp)
+   :switch:`--spaces-only, --no-spaces-only`
+     Disable all formatting except for inserting and removing spaces.
+     This implies --source-line-breaks.
 
-   :switch:`-files {filename}`
-     :switch:`--files={filename}`
+   .. index:: -c (gnatpp)
 
-   .. index:: -j (gnatpp)
+   :switch:`--comments-unchanged, -c0`
+     All comments remain unchanged.
 
-   :switch:`-j{n}`
-     :switch:`--jobs={n}`
+   :switch:`--comments-gnat-indentation, -c1`
+     GNAT-style comment line indentation.
 
-   .. index:: -v (gnatpp)
+   :switch:`--comments-gnat-beginning, -c3`
+     GNAT-style comment beginning.
 
-   :switch:`-v`
-     :switch:`--verbose`
+   :switch:`--comments-fill, -c4`
+     Fill comment blocks.
 
-   .. index:: -q (gnatpp)
+   :switch:`--comments-special, -c5`
+     Keep unchanged special form comments.
 
-   :switch:`-q`
-     :switch:`--quiet`
+   :switch:`--comments-only`
+     Format just the comments.
 
 
 .. only:: PRO or GPL