2006-10-31 Robert Dewar <dewar@adacore.com>

	    Cyrille Comar  <comar@adacore.com>
	    Ben Brosgol  <brosgol@adacore.com>

	* debug.adb:  Update flags documentation

        * gnat_ugn.texi: Add documentation for new -gnatwq switch
        Clean up documentation for several other warning switches
        Clarify how task stack size can be specified with various
        versions of Windows.
        Add note that -gnatVo includes ranges including loops
	Add documentation for -gnatL switch
	Add note on elaboration warning for initializing variables
	Add documentation for new -gnatwt warning switch
	Document new form of pragma Warnings (On|Off, string)
	Add comment on use of pragma Warnings to control warnings
	Add documentation for -gnatjnn switch
	Modify section on interfacing with C for VMS 64-bit.
	Add doc for -gnatVe/E
	Add documentation of new warning flags -gnatww/-gnatwW
	Add warnings about address clause overlays to list of warnings
	(Exception Handling Control): Document that the option --RTS must be
	used consistently for gcc and gnatbind.
	Clarify that inlining is not always possible
	Update documentation on pragma Unchecked_Union.

	* gnat_rm.texi: 
	Add documentation for new extended version of pragma Obsolescent
	Add documentation for implementation defined attribute 'Stub_Type.
	Add note on use of Volatile in asm statements
	Add documentation on use of pragma Unreferenced in context clause
	Document new form of pragma Warnings (On|Off, pattern)
	Document pragma Wide_Character_Encoding
	Add note that pragma Restrictions (No_Elaboration_Code) is only fully
	enforced if code generation is active.
	Add section on pragma Suppress to document GNAT specific check
	Alignment_Check
	Clarify difference between No_Dispatching_Calls & No_Dispatch.
	Add documentation for pragma Restrictions (No_Elaboration_Code)

	* gnat-style.texi: 
	Add comments on layout of subprogram local variables in the
	presence of nested subprograms.

        * ug_words: Resync.

	* elists.ads: Minor reformatting
	Node returns Node_Or_Entity_Id (doc change only)

	* xgnatugn.adb: Replace ACADEMICEDITION with GPLEDITION

	* g-arrspl.ads (Create): Update comments.

	* sem.ads: Add details on the handling of the scope stack.

        * usage.adb: Update documentation.

	* validsw.ads, validsw.adb: 
	Add definition of Validity_Check_Components and implement -gnatVe/E

        * vms_data.ads: Add missing VMS qualifiers.

	* s-addope.ads: Add documentation on overflow and divide by zero



git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@118328 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 73 insertions, 2 deletions

diff --git a/gcc/ada/gnat-style.texi b/gcc/ada/gnat-style.texi
index cbe75ad44ce..701897432d0 100644
--- a/gcc/ada/gnat-style.texi
+++ b/gcc/ada/gnat-style.texi
@@ -712,7 +712,7 @@ alternative forms for the above spec are:
 @item
 Function and procedure bodies should usually be sorted alphabetically. Do
 not attempt to sort them in some logical order by functionality. For a
-sequence of subrpgroams specs, a general alphabetical sorting is also
+sequence of subprogram specs, a general alphabetical sorting is also
 usually appropriate, but occasionally it makes sense to group by major
 function, with appropriate headers.
 
@@ -749,7 +749,8 @@ A sequence of declarations may optionally be separated from the following
 begin by a blank line.  Just as we optionally allow blank lines in general
 between declarations, this blank line should be present only if it improves
 readability. Generally we avoid this blank line if the declarative part is
-small (one or two lines) and we include it if the declarative part is long.
+small (one or two lines) and the body has no blank lines, and we include it
+if the declarative part is long or if the body has blank lines.
 
 @item
 If the declarations in a subprogram contain at least one nested
@@ -766,8 +767,78 @@ subprogram, there is a comment line and a blank line:
 @end group
 @end smallexample
 
+@item
+When nested subprograms are present, variables that are referenced by any
+nested subprogram should precede the nested subprogram specs. For variables
+that are not referenced by nested procedures, the declarations can either also
+be before any of the nested subprogram specs (this is the old style, more
+generally used). Or then can come just before the begin, with a header. The
+following example shows the two possible styles:
+
+@smallexample @c adanocomment
+@group
+    procedure Style1 is
+       Var_Referenced_In_Nested      : Integer;
+       Var_Referenced_Only_In_Style1 : Integer;
+
+       proc Nested;
+       --  Comments ...
+
+
+       ------------
+       -- Nested --
+       ------------
+
+       procedure Nested is
+       begin
+          ...
+       end Nested;
+
+    --  Start of processing for Style1
+
+    begin
+       ...
+    end Style1;
+
+@end group
+
+@group
+    procedure Style2 is
+       Var_Referenced_In_Nested : Integer;
+
+       proc Nested;
+       --  Comments ...
+
+       ------------
+       -- Nested --
+       ------------
+
+       procedure Nested is
+       begin
+          ...
+       end Nested;
+
+       --  Local variables
+
+       Var_Referenced_Only_In_Style2 : Integer;
+
+    --  Start of processing for Style2
+
+    begin
+       ...
+    end Style2;
+
+@end group
+@end smallexample
+
+@noindent
+For new code, we generally prefer Style2, but we do not insist on
+modifying all legacy occurrences of Style1, which is still much
+more common in the sources.
+
 @end itemize
 
+
 @c  -------------------------------------------------------------------------
 @node    Packages, Program Structure, Subprograms, Top
 @section Packages and Visibility Rules