[gcc r13-1637] [Ada] Make it clear that gnatmake passes the ball to gprbuild if -P is set

[Pierre-Marie de Rodat <pmderodat@gcc.gnu.org>]

https://gcc.gnu.org/g:3a7a02f4355bb81f7cb253fc900ad57c9503f5c7

commit r13-1637-g3a7a02f4355bb81f7cb253fc900ad57c9503f5c7
Author: Vasiliy Fofanov <fofanov@adacore.com>
Date:   Tue Jun 28 17:50:38 2022 +0200

    [Ada] Make it clear that gnatmake passes the ball to gprbuild if -P is set
    
    Also move -P switch description to the top of the switches list.
    
    gcc/ada/
    
            * makeusg.adb,
            doc/gnat_ugn/building_executable_programs_with_gnat.rst: Move -P
            to the top of switches list and make it clear that gnatmake
            passes the ball to gprbuild if -P is set.
            * gnat_ugn.texi: Regenerate.

Diff:
---
 .../building_executable_programs_with_gnat.rst     | 20 ++++++++-------
 gcc/ada/gnat_ugn.texi                              | 30 ++++++++++++----------
 gcc/ada/makeusg.adb                                | 12 +++++----
 3 files changed, 34 insertions(+), 28 deletions(-)

diff --git a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
index c0eeca43cf0..5442d5544cb 100644
--- a/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
+++ b/gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst
@@ -139,6 +139,17 @@ You may specify any of the following switches to ``gnatmake``:
   all other options.
 
 
+.. index:: -P  (gnatmake)
+
+:switch:`-P{project}`
+  Build GNAT project file ``project`` using GPRbuild. When this switch is
+  present, all other command-line switches are treated as GPRbuild switches
+  and not ``gnatmake`` switches.
+
+.. -- Comment:
+  :ref:`gnatmake_and_Project_Files`.
+
+
 .. index:: --GCC=compiler_name  (gnatmake)
 
 :switch:`--GCC={compiler_name}`
@@ -522,15 +533,6 @@ You may specify any of the following switches to ``gnatmake``:
 :switch:`-p`
   Same as :switch:`--create-missing-dirs`
 
-.. index:: -P  (gnatmake)
-
-:switch:`-P{project}`
-  Use project file ``project``. Only one such switch can be used.
-
-.. -- Comment:
-  :ref:`gnatmake_and_Project_Files`.
-
-
 .. index:: -q  (gnatmake)
 
 :switch:`-q`
diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index cfd9a87395d..64ebd95cbe0 100644
--- a/gcc/ada/gnat_ugn.texi
+++ b/gcc/ada/gnat_ugn.texi
@@ -21,7 +21,7 @@
 
 @copying
 @quotation
-GNAT User's Guide for Native Platforms , Jun 24, 2022
+GNAT User's Guide for Native Platforms , Jul 11, 2022
 
 AdaCore
 
@@ -7120,6 +7120,21 @@ If @code{--version} was not used, display usage, then exit disregarding
 all other options.
 @end table
 
+@geindex -P (gnatmake)
+
+
+@table @asis
+
+@item @code{-P@emph{project}}
+
+Build GNAT project file @code{project} using GPRbuild. When this switch is
+present, all other command-line switches are treated as GPRbuild switches
+and not @code{gnatmake} switches.
+@end table
+
+@c -- Comment:
+@c :ref:`gnatmake_and_Project_Files`.
+
 @geindex --GCC=compiler_name (gnatmake)
 
 
@@ -7620,19 +7635,6 @@ This switch cannot be used when invoking @code{gnatmake} with several
 Same as @code{--create-missing-dirs}
 @end table
 
-@geindex -P (gnatmake)
-
-
-@table @asis
-
-@item @code{-P@emph{project}}
-
-Use project file @code{project}. Only one such switch can be used.
-@end table
-
-@c -- Comment:
-@c :ref:`gnatmake_and_Project_Files`.
-
 @geindex -q (gnatmake)
 
 
diff --git a/gcc/ada/makeusg.adb b/gcc/ada/makeusg.adb
index e7653ebc552..74c0d171306 100644
--- a/gcc/ada/makeusg.adb
+++ b/gcc/ada/makeusg.adb
@@ -54,6 +54,13 @@ begin
 
    Display_Usage_Version_And_Help;
 
+   --  Line for -P
+
+   Write_Str ("  -Pproj   Build GNAT Project File proj using GPRbuild");
+   Write_Eol;
+   Write_Str ("           Treats all other switches as GPRbuild switches");
+   Write_Eol;
+
    --  Line for -a
 
    Write_Str ("  -a       Consider all files, even readonly ali files");
@@ -169,11 +176,6 @@ begin
    Write_Str ("  -p       Create missing obj, lib and exec dirs");
    Write_Eol;
 
-   --  Line for -P
-
-   Write_Str ("  -Pproj   Use GNAT Project File proj");
-   Write_Eol;
-
    --  Line for -q
 
    Write_Str ("  -q       Be quiet/terse");