[Ada] Document handling of preprocessor directives in GNATpp

2019-07-08  Bob Duff  <duff@adacore.com>

gcc/ada/

	* doc/gnat_ugn/gnat_utility_programs.rst: Document handling of
	preprocessor directives in GNATpp.

From-SVN: r273203

diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog
index bec33068f53b554076caadd8ca2814fa960e4aeb..72cb89296d1929a06d32544e176080dd2310f780 100644 (file)
--- a/gcc/ada/ChangeLog
+++ b/gcc/ada/ChangeLog
@@ -1,3 +1,8 @@
+2019-07-08  Bob Duff  <duff@adacore.com>
+
+       * doc/gnat_ugn/gnat_utility_programs.rst: Document handling of
+       preprocessor directives in GNATpp.
+
 2019-07-08  Javier Miranda  <miranda@adacore.com>
 
        * gnat1drv.adb (Post_Compilation_Validation_Checks:

diff --git a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
index 53904b13572653f5438af3cd90ad2e90dab3f939..b6a1d189f8b4074f3cfdf42c5ccceb61b6579265 100644 (file)
--- a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
+++ b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
@@ -3933,6 +3933,67 @@ Alternatively, you may run the script using the following command line:
            Name2_NAME3_Name4 := Name4_NAME3_Name2 > NAME1;
         end Test;
 
+   .. _Preprocessor_directives:
+
+   Preprocessor Directives
+   ^^^^^^^^^^^^^^^^^^^^^^^
+
+   ``gnatpp`` has some support for preprocessor directives.
+   You can use preprocessor symbols, as in ``$symbol``.
+   In addition, you can use conditional compilation,
+   so long as the program text is syntactically legal Ada code
+   after removing all the preprocessor directives (lines starting
+   with ``#``). For example, ``gnatpp`` can format the following:
+
+     .. code-block:: ada
+
+        package P is
+        #IF SOMETHING
+           X : constant Integer := 123;
+        #ELSE
+           X : constant Integer := 456;
+        #END IF;
+        end P;
+
+   which will be formatted as if it were:
+
+     .. code-block:: ada
+
+        package P is
+           X : constant Integer := 123;
+           X : constant Integer := 456;
+        end P;
+
+   except that the ``#`` lines will be preserved.
+   However, ``gnatpp`` cannot format the following:
+
+     .. code-block:: ada
+
+        procedure P is
+        begin
+        #IF SOMETHING
+           if X = 0 then
+        #ELSE
+           if X = 1 then
+        #END IF;
+              null;
+           end if;
+        end P;
+
+   because removing the ``#`` lines gives:
+
+     .. code-block:: ada
+
+        procedure P is
+        begin
+           if X = 0 then
+           if X = 1 then
+              null;
+           end if;
+        end P;
+
+   which is not syntactically legal.
+
    Legacy Switches
    ^^^^^^^^^^^^^^^