[Ada] Update user manual for the -D binder switch

2018-05-28  Patrick Bernardi  <bernardi@adacore.com>

gcc/ada/

	* doc/gnat_ugn/building_executable_programs_with_gnat.rst: Update the
	description of the -D binder switch to reflect current usage.
	* gnat_ugn.texi: Regenerate.

From-SVN: r260824

gcc/ada/ChangeLog

+2018-05-28  Patrick Bernardi  <bernardi@adacore.com>
+
+	* doc/gnat_ugn/building_executable_programs_with_gnat.rst: Update the
+	description of the -D binder switch to reflect current usage.
+	* gnat_ugn.texi: Regenerate.
+
 2018-05-28  Gary Dismukes  <dismukes@adacore.com>
 
 	* exp_ch3.adb: Minor reformatting

gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst

@@ -6198,28 +6198,25 @@ be presented in subsequent sections.
 .. index:: -D  (gnatbind)
 
 :switch:`-D{nn}[k|m]`
-  This switch can be used to change the default secondary stack size value
-  to a specified size ``nn``, which is expressed in bytes by default, or
-  in kilobytes when suffixed with ``k`` or in megabytes when suffixed
-  with ``m``.
-
-  The secondary stack is used to deal with functions that return a variable
-  sized result, for example a function returning an unconstrained
-  String. There are two ways in which this secondary stack is allocated.
-
-  For most targets, the secondary stack grows on demand and is allocated
-  as a chain of blocks in the heap. The -D option is not very
-  relevant. It only give some control over the size of the allocated
-  blocks (whose size is the minimum of the default secondary stack size value,
-  and the actual size needed for the current allocation request).
-
-  For certain targets, notably VxWorks 653 and bare board targets,
-  the secondary stack is allocated by carving off a chunk of the primary task
-  stack. By default this is a fixed percentage of the primary task stack as
-  defined by System.Parameter.Sec_Stack_Percentage. This can be overridden per
-  task using the Secondary_Stack_Size pragma/aspect. The -D option is used to
-  define the size of the environment task's secondary stack.
-
+  Set the default secondary stack size to ``nn``. The suffix indicates whether
+  the size is in bytes (no suffix), kilobytes (``k`` suffix) or megabytes
+  (``m`` suffix).
+
+  The secondary stack holds objects of unconstrained types that are returned by
+  functions, for example unconstrained Strings. The size of the secondary stack
+  can be dynamic or fixed depending on the target.
+
+  For most targets, the secondary stack grows on demand and is implemented as
+  a chain of blocks in the heap. In this case, the default secondary stack size
+  determines the initial size of the secondary stack for each task and the
+  smallest amount the secondary stack can grow by.
+
+  For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is
+  fixed. This switch can be used to change the default size of these stacks.
+  The default secondary stack size can be overridden on a per-task basis if
+  individual tasks have different secondary stack requirements. This is
+  achieved through the Secondary_Stack_Size aspect that takes the size of the
+  secondary stack in bytes.
 
 .. index:: -e  (gnatbind)
 

gcc/ada/gnat_ugn.texi

@@ -3,7 +3,7 @@
 @setfilename gnat_ugn.info
 @documentencoding UTF-8
 @ifinfo
-@*Generated by Sphinx 1.3.6.@*
+@*Generated by Sphinx 1.4.6.@*
 @end ifinfo
 @settitle GNAT User's Guide for Native Platforms
 @defindex ge
@@ -21,7 +21,7 @@
 
 @copying
 @quotation
-GNAT User's Guide for Native Platforms , April 25, 2018
+GNAT User's Guide for Native Platforms , May 22, 2018
 
 AdaCore
 
@@ -15512,27 +15512,25 @@ When they do not already have such a pragma.
 
 @item @code{-D@emph{nn}[k|m]}
 
-This switch can be used to change the default secondary stack size value
-to a specified size @code{nn}, which is expressed in bytes by default, or
-in kilobytes when suffixed with @code{k} or in megabytes when suffixed
-with @code{m}.
-
-The secondary stack is used to deal with functions that return a variable
-sized result, for example a function returning an unconstrained
-String. There are two ways in which this secondary stack is allocated.
-
-For most targets, the secondary stack grows on demand and is allocated
-as a chain of blocks in the heap. The -D option is not very
-relevant. It only give some control over the size of the allocated
-blocks (whose size is the minimum of the default secondary stack size value,
-and the actual size needed for the current allocation request).
-
-For certain targets, notably VxWorks 653 and bare board targets,
-the secondary stack is allocated by carving off a chunk of the primary task
-stack. By default this is a fixed percentage of the primary task stack as
-defined by System.Parameter.Sec_Stack_Percentage. This can be overridden per
-task using the Secondary_Stack_Size pragma/aspect. The -D option is used to
-define the size of the environment task's secondary stack.
+Set the default secondary stack size to @code{nn}. The suffix indicates whether
+the size is in bytes (no suffix), kilobytes (@code{k} suffix) or megabytes
+(@code{m} suffix).
+
+The secondary stack holds objects of unconstrained types that are returned by
+functions, for example unconstrained Strings. The size of the secondary stack
+can be dynamic or fixed depending on the target.
+
+For most targets, the secondary stack grows on demand and is implemented as
+a chain of blocks in the heap. In this case, the default secondary stack size
+determines the initial size of the secondary stack for each task and the
+smallest amount the secondary stack can grow by.
+
+For Ravenscar, ZFP, and Cert run-times the size of the secondary stack is
+fixed. This switch can be used to change the default size of these stacks.
+The default secondary stack size can be overridden on a per-task basis if
+individual tasks have different secondary stack requirements. This is
+achieved through the Secondary_Stack_Size aspect that takes the size of the
+secondary stack in bytes.
 @end table
 
 @geindex -e (gnatbind)