Update documentation.

From-SVN: r237979

gcc/ada/ChangeLog

 2016-07-04  Arnaud Charlet  <charlet@adacore.com>
 
+	* gnat_rm.texi, gnat_ugn.texi,
+	doc/gnat_ugn/gnat_project_manager.rst,
+	doc/gnat_ugn/building_executable_programs_with_gnat.rst,
+	doc/gnat_ugn/elaboration_order_handling_in_gnat.rst,
+	doc/gnat_ugn/about_this_guide.rst,
+	doc/gnat_ugn/platform_specific_information.rst,
+	doc/gnat_ugn/tools_supporting_project_files.rst,
+	doc/gnat_ugn/gnat_and_program_execution.rst,
+	doc/gnat_ugn/gnat_utility_programs.rst,
+	doc/gnat_ugn/the_gnat_compilation_model.rst,
+	doc/gnat_rm/implementation_defined_attributes.rst,
+	doc/gnat_rm/implementation_defined_pragmas.rst,
+	doc/gnat_rm/representation_clauses_and_pragmas.rst,
+	doc/gnat_rm/standard_and_implementation_defined_restrictions.rst,
+	doc/gnat_ugn.rst: Update documentation.
+
+2016-07-04  Arnaud Charlet  <charlet@adacore.com>
+
 	* gcc-interface/Makefile.in: Cleanups.
 
 2016-07-04  Ed Schonberg  <schonberg@adacore.com>

gcc/ada/doc/gnat_rm/implementation_defined_attributes.rst

@@ -966,9 +966,6 @@ types. This may be overridden for the derived type by giving an explicit scalar
 storage order for the derived type. For a record extension, the derived type
 must have the same scalar storage order as the parent type.
 
-If a component of `T` is of a record or array type, then that type must
-also have a `Scalar_Storage_Order` attribute definition clause.
-
 A component of a record or array type that is a bit-packed array, or that
 does not start on a byte boundary, must have the same scalar storage order
 as the enclosing record or array type.
@@ -1005,6 +1002,11 @@ inheritance in the case of a derived type), then the default is normally
 the native ordering of the target, but this default can be overridden using
 pragma `Default_Scalar_Storage_Order`.
 
+Note that if a component of `T` is itself of a record or array type,
+the specfied `Scalar_Storage_Order` does *not* apply to that nested type:
+an explicit attribute definition clause must be provided for the component
+type as well if desired.
+
 Note that the scalar storage order only affects the in-memory data
 representation. It has no effect on the representation used by stream
 attributes.

gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst

@@ -196,7 +196,7 @@ Ada 83, Ada 95, or Ada 2005 programs.
 The one argument form, which is not a configuration pragma,
 is used for managing the transition from Ada
 2005 to Ada 2012 in the run-time library. If an entity is marked
-as Ada_201 only, then referencing the entity in any pre-Ada_2012
+as Ada_2012 only, then referencing the entity in any pre-Ada_2012
 mode will generate a warning. In addition, in any pre-Ada_2012
 mode, a preference rule is established which does not choose
 such an entity unless it is unambiguously specified. This avoids
@@ -6821,6 +6821,40 @@ the handling of existing code which depends on the interpretation of Size
 as implemented in the VADS compiler.  See description of the VADS_Size
 attribute for further details.
 
+.. _Pragma-Unused:
+
+Pragma Unused
+=============
+.. index:: Warnings, unused
+
+Syntax:
+
+
+::
+
+  pragma Unused (LOCAL_NAME {, LOCAL_NAME});
+
+
+This pragma signals that the assignable entities (variables,
+`out` parameters, and `in out` parameters) whose names are listed
+deliberately do not get assigned or referenced in the current source unit
+after the occurrence of the pragma in the current source unit. This
+suppresses warnings about the entities that are unreferenced and/or not
+assigned, and, in addition, a warning will be generated if one of these
+entities gets assigned or subsequently referenced in the same unit as the
+pragma (in the corresponding body or one of its subunits).
+
+This is particularly useful for clearly signaling that a particular
+parameter is not modified or referenced, even though the spec suggests
+that it might be.
+
+For the variable case, warnings are never given for unreferenced
+variables whose name contains one of the substrings
+`DISCARD, DUMMY, IGNORE, JUNK, UNUSED` in any casing. Such names
+are typically to be used in cases where such warnings are expected.
+Thus it is never necessary to use `pragma Unmodified` for such
+variables, though it is harmless to do so. 
+
 Pragma Validity_Checks
 ======================
 

gcc/ada/doc/gnat_rm/representation_clauses_and_pragmas.rst

@@ -53,9 +53,9 @@ values are as follows:
   For arrays, the alignment is equal to the alignment of the component type
   for the normal case where no packing or component size is given.  If the
   array is packed, and the packing is effective (see separate section on
-  packed arrays), then the alignment will be either 4, 2 or 1 for long packed
+  packed arrays), then the alignment will be either 4, 2, or 1 for long packed
   arrays or arrays whose length is not known at compile time, depending on
-  whether the component size is divisible by 4, 2 or is odd.  For short packed
+  whether the component size is divisible by 4, 2, or is odd.  For short packed
   arrays, which are handled internally as modular types, the alignment
   will be as described for elementary types, e.g. a packed array of length
   31 bits will have an object size of four bytes, and an alignment of 4.
@@ -490,7 +490,7 @@ discrete types are as follows:
   The `Object_Size` for base subtypes reflect the natural hardware
   size in bits (run the compiler with *-gnatS* to find those values
   for numeric types). Enumeration types and fixed-point base subtypes have
-  8, 16, 32 or 64 bits for this size, depending on the range of values
+  8, 16, 32, or 64 bits for this size, depending on the range of values
   to be stored.
 
 *
@@ -1187,7 +1187,7 @@ taken by components.  We distinguish between *packable* components and
 Components of the following types are considered packable:
 
 * Components of an elementary type are packable unless they are aliased,
-  independent or of an atomic type.
+  independent, or of an atomic type.
 
 * Small packed arrays, where the size is statically known, are represented
   internally as modular integers, and so they are also packable.

gcc/ada/doc/gnat_rm/standard_and_implementation_defined_restrictions.rst

@@ -445,20 +445,6 @@ No_Implicit_Heap_Allocations
 
 [RM D.7] No constructs are allowed to cause implicit heap allocation.
 
-No_Implicit_Loops
------------------
-.. index:: No_Implicit_Loops
-
-[GNAT] This restriction ensures that the generated code does not contain any
-implicit `for` loops, either by modifying
-the generated code where possible,
-or by rejecting any construct that would otherwise generate an implicit
-`for` loop. If this restriction is active, it is possible to build
-large array aggregates with all static components without generating an
-intermediate temporary, and without generating a loop to initialize individual
-components. Otherwise, a loop is created for arrays larger than about 5000
-scalar components.
-
 No_Implicit_Protected_Object_Allocations
 ----------------------------------------
 .. index:: No_Implicit_Protected_Object_Allocations
@@ -969,6 +955,20 @@ Unrestricted_Access is forbidden is that it would require the prefix
 to be aliased, and in such cases, it can always be replaced by
 the standard attribute Unchecked_Access which is preferable.
 
+No_Implicit_Loops
+-----------------
+.. index:: No_Implicit_Loops
+
+[GNAT] This restriction ensures that the generated code of the unit marked
+with this restriction does not contain any implicit `for` loops, either by
+modifying the generated code where possible, or by rejecting any construct
+that would otherwise generate an implicit `for` loop. If this restriction is
+active, it is possible to build large array aggregates with all static
+components without generating an intermediate temporary, and without generating
+a loop to initialize individual components. Otherwise, a loop is created for
+arrays larger than about 5000 scalar components. Note that if this restriction
+is set in the spec of a package, it will not apply to its body.
+
 No_Obsolescent_Features
 -----------------------
 .. index:: No_Obsolescent_Features

gcc/ada/doc/gnat_ugn.rst

@@ -42,8 +42,6 @@ included in the section entitled :ref:`gnu_fdl`.
    gnat_ugn/getting_started_with_gnat
    gnat_ugn/the_gnat_compilation_model
    gnat_ugn/building_executable_programs_with_gnat
-   gnat_ugn/gnat_project_manager
-   gnat_ugn/tools_supporting_project_files
    gnat_ugn/gnat_utility_programs
    gnat_ugn/gnat_and_program_execution
 

gcc/ada/doc/gnat_ugn/about_this_guide.rst

@@ -37,12 +37,6 @@ This guide contains the following chapters:
   main GNAT tools to build executable programs, and it also gives examples of
   using the GNU make utility with GNAT.
 
-* :ref:`GNAT_Project_Manager` describes how to use project files
-  to organize large projects.
-  
-* :ref:`Tools_Supporting_Project_Files` described how to use the project
-  facility in conjunction with various GNAT tools.
-
 * :ref:`GNAT_Utility_Programs` explains the various utility programs that
   are included in the GNAT environment
 

gcc/ada/doc/gnat_ugn/building_executable_programs_with_gnat.rst

@@ -27,6 +27,15 @@ Finally, this chapter provides examples of
 how to make use of the general GNU make mechanism
 in a GNAT context (see :ref:`Using_the_GNU_make_Utility`).
 
+.. only:: PRO or GPL
+  
+   For building large systems with components possibly written
+   in different languages (such as Ada, C, C++ and Fortran)
+   and organized into subsystems and libraries, the GPRbuild
+   tool can be used. This tool, and the Project Manager
+   facility that it is based upon, is described in
+   *GPRbuild and GPR Companion Tools User's Guide*.
+	  
 
 .. _The_GNAT_Make_Program_gnatmake:
 
@@ -67,8 +76,9 @@ changes to the source program cause corresponding changes in
 dependencies, they will always be tracked exactly correctly by
 *gnatmake*.
 
-Note that for advanced description of project structure, we recommend creating
-a project file as explained in :ref:`GNAT_Project_Manager` and use the
+Note that for advanced forms of project structure, we recommend creating
+a project file as explained in the *GNAT_Project_Manager* chapter in the
+*GPRbuild User's Guide*, and using the
 *gprbuild* tool which supports building with project files and works similarly
 to *gnatmake*.
 
@@ -516,6 +526,8 @@ You may specify any of the following switches to *gnatmake*:
 
 :samp:`-P{project}`
   Use project file `project`. Only one such switch can be used.
+
+.. -- Comment:  
   :ref:`gnatmake_and_Project_Files`.
 
 
@@ -545,8 +557,10 @@ You may specify any of the following switches to *gnatmake*:
 :samp:`-u`
   Unique. Recompile at most the main files. It implies -c. Combined with
   -f, it is equivalent to calling the compiler directly. Note that using
-  -u with a project file and no main has a special meaning
-  (:ref:`Project_Files_and_Main_Subprograms`).
+  -u with a project file and no main has a special meaning.
+
+.. --Comment:
+  (See :ref:`Project_Files_and_Main_Subprograms`.)
 
 
 .. index:: -U  (gnatmake)

gcc/ada/doc/gnat_ugn/elaboration_order_handling_in_gnat.rst

@@ -1541,19 +1541,24 @@ fall back to run-time checks; premature calls to any primitive
 operation of a tagged type before the body of the operation has been
 elaborated will raise `Program_Error`.
 
-Access-to-subprogram types, however, are handled conservatively, and
-do not require run-time checks. This was not true in earlier versions
-of the compiler; you can use the *-gnatd.U* debug switch to
-revert to the old behavior if the new conservative behavior causes
-elaboration cycles. Here, 'conservative' means that if you do
-`P'Access` during elaboration, the compiler will assume that you
-might call `P` indirectly during elaboration, so it adds an
-implicit `pragma Elaborate_All` on the library unit containing
-`P`. The *-gnatd.U* switch is safe if you know there are
-no such calls. If the program worked before, it will continue to work
-with *-gnatd.U*. But beware that code modifications such as
-adding an indirect call can cause erroneous behavior in the presence
-of *-gnatd.U*.
+Access-to-subprogram types, however, are handled conservatively in many
+cases. This was not true in earlier versions of the compiler; you can use
+the *-gnatd.U* debug switch to revert to the old behavior if the new
+conservative behavior causes elaboration cycles. Here, 'conservative' means
+that if you do `P'Access` during elaboration, the compiler will normally
+assume that you might call `P` indirectly during elaboration, so it adds an
+implicit `pragma Elaborate_All` on the library unit containing `P`. The
+*-gnatd.U* switch is safe if you know there are no such calls. If the
+program worked before, it will continue to work with *-gnatd.U*. But beware
+that code modifications such as adding an indirect call can cause erroneous
+behavior in the presence of *-gnatd.U*.
+
+These implicit Elaborate_All pragmas are not added in all cases, because
+they cause elaboration cycles in certain common code patterns. If you want
+even more conservative handling of P'Access, you can use the *-gnatd.o*
+switch.
+
+See `debug.adb` for documentation on the *-gnatd...* debug switches.
 
 
 .. _Summary_of_Procedures_for_Elaboration_Control:
@@ -1564,7 +1569,7 @@ Summary of Procedures for Elaboration Control
 .. index:: Elaboration control
 
 First, compile your program with the default options, using none of
-the special elaboration control switches. If the binder successfully
+the special elaboration-control switches. If the binder successfully
 binds your program, then you can be confident that, apart from issues
 raised by the use of access-to-subprogram types and dynamic dispatching,
 the program is free of elaboration errors. If it is important that the

gcc/ada/doc/gnat_ugn/gnat_and_program_execution.rst

@@ -2605,6 +2605,14 @@ appropriate options.
   subprograms and helps the compiler to create a smaller executable for your
   program.
 
+  *gnatelim* is a project-aware tool.
+  (See :ref:`Using_Project_Files_with_GNAT_Tools` for a description of
+  the project-related switches but note that *gnatelim* does not support
+  the :samp:`-U`, :samp:`-U {main_unit}`, :samp:`--subdirs={dir}`, or
+  :samp:`--no_objects_dir` switches.)
+  The project file package that can specify
+  *gnatelim* switches is named ``Eliminate``.
+
   .. _About_gnatelim:
 
   About `gnatelim`

gcc/ada/doc/gnat_ugn/platform_specific_information.rst

@@ -156,6 +156,31 @@ For example on x86-linux::
    --           |
    --           +--- adalib
 
+.. only:: html or latex
+
+  .. image:: rtlibrary-structure.png
+
+.. only:: not (html or latex) 
+
+   ::
+
+                      $(target-dir)
+                     __/ /      \ \___
+             _______/   /        \    \_________________
+            /          /          \                     \
+           /          /            \                     \
+       ADAINCLUDE  ADALIB      rts-native             rts-sjlj
+          :          :            /    \                 /   \
+          :          :           /      \               /     \
+          :          :          /        \             /       \
+          :          :         /          \           /         \
+          +-------------> adainclude     adalib   adainclude   adalib
+                     :                     ^
+                     :                     :
+                     +---------------------+
+
+                     Run-Time Library Directory Structure
+          (Upper-case names and dotted/dashed arrows represent soft links)
 
 If the *rts-sjlj* library is to be selected on a permanent basis,
 these soft links can be modified with the following commands:
@@ -486,6 +511,57 @@ file will be created. This is particularly useful in networked
 environments where you may not have write access to some
 directories.
 
+Disabling Command Line Argument Expansion
+-----------------------------------------
+
+.. index:: Command Line Argument Expansion
+
+By default, an executable compiled for the **Windows** platform will do
+the following postprocessing on the arguments passed on the command
+line:
+
+* If the argument contains the characters ``*`` and/or ``?``, then
+  file expansion will be attempted. For example, if the current directory
+  contains :file:`a.txt` and :file:`b.txt`, then when calling::
+
+      $ my_ada_program *.txt
+
+  The following arguments will effectively be passed to the main program
+  (for example when using ``Ada.Command_Line.Argument``)::
+
+      Ada.Command_Line.Argument (1) -> "a.txt"
+      Ada.Command_Line.Argument (2) -> "b.txt"
+
+* Filename expansion can be disabled for a given argument by using single
+  quotes. Thus, calling::
+
+      $ my_ada_program '*.txt'
+
+  will result in::
+
+      Ada.Command_Line.Argument (1) -> "*.txt"
+
+Note that if the program is launched from a shell such as **Cygwin** **Bash**
+then quote removal might be performed by the shell.
+
+In some contexts it might be useful to disable this feature (for example if
+the program performs its own argument expansion). In order to do this, a C
+symbol needs to be defined and set to ``0``. You can do this by
+adding the following code fragment in one of your **Ada** units:
+
+.. code-block:: ada
+
+   Do_Argv_Expansion : Integer := 0;
+   pragma Export (C, Do_Argv_Expansion, "__gnat_do_argv_expansion");
+
+The results of previous examples will be respectively::
+
+   Ada.Command_Line.Argument (1) -> "*.txt"
+
+and::
+
+   Ada.Command_Line.Argument (1) -> "'*.txt'"
+
    
 .. _Mixed-Language_Programming_on_Windows:
 
@@ -1033,7 +1109,8 @@ Building DLLs with GNAT Project files
 .. index:: DLLs, building
 
 There is nothing specific to Windows in the build process.
-:ref:`Library_Projects`.
+See the *Library Projects* section in the *GNAT Project Manager*
+chapter of the *GPRbuild User's Guide*.
 
 Due to a system limitation, it is not possible under Windows to create threads
 when inside the `DllMain` routine which is used for auto-initialization
@@ -1149,7 +1226,9 @@ Note that a relocatable DLL stripped using the `strip`
 binutils tool will not be relocatable anymore. To build a DLL without
 debug information pass `-largs -s` to `gnatdll`. This
 restriction does not apply to a DLL built using a Library Project.
-See :ref:`Library_Projects`.
+See the *Library Projects* section in the *GNAT Project Manager*
+chapter of the *GPRbuild User's Guide*.
+
 
 .. Limitations_When_Using_Ada_DLLs_from Ada:
 

gcc/ada/doc/gnat_ugn/the_gnat_compilation_model.rst

@@ -872,7 +872,7 @@ File Name Krunching with `gnatkr`
 
 .. index:: ! gnatkr
 
-This chapter discusses the method used by the compiler to shorten
+This section discusses the method used by the compiler to shorten
 the default file names chosen for Ada units so that they do not
 exceed the maximum length permitted. It also describes the
 `gnatkr` utility that can be used to determine the result of
@@ -1052,7 +1052,7 @@ Renaming Files with `gnatchop`
 
 .. index:: ! gnatchop
 
-This chapter discusses how to handle files with multiple units by using
+This section discusses how to handle files with multiple units by using
 the `gnatchop` utility. This utility is also useful in renaming
 files to meet the standard GNAT default file naming conventions.
 
@@ -1550,8 +1550,10 @@ depend on a file that no longer exists. Such tools include
 *gprbuild*, *gnatmake*, and *gnatcheck*.
 
 If you are using project file, a separate mechanism is provided using
-project attributes, see :ref:`Specifying_Configuration_Pragmas` for more
-details.
+project attributes.
+
+.. --Comment:
+   See :ref:`Specifying_Configuration_Pragmas` for more details.
 
 
 .. _Generating_Object_Files:
@@ -1788,10 +1790,10 @@ GNAT and Libraries
 
 .. index:: Library building and using
 
-This chapter describes how to build and use libraries with GNAT, and also shows
+This section describes how to build and use libraries with GNAT, and also shows
 how to recompile the GNAT run-time library. You should be familiar with the
-Project Manager facility (:ref:`GNAT_Project_Manager`) before reading this
-chapter.
+Project Manager facility (see the *GNAT_Project_Manager* chapter of the
+*GPRbuild User's Guide*) before reading this chapter.
 
 .. _Introduction_to_Libraries_in_GNAT:
 
@@ -1849,7 +1851,8 @@ Building a library
 
 The easiest way to build a library is to use the Project Manager,
 which supports a special type of project called a *Library Project*
-(see :ref:`Library_Projects`).
+(see the *Library Projects* section in the *GNAT Project Manager*
+chapter of the *GPRbuild User's Guide*).
 
 A project is considered a library project, when two project-level attributes
 are defined in it: `Library_Name` and `Library_Dir`. In order to
@@ -1961,7 +1964,8 @@ Installing a library
 .. index:: GPR_PROJECT_PATH
 
 If you use project files, library installation is part of the library build
-process (:ref:`Installing_a_library_with_project_files`).
+process (see the *Installing a Library with Project Files* section of the
+*GNAT Project Manager* chapter of the *GPRbuild User's Guide*).
 
 When project files are not an option, it is also possible, but not recommended,
 to install the library so that the sources needed to use the library are on the
@@ -2137,11 +2141,13 @@ Building a Stand-alone Library
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 GNAT's Project facility provides a simple way of building and installing
-stand-alone libraries; see :ref:`Stand-alone_Library_Projects`.
+stand-alone libraries; see the *Stand-alone Library Projects* section
+in the *GNAT Project Manager* chapter of the *GPRbuild User's Guide*.
 To be a Stand-alone Library Project, in addition to the two attributes
 that make a project a Library Project (`Library_Name` and
-`Library_Dir`; see :ref:`Library_Projects`), the attribute
-`Library_Interface` must be defined.  For example:
+`Library_Dir`; see the *Library Projects* section in the
+*GNAT Project Manager* chapter of the *GPRbuild User's Guide*),
+the attribute `Library_Interface` must be defined.  For example:
 
 .. code-block:: gpr