gnat_ugn.texi: Document the new "--&pp off" feature of gnatpp.

2014-01-23  Bob Duff  <duff@adacore.com>

	* gnat_ugn.texi: Document the new "--&pp off" feature of gnatpp.

From-SVN: r206988

diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog
index a8851565ead2610f5b096b4bdd42cb2599abc0e2..8c57db842acda7cc80677333b56ea2776458bd92 100644 (file)
--- a/gcc/ada/ChangeLog
+++ b/gcc/ada/ChangeLog
@@ -1,3 +1,7 @@
+2014-01-23  Bob Duff  <duff@adacore.com>
+
+       * gnat_ugn.texi: Document the new "--&pp off" feature of gnatpp.
+
 2014-01-23  Robert Dewar  <dewar@adacore.com>
 
        * gnatlink.adb (Gnatlink): Fix problem of generating bad name

diff --git a/gcc/ada/gnat_ugn.texi b/gcc/ada/gnat_ugn.texi
index 3649149969672c2cd09932f7dfd7eedd99560d76..88f2138e8a5821696d4edd9a7f763475a82a718e 100644 (file)
--- a/gcc/ada/gnat_ugn.texi
+++ b/gcc/ada/gnat_ugn.texi
@@ -14501,6 +14501,16 @@ Display Copyright and version, then exit disregarding all other options.
 @cindex @option{--help} @command{gnatpp}
 Display usage, then exit disregarding all other options.
 
+@item --pp-off=@var{xxx}
+@cindex @option{--pp-off} @command{gnatpp}
+Use @code{--xxx} as the command to turn off pretty printing, instead
+of the default @code{--&pp off}.
+
+@item --pp-on=@var{xxx}
+@cindex @option{--pp-on} @command{gnatpp}
+Use @code{--xxx} as the command to turn pretty printing back on, instead
+of the default @code{--&pp on}.
+
 @item --pp-old
 @cindex @option{--pp-old} @command{gnatpp}
 Use the old formatting algorithms.
@@ -14535,12 +14545,39 @@ comments, program layout, and name casing.
 They provide the detailed descriptions of the switches shown above.
 
 @menu
+* Disabling Pretty Printing::
 * White Space and Empty Lines::
 * Formatting Comments::
 * Construct Layout::
 * Name Casing::
 @end menu
 
+@node Disabling Pretty Printing
+@subsection Disabling Pretty Printing
+
+@noindent
+Pretty printing is highly heuristic in nature, and sometimes doesn't
+do exactly what you want. If you wish to format a certain region of
+code by hand, you can turn off pretty printing in that region by
+surrounding it with the special comments @code{--&pp off} and
+@code{--&pp on}. The text in that region will then be reproduced
+verbatim in the output with no formatting.
+
+To disable pretty printing for the whole file, put @code{--&pp off} at
+the top, with no following @code{--&pp on}.
+
+The comments must appear on a line by themselves, with nothing
+preceding except spaces, and they must appear exactly as shown (case
+sensitive). For example, @code{--&pp off -- Turn off pp because ...}
+will not be recognized as a valid @code{--&pp off} command.
+
+You can specify different comment strings using the gnatpp
+@code{--pp-off} and @code{--pp-on} switches. For example, if you say
+@code{gnatpp --pp-off=' pp-' *.ad?} then gnatpp will recognize
+comments of the form @code{-- pp-}, instead of @code{--&pp off} for
+disabling pretty printing. Note that the leading @code{--} of the
+comment is not included in the argument to these switches.
+
 @node White Space and Empty Lines
 @subsection White Space and Empty Lines