[Ada] Update gnatpp documentation after engine change

2018-01-11  Bob Duff  <duff@adacore.com>

gcc/ada/

	* doc/gnat_ugn/gnat_utility_programs.rst: Rewrite gnatpp documentation
	to match what the Libadalang-based version does.
	* doc/gnat_ugn/about_this_guide.rst: Update reference.

From-SVN: r256500

3 files changed, 447 insertions, 249 deletions

diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog
index 9915a7a..4a92bf9 100644
--- a/gcc/ada/ChangeLog
+++ b/gcc/ada/ChangeLog
@@ -1,3 +1,9 @@
+2018-01-11  Bob Duff  <duff@adacore.com>
+
+	* doc/gnat_ugn/gnat_utility_programs.rst: Rewrite gnatpp documentation
+	to match what the Libadalang-based version does.
+	* doc/gnat_ugn/about_this_guide.rst: Update reference.
+
 2018-01-11  Hristian Kirtchev  <kirtchev@adacore.com>
 
 	* sem_res.adb (Uses_SS): A controlled type requires the secondary stack
diff --git a/gcc/ada/doc/gnat_ugn/about_this_guide.rst b/gcc/ada/doc/gnat_ugn/about_this_guide.rst
index 241e998..e303721 100644
--- a/gcc/ada/doc/gnat_ugn/about_this_guide.rst
+++ b/gcc/ada/doc/gnat_ugn/about_this_guide.rst
@@ -146,7 +146,7 @@ the new document structure.
     - :ref:`The_Ada-to-XML_Converter_gnat2xml`
     - :ref:`The_Coding_Standard_Verifier_gnatcheck`
     - :ref:`The_GNAT_Metrics_Tool_gnatmetric`
-    - :ref:`The_GNAT_Pretty-Printer_gnatpp`
+    - :ref:`The_GNAT_Pretty_Printer_gnatpp`
     - :ref:`The_Body_Stub_Generator_gnatstub`
     - :ref:`The_Unit_Test_Generator_gnattest`
 
diff --git a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
index 95a35f3..74dbe4e 100644
--- a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
+++ b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
@@ -19,7 +19,7 @@ This chapter describes a number of utility programs:
   * :ref:`The_Ada-to-XML_Converter_gnat2xml`
   * :ref:`The_Coding_Standard_Verifier_gnatcheck`
   * :ref:`The_GNAT_Metrics_Tool_gnatmetric`
-  * :ref:`The_GNAT_Pretty-Printer_gnatpp`
+  * :ref:`The_GNAT_Pretty_Printer_gnatpp`
   * :ref:`The_Body_Stub_Generator_gnatstub`
   * :ref:`The_Unit_Test_Generator_gnattest`
   * :ref:`The_Backtrace_Symbolizer_gnatsymbolize`
@@ -2798,42 +2798,36 @@ Alternatively, you may run the script using the following command line:
 
 .. only:: PRO or GPL
 
-   .. _The_GNAT_Pretty-Printer_gnatpp:
+   .. _The_GNAT_Pretty_Printer_gnatpp:
 
-   The GNAT Pretty-Printer ``gnatpp``
+   The GNAT Pretty Printer ``gnatpp``
    ==================================
 
    .. index:: ! gnatpp
-   .. index:: Pretty-Printer
+   .. index:: pretty printer
 
-   The ``gnatpp`` tool is an ASIS-based utility
-   for source reformatting / pretty-printing.
-   It takes an Ada source file as input and generates a reformatted
-   version as output.
-   You can specify various style directives via switches; e.g.,
-   identifier case conventions, rules of indentation, and comment layout.
+   This documentation is for the new libadalang-based version
+   of ``gnatpp``, which replaces the ASIS-based version.
+
+   The ``gnatpp`` tool is a utility for source reformatting / pretty
+   printing.  It takes an Ada source file as input and generates a
+   reformatted version as output.  You can specify various style
+   directives via switches; e.g., identifier case conventions, rules of
+   indentation, and comment layout.
 
    ``gnatpp`` is a project-aware tool
    (see :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
    the project-related switches).  The project file package that can specify
    ``gnatpp`` switches is named ``Pretty_Printer``.
 
-   To produce a reformatted file, ``gnatpp`` invokes the Ada
-   compiler and generates and uses the ASIS tree for the input source;
-   thus the input must be legal Ada code, and the tool should have all the
-   information needed to compile the input source. To provide this information,
-   you may specify as a tool parameter the project file the input source belongs to.
-   Another possibility is to specify the source search
-   path and needed configuration files in ``-cargs`` section of ``gnatpp``
-   call, see the description of the ``gnatpp`` switches below.
-
-   ``gnatpp`` cannot process sources that contain preprocessing directives.
+   ``gnatpp`` cannot process sources that contain preprocessing
+   directives.
 
    The ``gnatpp`` command has the form
 
      ::
 
-        $ gnatpp [ switches ] filename [ -cargs gcc_switches ]
+        $ gnatpp [ switches ] filename
 
    where
 
@@ -2841,16 +2835,10 @@ Alternatively, you may run the script using the following command line:
      the formatting rules, the source search path, and the destination for the
      output source file
 
-   * ``filename`` is the name (including the extension) 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
-
-   * ``gcc_switches`` is a list of switches for
-     ``gcc``. They will be passed on to all compiler invocations made by
-     ``gnatpp`` to generate the ASIS trees. Here you can provide
-     ``-I`` switches to form the source search path,
-     use the ``-gnatec`` switch to set the configuration file, etc.
+   * ``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
 
 
    .. _Switches_for_gnatpp:
@@ -2892,15 +2880,15 @@ Alternatively, you may run the script using the following command line:
      * ``at`` keywords in the component clauses in record representation clauses.
 
 
-   .. index:: -A0 (gnatpp)
-   .. index:: -A1 (gnatpp)
+   .. index:: --no-alignment (gnatpp)
+   .. index:: --alignment (gnatpp)
 
 
-   :switch:`-A0`
+   :switch:`--no-alignment`
      Set alignment to OFF
 
 
-   :switch:`-A1`
+   :switch:`--alignment`
      Set alignment to ON
 
    .. _Casing_Control:
@@ -2922,144 +2910,158 @@ Alternatively, you may run the script using the following command line:
    following an underscore, are converted to their uppercase forms;
    all the other letters are converted to their lowercase forms.
 
-   .. index:: -a (gnatpp)
+   (Note: the casing switches are not yet fully supported in the
+   libadalang-based version of gnatpp.)
 
+   .. index:: --name-case-as-declared (gnatpp)
 
-   :switch:`-aL`
-     Attribute designators are lower case
-
-
-   :switch:`-aU`
-     Attribute designators are upper case
-
+   :switch:`--name-case-as-declared`
+     Name casing for defining occurrences are as they appear in the source file
+     (this is the default)
 
-   :switch:`-aM`
-     Attribute designators are mixed case (this is the default)
+   .. index:: --name-upper-case (gnatpp)
 
-   .. index:: -k (gnatpp)
+   :switch:`--name-upper-case`
+     Names are in upper case
 
+   .. index:: --name-lower-case (gnatpp)
 
-   :switch:`-kL`
-     Keywords (technically, these are known in Ada as *reserved words*) are
-     lower case (this is the default)
+   :switch:`--name-lower-case`
+     Names are in lower case
 
+   .. index:: --name-mixed-case (gnatpp)
 
-   :switch:`-kU`
-     Keywords are upper case
+   :switch:`--name-mixed-case`
+     Names are in mixed case
 
-   .. index:: -n (gnatpp)
+   .. index:: --attribute-lower-case (gnatpp)
 
+   :switch:`--attribute-lower-case`
+     Attribute designators are lower case
 
-   :switch:`-nD`
-     Name casing for defining occurrences are as they appear in the source file
-     (this is the default)
+   .. index:: --attribute-upper-case (gnatpp)
 
+   :switch:`--attribute-upper-case`
+     Attribute designators are upper case
 
-   :switch:`-nU`
-     Names are in upper case
+   .. index:: --attribute-mixed-case (gnatpp)
 
+   :switch:`--attribute-mixed-case`
+     Attribute designators are mixed case (this is the default)
 
-   :switch:`-nL`
-     Names are in lower case
+   .. index:: --keyword-lower-case (gnatpp)
 
+   :switch:`--keyword-lower-case`
+     Keywords (technically, these are known in Ada as *reserved words*) are
+     lower case (this is the default)
 
-   :switch:`-nM`
-     Names are in mixed case
+   .. index:: --keyword-upper-case (gnatpp)
 
-   .. index:: -ne (gnatpp)
+   :switch:`--keyword-upper-case`
+     Keywords are upper case
 
+   .. index:: --enum-case-as-declared (gnatpp)
 
-   :switch:`-neD`
+   :switch:`--enum-case-as-declared`
      Enumeration literal casing for defining occurrences are as they appear in the
      source file. Overrides -n casing setting.
 
+   .. index:: --enum-upper-case (gnatpp)
 
-   :switch:`-neU`
+   :switch:`--enum-upper-case`
      Enumeration literals are in upper case.  Overrides -n casing
      setting.
 
+   .. index:: --enum-lower-case (gnatpp)
 
-   :switch:`-neL`
+   :switch:`--enum-lower-case`
      Enumeration literals are in lower case. Overrides -n casing
      setting.
 
+   .. index:: --enum-mixed-case (gnatpp)
 
-   :switch:`-neM`
+   :switch:`--enum-mixed-case`
      Enumeration literals are in mixed case. Overrides -n casing
      setting.
 
-   .. index:: -nt (gnatpp)
-
+   .. index:: --type-case-as-declared (gnatpp)
 
-   :switch:`-ntD`
+   :switch:`--type-case-as-declared`
      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:`-ntU`
+   :switch:`--type-upper-case`
      Names introduced by type and subtype declarations are always in
      upper case. Overrides -n casing setting.
 
+   .. index:: --type-lower-case (gnatpp)
 
-   :switch:`-ntL`
+   :switch:`--type-lower-case`
      Names introduced by type and subtype declarations are always in
      lower case. Overrides -n casing setting.
 
+   .. index:: --type-mixed-case (gnatpp)
 
-   :switch:`-ntM`
+   :switch:`--type-mixed-case`
      Names introduced by type and subtype declarations are always in
      mixed case. Overrides -n casing setting.
 
+   .. index:: --number-upper-case (gnatpp)
 
-   :switch:`-nnU`
+   :switch:`--number-upper-case`
      Names introduced by number declarations are always in
      upper case. Overrides -n casing setting.
 
+   .. index:: --number-lower-case (gnatpp)
 
-   :switch:`-nnL`
+   :switch:`--number-lower-case`
      Names introduced by number declarations are always in
      lower case. Overrides -n casing setting.
 
+   .. index:: --number-mixed-case (gnatpp)
 
-   :switch:`-nnM`
+   :switch:`--number-mixed-case`
      Names introduced by number declarations are always in
      mixed case. Overrides -n casing setting.
 
-   .. index:: -p (gnatpp)
-
+   .. index:: --pragma-lower-case (gnatpp)
 
-   :switch:`-pL`
+   :switch:`--pragma-lower-case`
      Pragma names are lower case
 
+   .. index:: --pragma-upper-case (gnatpp)
 
-   :switch:`-pU`
+   :switch:`--pragma-upper-case`
      Pragma names are upper case
 
+   .. index:: --pragma-mixed-case (gnatpp)
 
-   :switch:`-pM`
+   :switch:`--pragma-mixed-case`
      Pragma names are mixed case (this is the default)
 
 
-   .. index:: -D (gnatpp)
+   .. index:: --dictionary (gnatpp)
 
-   :switch:`-D{file}`
+   :switch:`--dictionary={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
      any explicit or implicit
      -n switch.
      To supply more than one dictionary file,
-     use several ``-D`` switches.
+     use several ``--dictionary`` switches.
 
      ``gnatpp`` implicitly uses a *default dictionary file*
      to define the casing for the Ada predefined names and
      the names declared in the GNAT libraries.
 
 
-   .. index:: -D- (gnatpp)
+   .. index:: --dictionary=- (gnatpp)
 
-   :switch:`-D-`
+   :switch:`--dictionary=-`
      Do not use the default dictionary file;
      instead, use the casing
      defined by a ``-n`` switch and any explicit
@@ -3068,8 +3070,8 @@ Alternatively, you may run the script using the following command line:
    The structure of a dictionary file, and details on the conventions
    used in the default dictionary file, are defined in :ref:`Name_Casing`.
 
-   The :switch:`-D-` and
-   :switch:`-D{file}` switches are mutually
+   The :switch:`--dictionary=-` and
+   :switch:`--dictionary={file}` switches are mutually
    compatible.
 
    This group of ``gnatpp`` switches controls the layout of comments and
@@ -3080,24 +3082,24 @@ Alternatively, you may run the script using the following command line:
    .. index:: -c (gnatpp)
 
 
-   :switch:`-c0`
+   :switch:`--comments-unchanged`
      All comments remain unchanged.
 
 
-   :switch:`-c1`
+   :switch:`--comments-gnat-indentation`
      GNAT-style comment line indentation.
      This is the default.
 
 
-   :switch:`-c3`
+   :switch:`--comments-gnat-beginning`
      GNAT-style comment beginning.
 
 
-   :switch:`-c4`
+   :switch:`--comments-fill`
      Fill comment blocks.
 
 
-   :switch:`-c5`
+   :switch:`--comments-special`
      Keep unchanged special form comments.
      This is the default.
 
@@ -3142,6 +3144,7 @@ Alternatively, you may run the script using the following command line:
    :switch:`--use-on-new-line`
      Start each USE clause in a context clause from a separate line.
 
+
    .. index:: --insert-blank-lines (gnatpp)
 
 
@@ -3156,10 +3159,14 @@ Alternatively, you may run the script using the following command line:
      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.
 
-   The ``-c`` switches are compatible with one another, except that
-   the ``-c0`` switch disables all other comment formatting
-   switches.
+   The ``--comments`` switches are compatible with one another, except
+   that the ``--comments-unchanged`` switch disables all other comment
+   formatting switches.
 
 
    .. _General_Text_Layout_Control:
@@ -3169,21 +3176,21 @@ Alternatively, you may run the script using the following command line:
 
    These switches allow control over line length and indentation.
 
-   .. index:: -M (gnatpp)
+   .. index:: --max-line-length (gnatpp)
 
-   :switch:`-M{nnn}`
+   :switch:`--max-line-length={nnn}`
      Maximum line length, ``nnn`` from 32...256, the default value is 79
 
 
-   .. index:: -i (gnatpp)
+   .. index:: --indentation (gnatpp)
 
-   :switch:`-i{nnn}`
+   :switch:`--indentation={nnn}`
      Indentation level, ``nnn`` from 1...9, the default value is 3
 
 
-   .. index:: -cl (gnatpp)
+   .. index:: --indent-continuation (gnatpp)
 
-   :switch:`-cl{nnn}`
+   :switch:`--indent-continuation={nnn}`
      Indentation level for continuation lines (relative to the line being
      continued), ``nnn`` from 1...9.
      The default
@@ -3232,9 +3239,9 @@ Alternatively, you may run the script using the following command line:
      '(' and ':'. This also turns off alignment.
 
 
-   .. index:: -ff (gnatpp)
+   .. index:: --ff-after-pragma-page (gnatpp)
 
-   :switch:`-ff`
+   :switch:`--ff-after-pragma-page`
      Insert a Form Feed character after a pragma Page.
 
 
@@ -3255,6 +3262,32 @@ Alternatively, you may run the script using the following command line:
      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.
+
 
    .. _Setting_the_Source_Search_Path:
 
@@ -3283,48 +3316,52 @@ Alternatively, you may run the script using the following command line:
    Output File Control
    ^^^^^^^^^^^^^^^^^^^
 
-   By default the output is sent to a file whose name is obtained by appending
-   the :file:`.pp` suffix to the name of the input file.
-   If the file with this name already exists, it is overwritten.
-   Thus if the input file is :file:`my_ada_proc.adb` then
-   ``gnatpp`` will produce :file:`my_ada_proc.adb.pp`
-   as output file.
+   By default the output overwrites the input file.
    The output may be redirected by the following switches:
 
 
+   .. index:: --replace (gnatpp)
+
+   :switch:`--replace`
+     This is the default.
+     Replace the input source file with the reformatted output without
+     creating any backup copy of the input source.
+
+
    .. index:: --output-dir (gnatpp)
 
    :switch:`--output-dir={dir}`
-     Generate output file in directory :file:`dir` with the same name as the input
-     file. If :file:`dir` is the same as the directory containing the input file,
-     the input file is not processed; use ``-rnb``
-     if you want to update the input file in place.
+     Generate output file in directory :file:`dir` with the same name as
+     the input file. If :file:`dir` is the same as the directory
+     containing the input file, the input file is not processed; use
+     ``--replace`` if you want to update the input file in
+     place.
 
 
-   .. index:: -pipe (gnatpp)
+   .. index:: --pipe (gnatpp)
 
-   :switch:`-pipe`
+   :switch:`--pipe`
      Send the output to ``Standard_Output``
 
 
-   .. index:: -o (gnatpp)
+   .. index:: --output (gnatpp)
 
-   :switch:`-o {output_file}`
+   :switch:`--output={output_file}`
      Write the output into ``output_file``.
      If ``output_file`` already exists, ``gnatpp`` terminates without
      reading or processing the input file.
 
 
-   .. index:: -of (gnatpp)
+   .. index:: --output-force (gnatpp)
 
-   :switch:`-of {output_file}`
+   :switch:`--output-force={output_file}`
      Write the output into ``output_file``, overwriting the existing file
      (if one is present).
 
 
-   .. index:: -r (gnatpp)
+   .. index:: --replace-backup (gnatpp)
 
-   :switch:`-r`
+   :switch:`--replace-backup`
      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.
@@ -3332,54 +3369,39 @@ Alternatively, you may run the script using the following command line:
      reading or processing the input file.
 
 
-   .. index:: -rf (gnatpp)
+   .. index:: --replace-force-backup (gnatpp)
 
-   :switch:`-rf`
-     Like ``-r`` except that if the file with the specified name
+   :switch:`--replace-force-backup`
+     Like ``--replace-backup`` except that if the file with the specified name
      already exists, it is overwritten.
 
 
-   .. index:: -rnb (gnatpp)
+   .. index:: --end-of-line (gnatpp)
 
-   :switch:`-rnb`
-     Replace the input source file with the reformatted output without
-     creating any backup copy of the input source.
-
-
-   .. index:: --eol (gnatpp)
-
-   :switch:`--eol={xxx}`
-     Specifies the line-ending style of the reformatted output file. The ``xxx``
-     string specified with the switch may be:
+   :switch:`--end-of-line={xxx}`
+     Specifies the line-ending style of the reformatted output file. The
+     ``xxx`` string specified with the switch may be:
 
      * *dos* - MS DOS style, lines end with CR LF characters*
      * *crlf*  - the same as *dos*
      * *unix* - UNIX style, lines end with LF character*
      * *lf* -  the same as *unix*
 
-   .. index:: -W (gnatpp)
+   .. index:: --wide-character-encoding (gnatpp)
 
-   :switch:`-W{e}`
-     Specify the wide character encoding method for the input and output files.
-     ``e`` is one of the following:
-
-     * *h* - Hex encoding
-
-     * *u* - Upper half encoding
-
-     * *s* - Shift/JIS encoding
-
-     * *e* - EUC encoding
+   :switch:`--wide-character-encoding={e}`
+     Specify the wide character encoding method for the input and output
+     files. ``e`` is one of the following:
 
      * *8* - UTF-8 encoding
 
      * *b* - Brackets encoding (default value)
 
-   Options ``-o`` and ``-of`` are allowed only if the call to gnatpp
-   contains only one file to reformat.
+   Options ``--output-file`` and ``--output-force`` are allowed only if
+   the call to gnatpp contains only one file to reformat.
 
-   Option ``--eol`` and ``-W`` cannot be used together
-   with the ``-pipe`` option.
+   Option ``--end-of-line`` and ``--wide-character-encoding`` cannot be used together
+   with the ``--pipe`` option.
 
 
    .. _Other_gnatpp_Switches:
@@ -3414,14 +3436,14 @@ Alternatively, you may run the script using the following command line:
 
    :switch:`-U`
      If a project file is specified and no argument source is explicitly
-     specified (either directly or by means of ``-files`` option), process
+     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.
 
 
    :switch:`-U {main_unit}`
      If a project file is specified and no argument source is explicitly
-     specified (either directly or by means of ``-files`` option), process
+     specified (either directly or by means of ``--files`` option), process
      the closure of units rooted at ``main_unit``. Otherwise this option
      has no effect.
 
@@ -3450,6 +3472,8 @@ Alternatively, you may run the script using the following command line:
      compiles files that need to be recompiled. A project file is required
      in this mode, and the gnat driver (as in *gnat pretty*) is not
      supported.
+     (Note: this switch is not yet supported in the libadalang-based
+     version of gnatpp.)
 
 
    .. index:: --pp-off  (gnatpp)
@@ -3466,9 +3490,9 @@ Alternatively, you may run the script using the following command line:
      of the default ``--!pp on``.
 
 
-   .. index:: -files (gnatpp)
+   .. index:: --files (gnatpp)
 
-   :switch:`-files {filename}`
+   :switch:`--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.
@@ -3481,44 +3505,27 @@ Alternatively, you may run the script using the following command line:
      Do not process the sources listed in a specified file. This option cannot
      be used in incremental mode.
 
-   .. index:: -j (gnatpp)
+   .. index:: --jobs (gnatpp)
 
-   :switch:`-j{n}`
-     Without ``--incremental``, use *n* processes to carry out the
-     tree creations (internal representations of the argument sources). On
-     a multiprocessor machine this speeds up processing of big sets of
-     argument sources. If *n* is 0, then the maximum number of parallel
-     tree creations is the number of core processors on the platform. This
-     option cannot be used together with the :switch:`-r`,
-     :switch:`-rf` or
-     :switch:`-rnb` options.
+   :switch:`--jobs={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.
 
-     With ``--incremental``, use *n* ``gnatpp`` processes to
-     perform pretty-printing in parallel. *n* = 0 means the same as
-     above. In this case, the :switch:`-r`,
-     :switch:`-rf` and
-     :switch:`-rnb` options are allowed.
 
-   .. index:: -t (gnatpp)
+   .. index:: --verbose (gnatpp)
 
-
-   :switch:`-t`
-     Print out execution time.
-
-
-   .. index:: -v (gnatpp)
-
-   :switch:`-v`
+   :switch:`--verbose`
      Verbose mode
 
 
-   .. index:: -q (gnatpp)
+   .. index:: --quiet (gnatpp)
 
-   :switch:`-q`
+   :switch:`--quiet`
      Quiet mode
 
    If a project file is specified and no argument source is explicitly
-   specified (either directly or by means of ``-files`` option), and no
+   specified (either directly or by means of ``--files`` option), and no
    ``-U`` is specified, then the set of processed sources is
    all the immediate units of the argument project.
 
@@ -3612,42 +3619,40 @@ Alternatively, you may run the script using the following command line:
      the same line.
 
    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 ``-c0`` option
-   turns off comment formatting.
-   Special-form comments such as SPARK-style ``--#...`` are left alone.
+   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
+   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 ``-c3`` switch
-   (GNAT style comment beginning) has the following
-   effect:
+   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.
-
-   The ``-c4`` 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 -c3 and -c4 switches; other
-   formatting switches are ignored. For example,
-   ``--comments-only -c4`` means to fill comment paragraphs, and do nothing else.
-   Likewise,
-   ``--comments-only -c3`` ensures comments start with at least two
-   spaces after ``--``, and ``--comments-only -c3 -c4`` does
-   both. If ``--comments-only`` is given without ``-c3`` or
-   ``-c4``, then gnatpp doesn't format anything.
+       ``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.
 
 
    .. _Name_Casing:
@@ -3658,49 +3663,42 @@ Alternatively, you may run the script using the following command line:
    ``gnatpp`` always converts the usage occurrence of a (simple) name to
    the same casing as the corresponding defining identifier.
 
-   You control the casing for defining occurrences via the
-   ``-n`` switch.
-   With ``-nD`` ('as declared', which is the default),
-   defining occurrences appear exactly as in the source file
-   where they are declared.
-   The other values for this switch --
-   ``-nU``,
-   ``-nL``,
-   ``-nM`` --
-   result in
-   upper, lower, or mixed case, respectively.
-   If ``gnatpp`` changes the casing of a defining
-   occurrence, it analogously changes the casing of all the
-   usage occurrences of this name.
-
-   If the defining occurrence of a name is not in the source compilation unit
-   currently being processed by ``gnatpp``, the casing of each reference to
-   this name is changed according to the value of the ``-n``
-   switch (subject to the dictionary file mechanism described below).
-   Thus ``gnatpp`` acts as though the ``-n`` switch
-   had affected the
-   casing for the defining occurrence of the name.
+   You control the casing for defining occurrences via the ``--name...``
+   switches.  With ``--name-case-as-declared``, which is the default,
+   defining occurrences appear exactly as in the source file where they
+   are declared.  The other values for this switch --
+   ``--name-upper-case``, ``--name-lower-case``, ``--name-mixed-case``
+   -- result in upper, lower, or mixed case, respectively.  If
+   ``gnatpp`` changes the casing of a defining occurrence, it
+   analogously changes the casing of all the usage occurrences of this
+   name.
+
+   If the defining occurrence of a name is not in the source compilation
+   unit currently being processed by ``gnatpp``, the casing of each
+   reference to this name is changed according to the switch (subject to
+   the dictionary file mechanism described below).  Thus ``gnatpp`` acts
+   as though the switch had affected the casing for the defining
+   occurrence of the name.
 
    The options
-   :switch:`-a{x}`,
-   :switch:`-k{x}`,
-   :switch:`-ne{x}`,
-   :switch:`-nt{x}`,
-   :switch:`-nn{x}`, and
-   :switch:`-p{x}`
+   :switch:`--attribute...`,
+   :switch:`--keyword...`,
+   :switch:`--enum...`,
+   :switch:`--type...`,
+   :switch:`--number...`, and
+   :switch:`--pragma...`
    allow finer-grained control over casing for
    attributes, keywords, enumeration literals,
    types, named numbers and pragmas, respectively.
-   :switch:`-nt{x}` covers subtypes and
-   task and protected bodies as well.
+   :switch:`--type...` cover subtypes as well.
 
    Some names may need to be spelled with casing conventions that are not
    covered by the upper-, lower-, and mixed-case transformations.
    You can arrange correct casing by placing such names in a
    *dictionary file*,
-   and then supplying a ``-D`` switch.
+   and then supplying a ``--dictionary`` switch.
    The casing of names from dictionary files overrides
-   any ``-n`` switch.
+   any ``--name...`` switch.
 
    To handle the casing of Ada predefined names and the names from GNAT libraries,
    ``gnatpp`` assumes a default dictionary file.
@@ -3709,15 +3707,15 @@ Alternatively, you may run the script using the following command line:
    The name of each entity in the GNAT libraries is spelled with the same casing
    as is used in the declaration of that entity.
 
-   The ``-D-`` switch suppresses the use of
+   The ``--dictionary=-`` switch suppresses the use of
    the default dictionary file. Instead, the casing for predefined and
    GNAT-defined names will be established by the
    ``-n`` switch or explicit dictionary files. For
    example, by default the names ``Ada.Text_IO`` and
    ``GNAT.OS_Lib`` will appear as just shown, even in the presence of
-   a ``-nU`` switch.  To ensure that even
+   a ``--name-upper-case`` switch.  To ensure that even
    such names are rendered in uppercase, additionally supply the
-   -D- switch (or else place these names
+   --dictionary=- switch (or else place these names
    in upper case in a dictionary file).
 
    A dictionary file is a plain text file; each line in this file can be
@@ -3740,7 +3738,7 @@ Alternatively, you may run the script using the following command line:
    comment; any amount of white space is allowed before the string.
 
    If a dictionary file is passed as
-   the value of a :switch:`-D{file}` switch
+   the value of a :switch:`--dictionary={file}` switch
    then for every
    simple name and every identifier, ``gnatpp`` checks if the dictionary
    defines the casing for the name or for some of its parts (the term 'subword'
@@ -3796,7 +3794,7 @@ Alternatively, you may run the script using the following command line:
 
      ::
 
-        $ gnatpp -nM -D dict1 -D dict2 test.adb
+        $ gnatpp --name-mixed-case --dictionary=dict1 --dictionary=dict2 test.adb
 
    then we will get the following name casing in the ``gnatpp`` output:
 
@@ -3812,6 +3810,200 @@ Alternatively, you may run the script using the following command line:
            Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1;
         end Test;
 
+   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`
+
+   :switch:`-aM`
+     :switch:`--attribute-mixed-case`
+
+   .. index:: -k (gnatpp)
+
+   :switch:`-kL`
+     :switch:`--keyword-lower-case`
+
+   :switch:`-kU`
+     :switch:`--keyword-upper-case`
+
+   .. index:: -ne (gnatpp)
+
+   :switch:`-neD`
+     :switch:`--enum-case-as-declared`
+
+   :switch:`-neU`
+     :switch:`--enum-upper-case`
+
+   :switch:`-neL`
+     :switch:`--enum-lower-case`
+
+   :switch:`-neM`
+     :switch:`--enum-mixed-case`
+
+   .. index:: -nt (gnatpp)
+
+   :switch:`-ntD`
+     :switch:`--type-case-as-declared`
+
+   :switch:`-ntU`
+     :switch:`--type-upper-case`
+
+   :switch:`-ntL`
+     :switch:`--type-lower-case`
+
+   :switch:`-ntM`
+     :switch:`--type-mixed-case`
+
+   :switch:`-nnU`
+     :switch:`--number-upper-case`
+
+   :switch:`-nnL`
+     :switch:`--number-lower-case`
+
+   :switch:`-nnM`
+     :switch:`--number-mixed-case`
+
+   .. index:: -p (gnatpp)
+
+   :switch:`-pL`
+     :switch:`--pragma-lower-case`
+
+   :switch:`-pU`
+     :switch:`--pragma-upper-case`
+
+   :switch:`-pM`
+     :switch:`--pragma-mixed-case`
+
+   .. index:: -D (gnatpp)
+
+   :switch:`-D{file}`
+     :switch:`--dictionary={file}`
+
+   .. index:: -D- (gnatpp)
+
+   :switch:`-D-`
+     :switch:`--dictionary=-`
+
+   .. index:: -c (gnatpp)
+
+   :switch:`-c0`
+     :switch:`--comments-unchanged`
+
+   :switch:`-c1`
+     :switch:`--comments-gnat-indentation`
+
+   :switch:`-c3`
+     :switch:`--comments-gnat-beginning`
+
+   :switch:`-c4`
+     :switch:`--comments-fill`
+
+   :switch:`-c5`
+     :switch:`--comments-special`
+
+   .. index:: -M (gnatpp)
+
+   :switch:`-M{nnn}`
+     :switch:`--max-line-length={nnn}`
+
+   .. index:: -i (gnatpp)
+
+   :switch:`-i{nnn}`
+     :switch:`--indentation={nnn}`
+
+   .. index:: -cl (gnatpp)
+
+   :switch:`-cl{nnn}`
+     :switch:`--indent-continuation={nnn}`
+
+   .. index:: -ff (gnatpp)
+
+   :switch:`-ff`
+     :switch:`--ff-after-pragma-page`
+
+   .. index:: -pipe (gnatpp)
+
+   :switch:`-pipe`
+     :switch:`--pipe`
+
+   .. index:: -o (gnatpp)
+
+   :switch:`-o {output-file}`
+     :switch:`--output={output-file}`
+
+   .. index:: -of (gnatpp)
+
+   :switch:`-of {output-file}`
+     :switch:`--output-force={output-file}`
+
+   .. index:: -r (gnatpp)
+
+   :switch:`-rnb`
+     :switch:`--replace`
+
+   :switch:`-r`
+     :switch:`--replace-backup`
+
+   .. index:: -rf (gnatpp)
+
+   :switch:`-rf`
+     :switch:`--replace-force-backup`
+
+   .. index:: -rnb (gnatpp)
+
+   .. index:: --eol (gnatpp)
+
+   :switch:`--eol={xxx}`
+     :switch:`--end-of-line={xxx}`
+
+   .. index:: -W (gnatpp)
+
+   :switch:`-W{e}`
+     :switch:`--wide-character-encoding={e}`
+
+   .. index:: -files (gnatpp)
+
+   :switch:`-files {filename}`
+     :switch:`--files={filename}`
+
+   .. index:: -j (gnatpp)
+
+   :switch:`-j{n}`
+     :switch:`--jobs={n}`
+
+   .. index:: -v (gnatpp)
+
+   :switch:`-v`
+     :switch:`--verbose`
+
+   .. index:: -q (gnatpp)
+
+   :switch:`-q`
+     :switch:`--quiet`
+
 
 .. only:: PRO or GPL