gnat_rm.texi, [...]: Now automatically generated from sphinx in the doc directory.

2015-02-20  Arnaud Charlet  <charlet@adacore.com>                      

        * gnat_rm.texi, gnat_ugn.texi: Now automatically generated from
        sphinx in the doc directory.
        * doc: New directory containing sphinx versions of gnat_rm and gnat_ugn

From-SVN: r220837

gcc/ada/doc/Makefile

+# Makefile for Sphinx documentation
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = DOC_NAME=$* sphinx-build
+PAPER         =
+BUILDDIR      = build
+SOURCEDIR     = .
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) \
+		  -c $(SOURCEDIR)/share \
+		  -d $(BUILDDIR)/$*/doctrees \
+		  $(SOURCEDIR)
+DOC_LIST=gnat_rm gnat_ugn
+FMT_LIST=html pdf txt info
+
+.PHONY: help clean
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  DOC_NAME.html       to make standalone HTML files"
+	@echo "  DOC_NAME.pdf        to make LaTeX files and run them through pdflatex"
+	@echo "  DOC_NAME.txt        to make text files"
+	@echo "  DOC_NAME.texinfo    to make Texinfo files"
+	@echo "  DOC_NAME.info       to make info files"
+	@echo "  DOC_NAME.all        to build DOC_NAME for all previous formats"
+	@echo "  all                 to build all documentations in all formats"
+	@echo "  html-all            same as previous rule but only for HTML format"
+	@echo "  pdf-all             same as previous rule but only for PDF format"
+	@echo "  txt-all             same as previous rule but only for text format"
+	@echo "  texinfo-all         same as previous rule but only for texinfo format"
+	@echo "  info-all            same as previous rule but only for info format"
+	@echo ""
+	@echo "DOC_NAME should be a documentation name in the following list:"
+	@echo "  $(DOC_LIST)"
+	@echo ""
+	@echo "source and location can be overriden using SOURCEDIR and BUILDDIR variables"
+
+clean:
+	-rm -rf $(BUILDDIR)/*/html \
+		$(BUILDDIR)/*/pdf \
+		$(BUILDDIR)/*/txt \
+		$(BUILDDIR)/*/info
+
+%.html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/$*/html
+
+%.pdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/$*/pdf
+	cp $(SOURCEDIR)/share/sphinx.sty $(BUILDDIR)/$*/pdf
+	$(MAKE) -C $(BUILDDIR)/$*/pdf all-pdf LATEXOPTS="-interaction=nonstopmode"
+
+%.txt:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/$*/txt
+	$(MAKE) -C $(BUILDDIR)/$*/txt plaintext
+
+%.info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/$*/info
+	$(MAKE) -C $(BUILDDIR)/$*/info info
+
+%.texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/$*/texinfo
+
+html-all: $(foreach doc, $(DOC_LIST), $(doc).html)
+
+pdf-all: $(foreach doc, $(DOC_LIST), $(doc).pdf)
+
+txt-all: $(foreach doc, $(DOC_LIST), $(doc).txt)
+
+texinfo-all: $(foreach doc, $(DOC_LIST), $(doc).texinfo)
+
+%.all:
+	$(MAKE) $(foreach fmt, $(FMT_LIST), $*.$(fmt))
+
+all: $(foreach fmt, $(FMT_LIST), $(fmt).all)
+

gcc/ada/doc/gnat_rm.rst

+GNAT Reference Manual
+=====================
+
+*GNAT, The GNU Ada Development Environment*
+
+.. only:: PRO
+   
+   *GNAT Pro Edition*
+   
+   | Version |version|
+   | Date: |today|
+
+.. only:: GPL
+   
+   *GNAT GPL Edition*
+   
+   | Version |version|
+   | Date: |today|
+
+.. only:: FSF
+   
+   .. raw:: texinfo
+      
+      @include gcc-common.texi
+      GCC version @value{version-GCC}@*
+
+AdaCore
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being "GNAT Reference
+Manual", and with no Back-Cover Texts.  A copy of the license is
+included in the section entitled :ref:`gnu_fdl`.
+
+.. toctree::
+   :numbered:
+   :maxdepth: 3
+
+   gnat_rm/about_this_guide
+   gnat_rm/implementation_defined_pragmas
+   gnat_rm/implementation_defined_aspects
+   gnat_rm/implementation_defined_attributes
+   gnat_rm/standard_and_implementation_defined_restrictions
+   gnat_rm/implementation_advice
+   gnat_rm/implementation_defined_characteristics
+   gnat_rm/intrinsic_subprograms
+   gnat_rm/representation_clauses_and_pragmas
+   gnat_rm/standard_library_routines
+   gnat_rm/the_implementation_of_standard_i_o
+   gnat_rm/the_gnat_library
+   gnat_rm/interfacing_to_other_languages
+   gnat_rm/specialized_needs_annexes
+   gnat_rm/implementation_of_specific_ada_features
+   gnat_rm/implementation_of_ada_2012_features
+   gnat_rm/obsolescent_features
+   gnat_rm/compatibility_and_porting_guide
+
+.. raw:: latex
+
+   \appendix
+
+.. toctree::
+   :maxdepth: 3
+
+   share/gnu_free_documentation_license

gcc/ada/doc/gnat_rm/about_this_guide.rst

+.. _About_This_Guide:
+
+****************
+About This Guide
+****************
+
+.. only:: PRO
+
+   For ease of exposition, 'GNAT Pro' will be referred to simply as
+   'GNAT' in the remainder of this document.
+
+This manual contains useful information in writing programs using the
+GNAT compiler.  It includes information on implementation dependent
+characteristics of GNAT, including all the information required by
+Annex M of the Ada language standard.
+
+GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be
+invoked in Ada 83 compatibility mode.
+By default, GNAT assumes Ada 2012,
+but you can override with a compiler switch
+to explicitly specify the language version.
+(Please refer to the *GNAT User's Guide* for details on these switches.)
+Throughout this manual, references to 'Ada' without a year suffix
+apply to all the Ada versions of the language.
+
+Ada is designed to be highly portable.
+In general, a program will have the same effect even when compiled by
+different compilers on different platforms.
+However, since Ada is designed to be used in a
+wide variety of applications, it also contains a number of system
+dependent features to be used in interfacing to the external world.
+.. index:: Implementation-dependent features
+
+.. index:: Portability
+
+Note: Any program that makes use of implementation-dependent features
+may be non-portable.  You should follow good programming practice and
+isolate and clearly document any sections of your program that make use
+of these features in a non-portable manner.
+
+What This Reference Manual Contains
+===================================
+
+This reference manual contains the following chapters:
+
+* :ref:`Implementation_Defined_Pragmas`, lists GNAT implementation-dependent
+  pragmas, which can be used to extend and enhance the functionality of the
+  compiler.
+
+* :ref:`Implementation_Defined_Attributes`, lists GNAT
+  implementation-dependent attributes, which can be used to extend and
+  enhance the functionality of the compiler.
+
+* :ref:`Standard_and_Implementation_Defined_Restrictions`, lists GNAT
+  implementation-dependent restrictions, which can be used to extend and
+  enhance the functionality of the compiler.
+
+* :ref:`Implementation_Advice`, provides information on generally
+  desirable behavior which are not requirements that all compilers must
+  follow since it cannot be provided on all systems, or which may be
+  undesirable on some systems.
+
+* :ref:`Implementation_Defined_Characteristics`, provides a guide to
+  minimizing implementation dependent features.
+
+* :ref:`Intrinsic_Subprograms`, describes the intrinsic subprograms
+  implemented by GNAT, and how they can be imported into user
+  application programs.
+
+* :ref:`Representation_Clauses_and_Pragmas`, describes in detail the
+  way that GNAT represents data, and in particular the exact set
+  of representation clauses and pragmas that is accepted.
+
+* :ref:`Standard_Library_Routines`, provides a listing of packages and a
+  brief description of the functionality that is provided by Ada's
+  extensive set of standard library routines as implemented by GNAT.
+
+* :ref:`The_Implementation_of_Standard_I/O`, details how the GNAT
+  implementation of the input-output facilities.
+
+* :ref:`The_GNAT_Library`, is a catalog of packages that complement
+  the Ada predefined library.
+
+* :ref:`Interfacing_to_Other_Languages`, describes how programs
+  written in Ada using GNAT can be interfaced to other programming
+  languages.
+
+* :ref:`Specialized_Needs_Annexes`, describes the GNAT implementation of all
+  of the specialized needs annexes.
+
+* :ref:`Implementation_of_Specific_Ada_Features`, discusses issues related
+  to GNAT's implementation of machine code insertions, tasking, and several
+  other features.
+
+* :ref:`Implementation_of_Ada_2012_Features`, describes the status of the
+  GNAT implementation of the Ada 2012 language standard.
+
+* :ref:`Obsolescent_Features` documents implementation dependent features,
+  including pragmas and attributes, which are considered obsolescent, since
+  there are other preferred ways of achieving the same results. These
+  obsolescent forms are retained for backwards compatibility.
+
+* :ref:`Compatibility_and_Porting_Guide` presents some guidelines for
+  developing portable Ada code, describes the compatibility issues that
+  may arise between GNAT and other Ada compilation systems (including those
+  for Ada 83), and shows how GNAT can expedite porting applications
+  developed in other Ada environments.
+
+* :ref:`gnu_fdl` contains the license for this document.
+
+.. index:: Ada 95 Language Reference Manual
+
+.. index:: Ada 2005 Language Reference Manual
+
+This reference manual assumes a basic familiarity with the Ada 95 language, as
+described in the 
+:title:`International Standard ANSI/ISO/IEC-8652:1995`.
+It does not require knowledge of the new features introduced by Ada 2005,
+(officially known as `ISO/IEC 8652:1995 with Technical Corrigendum 1
+and Amendment 1`).
+Both reference manuals are included in the GNAT documentation
+package.
+
+Conventions
+===========
+.. index:: Conventions, typographical
+
+.. index:: Typographical conventions
+
+Following are examples of the typographical and graphic conventions used
+in this guide:
+
+* `Functions`, `utility program names`, `standard names`,
+  and `classes`.
+
+* `Option flags`
+
+* :file:`File names`
+
+* `Variables`
+
+* *Emphasis*
+
+* [optional information or parameters]
+
+* Examples are described by text
+
+  ::
+
+    and then shown this way.
+    
+* Commands that are entered by the user are shown as preceded by a prompt string
+  comprising the ``$`` character followed by a space.
+  
+Related Information
+===================
+
+See the following documents for further information on GNAT:
+
+* :title:`GNAT User's Guide for Native Platforms`,
+  which provides information on how to use the
+  GNAT development environment.
+
+* :title:`Ada 95 Reference Manual`, the Ada 95 programming language standard.
+
+* :title:`Ada 95 Annotated Reference Manual`, which is an annotated version
+  of the Ada 95 standard.  The annotations describe
+  detailed aspects of the design decision, and in particular contain useful
+  sections on Ada 83 compatibility.
+
+* :title:`Ada 2005 Reference Manual`, the Ada 2005 programming language standard.
+
+* :title:`Ada 2005 Annotated Reference Manual`, which is an annotated version
+  of the Ada 2005 standard.  The annotations describe
+  detailed aspects of the design decision.
+
+* :title:`Ada 2012 Reference Manual`, the Ada 2012 programming language standard.
+
+* :title:`DEC Ada, Technical Overview and Comparison on DIGITAL Platforms`,
+  which contains specific information on compatibility between GNAT and
+  DEC Ada 83 systems.
+
+* :title:`DEC Ada, Language Reference Manual`, part number AA-PYZAB-TK, which
+  describes in detail the pragmas and attributes provided by the DEC Ada 83
+  compiler system.

gcc/ada/doc/gnat_rm/interfacing_to_other_languages.rst

+.. _Interfacing_to_Other_Languages:
+
+******************************
+Interfacing to Other Languages
+******************************
+
+The facilities in Annex B of the Ada Reference Manual are fully
+implemented in GNAT, and in addition, a full interface to C++ is
+provided.
+
+.. _Interfacing_to_C:
+
+Interfacing to C
+================
+
+Interfacing to C with GNAT can use one of two approaches:
+
+* 
+  The types in the package `Interfaces.C` may be used.
+* 
+  Standard Ada types may be used directly.  This may be less portable to
+  other compilers, but will work on all GNAT compilers, which guarantee
+  correspondence between the C and Ada types.
+
+Pragma `Convention C` may be applied to Ada types, but mostly has no
+effect, since this is the default.  The following table shows the
+correspondence between Ada scalar types and the corresponding C types.
+
+
+======================== ==================================================================
+Ada Type                 C Type
+======================== ==================================================================
+``Integer``              ``int``
+``Short_Integer``        ``short``
+``Short_Short_Integer``  ``signed char``
+``Long_Integer``         ``long``
+``Long_Long_Integer``    ``long long``
+``Short_Float``          ``float``
+``Float``                ``float``
+``Long_Float``           ``double``
+``Long_Long_Float``      This is the longest floating-point type supported by the hardware.
+======================== ==================================================================
+
+Additionally, there are the following general correspondences between Ada
+and C types:
+
+* 
+  Ada enumeration types map to C enumeration types directly if pragma
+  `Convention C` is specified, which causes them to have int
+  length.  Without pragma `Convention C`, Ada enumeration types map to
+  8, 16, or 32 bits (i.e., C types `signed char`, `short`,
+  `int`, respectively) depending on the number of values passed.
+  This is the only case in which pragma `Convention C` affects the
+  representation of an Ada type.
+
+* 
+  Ada access types map to C pointers, except for the case of pointers to
+  unconstrained types in Ada, which have no direct C equivalent.
+
+* 
+  Ada arrays map directly to C arrays.
+
+* 
+  Ada records map directly to C structures.
+
+* 
+  Packed Ada records map to C structures where all members are bit fields
+  of the length corresponding to the ``type'Size`` value in Ada.
+
+.. _Interfacing_to_C++:
+
+Interfacing to C++
+==================
+
+The interface to C++ makes use of the following pragmas, which are
+primarily intended to be constructed automatically using a binding generator
+tool, although it is possible to construct them by hand.
+
+Using these pragmas it is possible to achieve complete
+inter-operability between Ada tagged types and C++ class definitions.
+See :ref:`Implementation_Defined_Pragmas`, for more details.
+
+*pragma CPP_Class ([Entity =>] `LOCAL_NAME`)*
+  The argument denotes an entity in the current declarative region that is
+  declared as a tagged or untagged record type. It indicates that the type
+  corresponds to an externally declared C++ class type, and is to be laid
+  out the same way that C++ would lay out the type.
+
+  Note: Pragma `CPP_Class` is currently obsolete. It is supported
+  for backward compatibility but its functionality is available
+  using pragma `Import` with `Convention` = `CPP`.
+
+
+*pragma CPP_Constructor ([Entity =>] `LOCAL_NAME`)*
+  This pragma identifies an imported function (imported in the usual way
+  with pragma `Import`) as corresponding to a C++ constructor.
+
+A few restrictions are placed on the use of the `Access` attribute
+in conjunction with subprograms subject to convention `CPP`: the
+attribute may be used neither on primitive operations of a tagged
+record type with convention `CPP`, imported or not, nor on
+subprograms imported with pragma `CPP_Constructor`.
+
+In addition, C++ exceptions are propagated and can be handled in an
+`others` choice of an exception handler. The corresponding Ada
+occurrence has no message, and the simple name of the exception identity
+contains ``Foreign_Exception``. Finalization and awaiting dependent
+tasks works properly when such foreign exceptions are propagated.
+
+It is also possible to import a C++ exception using the following syntax:
+
+
+::
+
+  LOCAL_NAME : exception;
+  pragma Import (Cpp,
+    [Entity =>] LOCAL_NAME,
+    [External_Name =>] static_string_EXPRESSION);
+  
+
+The `External_Name` is the name of the C++ RTTI symbol. You can then
+cover a specific C++ exception in an exception handler.
+
+.. _Interfacing_to_COBOL:
+
+Interfacing to COBOL
+====================
+
+Interfacing to COBOL is achieved as described in section B.4 of
+the Ada Reference Manual.
+
+.. _Interfacing_to_Fortran:
+
+Interfacing to Fortran
+======================
+
+Interfacing to Fortran is achieved as described in section B.5 of the
+Ada Reference Manual.  The pragma `Convention Fortran`, applied to a
+multi-dimensional array causes the array to be stored in column-major
+order as required for convenient interface to Fortran.
+
+.. _Interfacing_to_non-GNAT_Ada_code:
+
+Interfacing to non-GNAT Ada code
+================================
+
+It is possible to specify the convention `Ada` in a pragma
+`Import` or pragma `Export`.  However this refers to
+the calling conventions used by GNAT, which may or may not be
+similar enough to those used by some other Ada 83 / Ada 95 / Ada 2005
+compiler to allow interoperation.
+
+If arguments types are kept simple, and if the foreign compiler generally
+follows system calling conventions, then it may be possible to integrate
+files compiled by other Ada compilers, provided that the elaboration
+issues are adequately addressed (for example by eliminating the
+need for any load time elaboration).
+
+In particular, GNAT running on VMS is designed to
+be highly compatible with the DEC Ada 83 compiler, so this is one
+case in which it is possible to import foreign units of this type,
+provided that the data items passed are restricted to simple scalar
+values or simple record types without variants, or simple array
+types with fixed bounds.
+

gcc/ada/doc/gnat_rm/intrinsic_subprograms.rst

+.. _Intrinsic_Subprograms:
+
+*********************
+Intrinsic Subprograms
+*********************
+
+.. index:: Intrinsic Subprograms
+
+GNAT allows a user application program to write the declaration:
+
+
+.. code-block:: ada
+
+     pragma Import (Intrinsic, name);
+  
+
+providing that the name corresponds to one of the implemented intrinsic
+subprograms in GNAT, and that the parameter profile of the referenced
+subprogram meets the requirements.  This chapter describes the set of
+implemented intrinsic subprograms, and the requirements on parameter profiles.
+Note that no body is supplied; as with other uses of pragma Import, the
+body is supplied elsewhere (in this case by the compiler itself).  Note
+that any use of this feature is potentially non-portable, since the
+Ada standard does not require Ada compilers to implement this feature.
+
+.. _Intrinsic_Operators:
+
+Intrinsic Operators
+===================
+
+.. index:: Intrinsic operator
+
+All the predefined numeric operators in package Standard
+in `pragma Import (Intrinsic,..)`
+declarations.  In the binary operator case, the operands must have the same
+size.  The operand or operands must also be appropriate for
+the operator.  For example, for addition, the operands must
+both be floating-point or both be fixed-point, and the
+right operand for `"**"` must have a root type of
+`Standard.Integer'Base`.
+You can use an intrinsic operator declaration as in the following example:
+
+
+.. code-block:: ada
+
+     type Int1 is new Integer;
+     type Int2 is new Integer;
+
+     function "+" (X1 : Int1; X2 : Int2) return Int1;
+     function "+" (X1 : Int1; X2 : Int2) return Int2;
+     pragma Import (Intrinsic, "+");
+  
+
+This declaration would permit 'mixed mode' arithmetic on items
+of the differing types `Int1` and `Int2`.
+It is also possible to specify such operators for private types, if the
+full views are appropriate arithmetic types.
+
+.. _Compilation_Date:
+
+Compilation_Date
+================
+
+.. index:: Compilation_Date
+
+This intrinsic subprogram is used in the implementation of the
+library package `GNAT.Source_Info`.  The only useful use of the
+intrinsic import in this case is the one in this unit, so an
+application program should simply call the function
+`GNAT.Source_Info.Compilation_Date` to obtain the date of
+the current compilation (in local time format MMM DD YYYY).
+
+.. _Compilation_Time:
+
+Compilation_Time
+================
+
+.. index:: Compilation_Time
+
+This intrinsic subprogram is used in the implementation of the
+library package `GNAT.Source_Info`.  The only useful use of the
+intrinsic import in this case is the one in this unit, so an
+application program should simply call the function
+`GNAT.Source_Info.Compilation_Time` to obtain the time of
+the current compilation (in local time format HH:MM:SS).
+
+.. _Enclosing_Entity:
+
+Enclosing_Entity
+================
+
+.. index:: Enclosing_Entity
+
+This intrinsic subprogram is used in the implementation of the
+library package `GNAT.Source_Info`.  The only useful use of the
+intrinsic import in this case is the one in this unit, so an
+application program should simply call the function
+`GNAT.Source_Info.Enclosing_Entity` to obtain the name of
+the current subprogram, package, task, entry, or protected subprogram.
+
+.. _Exception_Information:
+
+Exception_Information
+=====================
+
+.. index:: Exception_Information'
+
+This intrinsic subprogram is used in the implementation of the
+library package `GNAT.Current_Exception`.  The only useful
+use of the intrinsic import in this case is the one in this unit,
+so an application program should simply call the function
+`GNAT.Current_Exception.Exception_Information` to obtain
+the exception information associated with the current exception.
+
+.. _Exception_Message:
+
+Exception_Message
+=================
+
+.. index:: Exception_Message
+
+This intrinsic subprogram is used in the implementation of the
+library package `GNAT.Current_Exception`.  The only useful
+use of the intrinsic import in this case is the one in this unit,
+so an application program should simply call the function
+`GNAT.Current_Exception.Exception_Message` to obtain
+the message associated with the current exception.
+
+.. _Exception_Name:
+
+Exception_Name
+==============
+
+.. index:: Exception_Name
+
+This intrinsic subprogram is used in the implementation of the
+library package `GNAT.Current_Exception`.  The only useful
+use of the intrinsic import in this case is the one in this unit,
+so an application program should simply call the function
+`GNAT.Current_Exception.Exception_Name` to obtain
+the name of the current exception.
+
+.. _File:
+
+File
+====
+
+.. index:: File
+
+This intrinsic subprogram is used in the implementation of the
+library package `GNAT.Source_Info`.  The only useful use of the
+intrinsic import in this case is the one in this unit, so an
+application program should simply call the function
+`GNAT.Source_Info.File` to obtain the name of the current
+file.
+
+.. _Line:
+
+Line
+====
+
+.. index:: Line
+
+This intrinsic subprogram is used in the implementation of the
+library package `GNAT.Source_Info`.  The only useful use of the
+intrinsic import in this case is the one in this unit, so an
+application program should simply call the function
+`GNAT.Source_Info.Line` to obtain the number of the current
+source line.
+
+.. _Shifts_and_Rotates:
+
+Shifts and Rotates
+==================
+
+.. index:: Shift_Left
+
+.. index:: Shift_Right
+
+.. index:: Shift_Right_Arithmetic
+
+.. index:: Rotate_Left
+
+.. index:: Rotate_Right
+
+In standard Ada, the shift and rotate functions are available only
+for the predefined modular types in package `Interfaces`.  However, in
+GNAT it is possible to define these functions for any integer
+type (signed or modular), as in this example:
+
+
+.. code-block:: ada
+
+     function Shift_Left
+       (Value  : T;
+        Amount : Natural) return T;
+  
+
+The function name must be one of
+Shift_Left, Shift_Right, Shift_Right_Arithmetic, Rotate_Left, or
+Rotate_Right. T must be an integer type. T'Size must be
+8, 16, 32 or 64 bits; if T is modular, the modulus
+must be 2**8, 2**16, 2**32 or 2**64.
+The result type must be the same as the type of `Value`.
+The shift amount must be Natural.
+The formal parameter names can be anything.
+
+A more convenient way of providing these shift operators is to use
+the Provide_Shift_Operators pragma, which provides the function declarations
+and corresponding pragma Import's for all five shift functions.
+
+.. _Source_Location:
+
+Source_Location
+===============
+
+.. index:: Source_Location
+
+This intrinsic subprogram is used in the implementation of the
+library routine `GNAT.Source_Info`.  The only useful use of the
+intrinsic import in this case is the one in this unit, so an
+application program should simply call the function
+`GNAT.Source_Info.Source_Location` to obtain the current
+source file location.
+

gcc/ada/doc/gnat_rm/obsolescent_features.rst

+.. _Obsolescent_Features:
+
+********************
+Obsolescent Features
+********************
+
+This chapter describes features that are provided by GNAT, but are
+considered obsolescent since there are preferred ways of achieving
+the same effect. These features are provided solely for historical
+compatibility purposes.
+
+.. _pragma_No_Run_Time:
+
+pragma No_Run_Time
+==================
+
+The pragma `No_Run_Time` is used to achieve an affect similar
+to the use of the "Zero Foot Print" configurable run time, but without
+requiring a specially configured run time. The result of using this
+pragma, which must be used for all units in a partition, is to restrict
+the use of any language features requiring run-time support code. The
+preferred usage is to use an appropriately configured run-time that
+includes just those features that are to be made accessible.
+
+.. _pragma_Ravenscar:
+
+pragma Ravenscar
+================
+
+The pragma `Ravenscar` has exactly the same effect as pragma
+`Profile (Ravenscar)`. The latter usage is preferred since it
+is part of the new Ada 2005 standard.
+
+.. _pragma_Restricted_Run_Time:
+
+pragma Restricted_Run_Time
+==========================
+
+The pragma `Restricted_Run_Time` has exactly the same effect as
+pragma `Profile (Restricted)`. The latter usage is
+preferred since the Ada 2005 pragma `Profile` is intended for
+this kind of implementation dependent addition.
+
+.. _pragma_Task_Info:
+
+pragma Task_Info
+================
+
+The functionality provided by pragma `Task_Info` is now part of the
+Ada language. The `CPU` aspect and the package
+`System.Multiprocessors` offer a less system-dependent way to specify
+task affinity or to query the number of processsors.
+
+Syntax
+
+.. code-block:: ada
+
+  pragma Task_Info (EXPRESSION);
+  
+This pragma appears within a task definition (like pragma
+`Priority`) and applies to the task in which it appears.  The
+argument must be of type `System.Task_Info.Task_Info_Type`.
+The `Task_Info` pragma provides system dependent control over
+aspects of tasking implementation, for example, the ability to map
+tasks to specific processors.  For details on the facilities available
+for the version of GNAT that you are using, see the documentation
+in the spec of package System.Task_Info in the runtime
+library.
+
+.. _package_System_Task_Info:
+
+package System.Task_Info (:file:`s-tasinf.ads`)
+===============================================
+
+This package provides target dependent functionality that is used
+to support the `Task_Info` pragma. The predefined Ada package
+`System.Multiprocessors` and the `CPU` aspect now provide a
+standard replacement for GNAT's `Task_Info` functionality.
+
+.. raw:: latex
+
+    \appendix

gcc/ada/doc/gnat_rm/specialized_needs_annexes.rst

+.. _Specialized_Needs_Annexes:
+
+*************************
+Specialized Needs Annexes
+*************************
+
+Ada 95, Ada 2005, and Ada 2012 define a number of Specialized Needs Annexes, which are not
+required in all implementations.  However, as described in this chapter,
+GNAT implements all of these annexes:
+
+*Systems Programming (Annex C)*
+  The Systems Programming Annex is fully implemented.
+
+
+*Real-Time Systems (Annex D)*
+  The Real-Time Systems Annex is fully implemented.
+
+
+*Distributed Systems (Annex E)*
+  Stub generation is fully implemented in the GNAT compiler.  In addition,
+  a complete compatible PCS is available as part of the GLADE system,
+  a separate product.  When the two
+  products are used in conjunction, this annex is fully implemented.
+
+
+*Information Systems (Annex F)*
+  The Information Systems annex is fully implemented.
+
+
+*Numerics (Annex G)*
+  The Numerics Annex is fully implemented.
+
+
+*Safety and Security / High-Integrity Systems (Annex H)*
+  The Safety and Security Annex (termed the High-Integrity Systems Annex
+  in Ada 2005) is fully implemented.
+

gcc/ada/doc/gnat_ugn.rst

+GNAT User's Guide for Native Platforms
+======================================
+
+*GNAT, The GNU Ada Development Environment*
+
+.. only:: PRO
+
+   *GNAT Pro Edition*
+
+   | Version |version|
+   | Date: |today|
+
+.. only:: GPL
+
+   *GNAT GPL Edition*
+
+   | Version |version|
+   | Date: |today|
+
+.. only:: FSF
+
+   .. raw:: texinfo
+
+      @include gcc-common.texi
+      GCC version @value{version-GCC}@*
+
+AdaCore
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover Texts being
+"GNAT User's Guide for Native Platforms",
+and with no Back-Cover Texts.  A copy of the license is
+included in the section entitled :ref:`gnu_fdl`.
+
+.. toctree::
+   :maxdepth: 3
+   :numbered:
+
+   gnat_ugn/about_this_guide
+   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
+
+.. raw:: latex
+
+   \appendix
+
+.. toctree::
+   :maxdepth: 3
+
+   A. Platform-Specific Information <gnat_ugn/platform_specific_information>
+   B. Example of Binder Output <gnat_ugn/example_of_binder_output>
+   C. Elaboration Order Handling in GNAT <gnat_ugn/elaboration_order_handling_in_gnat>
+   D. Inline Assembler <gnat_ugn/inline_assembler>
+   E. GNU Free Documentation License <share/gnu_free_documentation_license>
+
+

gcc/ada/doc/gnat_ugn/about_this_guide.rst

+.. _About_This_Guide:
+
+About This Guide
+~~~~~~~~~~~~~~~~
+
+.. only:: PRO
+
+   For ease of exposition, 'GNAT Pro' will be referred to simply as
+   'GNAT' in the remainder of this document.
+
+This guide describes the use of GNAT,
+a compiler and software development
+toolset for the full Ada programming language.
+It documents the features of the compiler and tools, and explains
+how to use them to build Ada applications.
+
+GNAT implements Ada 95, Ada 2005 and Ada 2012, and it may also be
+invoked in Ada 83 compatibility mode.
+By default, GNAT assumes Ada 2012, but you can override with a
+compiler switch (:ref:`Compiling_Different_Versions_of_Ada`)
+to explicitly specify the language version.
+Throughout this manual, references to 'Ada' without a year suffix
+apply to all Ada 95/2005/2012 versions of the language.
+
+What This Guide Contains
+========================
+
+This guide contains the following chapters:
+
+* :ref:`Getting_Started_with_GNAT` describes how to get started compiling
+  and running Ada programs with the GNAT Ada programming environment.
+
+* :ref:`The_GNAT_Compilation_Model` describes the compilation model used
+  by GNAT.
+
+* :ref:`Building_Executable_Programs_With_GNAT` describes how to use the
+  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
+
+* :ref:`GNAT_and_Program_Execution` covers a number of topics related to
+  running, debugging, and tuning the performace of programs developed
+  with GNAT
+
+Appendices cover several additional topics:
+  
+* :ref:`Platform_Specific_Information` describes the different run-time
+  library implementations and also presents information on how to use
+  GNAT on several specific platforms
+  
+* :ref:`Example_of_Binder_Output_File` shows the source code for the binder
+  output file for a sample program.
+
+* :ref:`Elaboration_Order_Handling_in_GNAT` describes how GNAT helps
+  you deal with elaboration order issues.
+
+* :ref:`Inline_Assembler` shows how to use the inline assembly facility
+  in an Ada program.
+
+
+
+What You Should Know before Reading This Guide
+==============================================
+
+.. index:: Ada 95 Language Reference Manual
+
+.. index:: Ada 2005 Language Reference Manual
+
+This guide assumes a basic familiarity with the Ada 95 language, as
+described in the International Standard ANSI/ISO/IEC-8652:1995, January
+1995.
+It does not require knowledge of the features introduced by Ada 2005
+or Ada 2012.
+Reference manuals for Ada 95, Ada 2005, and Ada 2012 are included in
+the GNAT documentation package.
+
+
+Related Information
+===================
+
+For further information about Ada and related tools, please refer to the
+following documents:
+
+* :title:`Ada 95 Reference Manual`, :title:`Ada 2005 Reference Manual`, and
+  :title:`Ada 2012 Reference Manual`, which contain reference
+  material for the several revisions of the Ada language standard.
+
+* :title:`GNAT Reference_Manual`, which contains all reference material for the GNAT
+  implementation of Ada.
+
+* :title:`Using the GNAT Programming Studio`, which describes the GPS
+  Integrated Development Environment.
+
+* :title:`GNAT Programming Studio Tutorial`, which introduces the
+  main GPS features through examples.
+
+* :title:`Debugging with GDB`,
+  for all details on the use of the GNU source-level debugger.
+
+* :title:`GNU Emacs Manual`,
+  for full information on the extensible editor and programming
+  environment Emacs.
+
+
+A Note to Readers of Previous Versions of the Manual
+====================================================
+
+In early 2015 the GNAT manuals were transitioned to the
+reStructuredText (rst) / Sphinx documentation generator technology.
+During that process the :title:`GNAT User's Guide` was reorganized
+so that related topics would be described together in the same chapter
+or appendix.  Here's a summary of the major changes realized in
+the new document structure.
+
+* :ref:`The_GNAT_Compilation_Model` has been extended so that it now covers
+  the following material:
+
+  - The `gnatname`, `gnatkr`, and `gnatchop` tools
+  - :ref:`Configuration_Pragmas`
+  - :ref:`GNAT_and_Libraries`
+  - :ref:`Conditional_Compilation` including :ref:`Preprocessing_with_gnatprep`
+    and :ref:`Integrated_Preprocessing`
+  - :ref:`Generating_Ada_Bindings_for_C_and_C++_headers`
+  - :ref:`Using_GNAT_Files_with_External_Tools`
+
+* :ref:`Building_Executable_Programs_With_GNAT` is a new chapter consolidating
+  the following content:
+
+  - :ref:`The_GNAT_Make_Program_gnatmake`
+  - :ref:`Compiling_with_GCC`
+  - :ref:`Binding_with_gnatbind`
+  - :ref:`Linking_with_gnatlink`
+  - :ref:`Using_the_GNU_make_Utility`
+
+* :ref:`GNAT_Utility_Programs` is a new chapter consolidating the information about several
+  GNAT tools:
+  
+  .. only:: PRO or GPL
+
+    - :ref:`The_File_Cleanup_Utility_gnatclean`
+    - :ref:`The_GNAT_Library_Browser_gnatls`
+    - :ref:`The_Cross-Referencing_Tools_gnatxref_and_gnatfind`
+    - :ref:`The_Ada_to_HTML_Converter_gnathtml`
+    - :ref:`The_Ada-to-XML_Converter_gnat2xml`
+    - :ref:`The_Program_Property_Verifier_gnatcheck`
+    - :ref:`The_GNAT_Metrics_Tool_gnatmetric`
+    - :ref:`The_GNAT_Pretty-Printer_gnatpp`
+    - :ref:`The_Body_Stub_Generator_gnatstub`
+    - :ref:`The_Unit_Test_Generator_gnattest`
+  
+  .. only:: FSF
+
+    - :ref:`The_File_Cleanup_Utility_gnatclean`
+    - :ref:`The_GNAT_Library_Browser_gnatls`
+    - :ref:`The_Cross-Referencing_Tools_gnatxref_and_gnatfind`
+    - :ref:`The_Ada_to_HTML_Converter_gnathtml`
+
+* :ref:`GNAT_and_Program_Execution` is a new chapter consolidating the following:
+
+  - :ref:`Running_and_Debugging_Ada_Programs`
+  - :ref:`Code_Coverage_and_Profiling`
+  - :ref:`Improving_Performance`
+  - :ref:`Overflow Check Handling in GNAT <Overflow_Check_Handling_in_GNAT>`
+  - :ref:`Performing Dimensionality Analysis in GNAT <Performing_Dimensionality_Analysis_in_GNAT>`
+  - :ref:`Stack_Related_Facilities`
+  - :ref:`Memory_Management_Issues`
+
+* :ref:`Platform_Specific_Information` is a new appendix consolidating the following:
+
+  - :ref:`Run_Time_Libraries`
+  - :ref:`Microsoft_Windows_Topics`
+  - :ref:`Mac_OS_Topics`
+
+* The `Compatibility and Porting Guide` appendix has been moved to the
+  :title:`GNAT Reference Manual`. It now includes a section
+  `Writing Portable Fixed-Point Declarations` which was previously
+  a separate chapter in the :title:`GNAT User's Guide`.
+
+
+Conventions
+===========
+.. index:: Conventions, typographical
+
+.. index:: Typographical conventions
+
+Following are examples of the typographical and graphic conventions used
+in this guide:
+
+* `Functions`, `utility program names`, `standard names`,
+  and `classes`.
+
+* `Option flags`
+
+* :file:`File names`
+
+* `Variables`
+
+* *Emphasis*
+
+* [optional information or parameters]
+
+* Examples are described by text
+
+  ::
+
+    and then shown this way.
+    
+* Commands that are entered by the user are shown as preceded by a prompt string
+  comprising the ``$`` character followed by a space.
+
+* Full file names are shown with the '/' character
+  as the directory separator; e.g., :file:`parent-dir/subdir/myfile.adb`.
+  If you are using GNAT on a Windows platform, please note that
+  the '\\' character should be used instead.
+

gcc/ada/doc/gnat_ugn/getting_started_with_gnat.rst

+.. _Getting_Started_with_GNAT:
+
+*************************
+Getting Started with GNAT
+*************************
+
+This chapter describes how to use GNAT's command line interface to build
+executable Ada programs.
+On most platforms a visually oriented Integrated Development Environment
+is also available, the GNAT Programming Studio (GPS).
+GPS offers a graphical "look and feel", support for development in
+other programming languages, comprehensive browsing features, and
+many other capabilities.
+For information on GPS please refer to
+:title:`Using the GNAT Programming Studio`.
+
+
+.. _Running_GNAT:
+
+Running GNAT
+============
+
+Three steps are needed to create an executable file from an Ada source
+file:
+
+*   The source file(s) must be compiled.
+*   The file(s) must be bound using the GNAT binder.
+*   All appropriate object files must be linked to produce an executable.
+
+All three steps are most commonly handled by using the *gnatmake*
+utility program that, given the name of the main program, automatically
+performs the necessary compilation, binding and linking steps.
+
+.. _Running_a_Simple_Ada_Program:
+
+Running a Simple Ada Program
+============================
+
+Any text editor may be used to prepare an Ada program.
+(If Emacs is used, the optional Ada mode may be helpful in laying out the
+program.)
+The program text is a normal text file. We will assume in our initial
+example that you have used your editor to prepare the following
+standard format text file:
+
+
+.. code-block:: ada
+
+  with Ada.Text_IO; use Ada.Text_IO;
+  procedure Hello is
+  begin
+     Put_Line ("Hello WORLD!");
+  end Hello;
+
+This file should be named :file:`hello.adb`.
+With the normal default file naming conventions, GNAT requires
+that each file
+contain a single compilation unit whose file name is the
+unit name,
+with periods replaced by hyphens; the
+extension is :file:`ads` for a
+spec and :file:`adb` for a body.
+You can override this default file naming convention by use of the
+special pragma `Source_File_Name` (for further information please
+see :ref:`Using_Other_File_Names`).
+Alternatively, if you want to rename your files according to this default
+convention, which is probably more convenient if you will be using GNAT
+for all your compilations, then the `gnatchop` utility
+can be used to generate correctly-named source files
+(see :ref:`Renaming_Files_with_gnatchop`).
+
+You can compile the program using the following command (`$` is used
+as the command prompt in the examples in this document):
+
+.. code-block:: sh
+
+  $ gcc -c hello.adb
+  
+
+*gcc* is the command used to run the compiler. This compiler is
+capable of compiling programs in several languages, including Ada and
+C. It assumes that you have given it an Ada program if the file extension is
+either :file:`.ads` or :file:`.adb`, and it will then call
+the GNAT compiler to compile the specified file.
+
+The :option:`-c` switch is required. It tells *gcc* to only do a
+compilation. (For C programs, *gcc* can also do linking, but this
+capability is not used directly for Ada programs, so the :option:`-c`
+switch must always be present.)
+
+This compile command generates a file
+:file:`hello.o`, which is the object
+file corresponding to your Ada program. It also generates
+an 'Ada Library Information' file :file:`hello.ali`,
+which contains additional information used to check
+that an Ada program is consistent.
+To build an executable file,
+use `gnatbind` to bind the program
+and *gnatlink* to link it. The
+argument to both `gnatbind` and *gnatlink* is the name of the
+:file:`ALI` file, but the default extension of :file:`.ali` can
+be omitted. This means that in the most common case, the argument
+is simply the name of the main program:
+
+.. code-block:: sh
+
+  $ gnatbind hello
+  $ gnatlink hello
+
+A simpler method of carrying out these steps is to use *gnatmake*,
+a master program that invokes all the required
+compilation, binding and linking tools in the correct order. In particular,
+*gnatmake* automatically recompiles any sources that have been
+modified since they were last compiled, or sources that depend
+on such modified sources, so that 'version skew' is avoided.
+
+.. index:: Version skew (avoided by *gnatmake*)
+
+.. code-block:: sh
+
+  $ gnatmake hello.adb
+
+The result is an executable program called :file:`hello`, which can be
+run by entering:
+
+.. code-block:: sh
+
+  $ hello
+
+assuming that the current directory is on the search path
+for executable programs.
+
+and, if all has gone well, you will see::
+
+  Hello WORLD!
+
+appear in response to this command.
+
+.. _Running_a_Program_with_Multiple_Units:
+
+Running a Program with Multiple Units
+=====================================
+
+Consider a slightly more complicated example that has three files: a
+main program, and the spec and body of a package:
+
+
+.. code-block:: ada
+
+  package Greetings is
+     procedure Hello;
+     procedure Goodbye;
+  end Greetings;
+
+  with Ada.Text_IO; use Ada.Text_IO;
+  package body Greetings is
+     procedure Hello is
+     begin
+        Put_Line ("Hello WORLD!");
+     end Hello;
+
+     procedure Goodbye is
+     begin
+        Put_Line ("Goodbye WORLD!");
+     end Goodbye;
+  end Greetings;
+
+  with Greetings;
+  procedure Gmain is
+  begin
+     Greetings.Hello;
+     Greetings.Goodbye;
+  end Gmain;
+
+Following the one-unit-per-file rule, place this program in the
+following three separate files:
+
+
+
+*greetings.ads*
+  spec of package `Greetings`
+
+
+*greetings.adb*
+  body of package `Greetings`
+
+
+*gmain.adb*
+  body of main program
+
+To build an executable version of
+this program, we could use four separate steps to compile, bind, and link
+the program, as follows:
+
+.. code-block:: sh
+
+  $ gcc -c gmain.adb
+  $ gcc -c greetings.adb
+  $ gnatbind gmain
+  $ gnatlink gmain
+
+Note that there is no required order of compilation when using GNAT.
+In particular it is perfectly fine to compile the main program first.
+Also, it is not necessary to compile package specs in the case where
+there is an accompanying body; you only need to compile the body. If you want
+to submit these files to the compiler for semantic checking and not code
+generation, then use the :option:`-gnatc` switch:
+
+.. code-block:: sh
+
+  $ gcc -c greetings.ads -gnatc
+
+Although the compilation can be done in separate steps as in the
+above example, in practice it is almost always more convenient
+to use the *gnatmake* tool. All you need to know in this case
+is the name of the main program's source file. The effect of the above four
+commands can be achieved with a single one:
+
+.. code-block:: sh
+
+  $ gnatmake gmain.adb
+
+In the next section we discuss the advantages of using *gnatmake* in
+more detail.
+
+.. _Using_the_gnatmake_Utility:
+
+Using the *gnatmake* Utility
+============================
+
+If you work on a program by compiling single components at a time using
+*gcc*, you typically keep track of the units you modify. In order to
+build a consistent system, you compile not only these units, but also any
+units that depend on the units you have modified.
+For example, in the preceding case,
+if you edit :file:`gmain.adb`, you only need to recompile that file. But if
+you edit :file:`greetings.ads`, you must recompile both
+:file:`greetings.adb` and :file:`gmain.adb`, because both files contain
+units that depend on :file:`greetings.ads`.
+
+*gnatbind* will warn you if you forget one of these compilation
+steps, so that it is impossible to generate an inconsistent program as a
+result of forgetting to do a compilation. Nevertheless it is tedious and
+error-prone to keep track of dependencies among units.
+One approach to handle the dependency-bookkeeping is to use a
+makefile. However, makefiles present maintenance problems of their own:
+if the dependencies change as you change the program, you must make
+sure that the makefile is kept up-to-date manually, which is also an
+error-prone process.
+
+The *gnatmake* utility takes care of these details automatically.
+Invoke it using either one of the following forms:
+
+.. code-block:: sh
+
+  $ gnatmake gmain.adb
+  $ gnatmake gmain
+
+The argument is the name of the file containing the main program;
+you may omit the extension. *gnatmake*
+examines the environment, automatically recompiles any files that need
+recompiling, and binds and links the resulting set of object files,
+generating the executable file, :file:`gmain`.
+In a large program, it
+can be extremely helpful to use *gnatmake*, because working out by hand
+what needs to be recompiled can be difficult.
+
+Note that *gnatmake* takes into account all the Ada rules that
+establish dependencies among units. These include dependencies that result
+from inlining subprogram bodies, and from
+generic instantiation. Unlike some other
+Ada make tools, *gnatmake* does not rely on the dependencies that were
+found by the compiler on a previous compilation, which may possibly
+be wrong when sources change. *gnatmake* determines the exact set of
+dependencies from scratch each time it is run.
+

gcc/ada/doc/share/ada_pygments.py

+"""Alternate Ada and Project Files parsers for Sphinx/Rest"""
+
+import re
+from pygments.lexer import RegexLexer, bygroups
+from pygments.token import Text, Comment, Operator, Keyword, Name, String, \
+    Number, Punctuation
+
+
+def get_lexer_tokens(tag_highlighting=False, project_support=False):
+    """Return the tokens needed for RegexLexer
+
+    :param tag_highlighting: if True we support tag highlighting. See
+        AdaLexerWithTags documentation
+    :type tag_highlighting: bool
+    :param project_support: if True support additional keywors associated
+        with project files.
+    :type project_support:  bool
+
+    :return: a dictionary following the structure required by RegexLexer
+    :rtype: dict
+    """
+    if project_support:
+        project_pattern = r'project\s+|'
+        project_pattern2 = r'project|'
+    else:
+        project_pattern = r''
+        project_pattern2 = r''
+
+    result = {
+        'root': [
+            # Comments
+            (r'--.*$', Comment),
+            # Character literal
+            (r"'.'", String.Char),
+            # Strings
+            (r'"[^"]*"', String),
+            # Numeric
+            # Based literal
+            (r'[0-9][0-9_]*#[0-9a-f][0-9a-f_]*#(E[\+-]?[0-9][0-9_]*)?',
+             Number.Integer),
+            (r'[0-9][0-9_]*#[0-9a-f][0-9a-f_]*'
+             r'\.[0-9a-f][0-9a-f_]*#(E[\+-]?[0-9][0-9_]*)?', Number.Float),
+            # Decimal literal
+            (r'[0-9][0-9_]*\.[0-9][0-9_](E[\+-]?[0-9][0-9_]*)?', Number.Float),
+            (r'[0-9][0-9_]*(E[\+-]?[0-9][0-9_]*)?', Number.Integer),
+            # Match use and with statements
+            # The first part of the pattern is be sure we don't match
+            # for/use constructs.
+            (r'(\n\s*|;\s*)(with|use)(\s+[\w\.]+)',
+             bygroups(Punctuation, Keyword.Reserved, Name.Namespace)),
+            # Match procedure, package and function declarations
+            (r'end\s+(if|loop|record)', Keyword),
+            (r'(package(?:\s+body)?\s+|' + project_pattern +
+             r'function\s+|end\s+|procedure\s+)([\w\.]+)',
+             bygroups(Keyword, Name.Function)),
+            # Ada 2012 standard attributes, GNAT specific ones and
+            # Spark 2014 ones ('Update and 'Loop_Entry)
+            # (reversed order to avoid having for
+            #  example Max before Max_Alignment_For_Allocation).
+            (r'\'(Write|Width|Wide_Width|Wide_Wide_Width|Wide_Wide_Value|'
+             r'Wide_Wide_Image|Wide_Value|Wide_Image|Word_Size|Wchar_T_Size|'
+             r'Version|Value_Size|Value|Valid_Scalars|VADS_Size|Valid|Val|'
+             r'Update|Unrestricted_Access|Universal_Literal_String|'
+             r'Unconstrained_Array|Unchecked_Access|Unbiased_Rounding|'
+             r'UET_Address|Truncation|Type_Class|To_Address|Tick|Terminated|'
+             r'Target_Name|Tag|System_Allocator_Alignment|Succ|Stub_Type|'
+             r'Stream_Size|Storage_Unit|Storage_Size|Storage_Pool|Small|Size|'
+             r'Simple_Storage_Pool|Signed_Zeros|Scaling|Scale|'
+             r'Scalar_Storage_Order|Safe_Last|Safe_Large|Safe_First|'
+             r'Safe_Emax|Rounding|Round|Result|Remainder|Ref|Read|'
+             r'Range_Length|Range|Priority|Pred|'
+             r'Position|Pos|Pool_Address|Passed_By_Reference|Partition_Id|'
+             r'Overlaps_Storage|Output|Old|Object_Size|Null_Parameter|Modulus|'
+             r'Model_Small|Model_Mantissa|Model_Epsilon|Model_Emin|Model|Mod|'
+             r'Min|Mechanism_Code|Maximum_Alignment|'
+             r'Max_Size_In_Storage_Elements|Max_Priority|'
+             r'Max_Interrupt_Priority|Max_Alignment_For_Allocation|'
+             r'Max|Mantissa|Machine_Size|Machine_Rounds|Machine_Rounding|'
+             r'Machine_Radix|Machine_Overflows|Machine_Mantissa|Machine_Emin|'
+             r'Machine_Emax|Machine|Loop_Entry|Length|Length|Leading_Part|'
+             r'Last_Valid|Last_Bit|Last|Large|Invalid_Value|Integer_Value|'
+             r'Input|Image|Img|Identity|Has_Same_Storage|Has_Discriminants|'
+             r'Has_Access_Values|Fraction|Fore|Floor|Fixed_Value|First_Valid|'
+             r'First_Bit|First|External_Tag|Exponent|Epsilon|Enum_Val|'
+             r'Enum_Rep|Enabled|Emax|Elaborated|Elab_Subp_Body|Elab_Spec|'
+             r'Elab_Body|Descriptor_Size|Digits|Denorm|Delta|Definite|'
+             r'Default_Bit_Order|Count|Copy_Sign|Constrained|'
+             r'Compose|Component_Size|Compiler_Version|Code_Address|Class|'
+             r'Ceiling|Caller|Callable|Body_Version|Bit_Order|Bit_Position|'
+             r'Bit|Base|Asm_Output|Asm_Input|Alignment|Aft|Adjacent|'
+             r'Address_Size|Address|Access|Abort_Signal|AST_Entry)',
+             Name.Attribute),
+            # All Ada2012 reserved words
+            (r'(abort|abstract|abs|accept|access|aliased|all|and|array|at|'
+             r'begin|body|case|constant|declare|delay|delta|digits|do|'
+             r'else|elsif|end|entry|exception|exit|for|function|generic|goto|'
+             r'if|interface|in|is|limited|loop|mod|new|not|null|'
+             r'of|or|others|out|overriding|' + project_pattern2 +
+             r'package|pragma|private|procedure|protected|'
+             r'raise|range|record|rem|renames|requeue|return|reverse|'
+             r'select|separate|some|subtype|synchronized|'
+             r'tagged|task|terminate|then|type|until|use|when|while|with|xor'
+             r')([\s;,])',
+             bygroups(Keyword.Reserved, Punctuation)),
+            # Two characters operators
+            (r'=>|\.\.|\*\*|:=|/=|>=|<=|<<|>>|<>', Operator),
+            # One character operators
+            (r'&|\'|\(|\)|\*|\+|-|\.|/|:|<|=|>|\|', Operator),
+            (r',|;', Punctuation),
+            # Spaces
+            (r'\s+', Text),
+            # Builtin values
+            (r'False|True', Keyword.Constant),
+            # Identifiers
+            (r'[\w\.]+', Name)], }
+
+    # Insert tag highlighting before identifiers
+    if tag_highlighting:
+        result['root'].insert(-1, (r'\[[\w ]*\]', Name.Tag))
+
+    return result
+
+
+class AdaLexer(RegexLexer):
+    """Alternate Pygments lexer for Ada source code and project files
+
+    The default pygments lexer always fails causing disabling of syntax
+    highlighting in Sphinx. This lexer is simpler but safer.
+
+    In order to use this lexer in your Sphinx project add the following
+    code at the end of your conf.py
+
+    .. code-block:: python
+
+        import gnatpython.ada_pygments
+
+        def setup(app):
+            app.add_lexer('ada', gnatpython.ada_pygments.AdaLexer())
+
+    """
+    name = 'Ada'
+    aliases = ['ada', 'ada83', 'ada95', 'ada2005', 'ada2012']
+    filenames = ['*.adb', '*.ads', '*.ada']
+    mimetypes = ['text/x-ada']
+
+    flags = re.MULTILINE | re.I  # Ignore case
+
+    tokens = get_lexer_tokens()
+
+
+class TaggedAdaLexer(AdaLexer):
+    """Alternate Pygments lexer for Ada source code with tags
+
+    A tag is a string of the form::
+
+      [MY STRING]
+
+    Only alphanumerical characters and spaces are considered inside the
+    brackets.
+    """
+
+    name = 'TaggedAda'
+    aliases = ['tagged_ada']
+    tokens = get_lexer_tokens(True)
+
+
+class GNATProjectLexer(RegexLexer):
+    """Pygment lexer for project files
+
+    This is the same as the AdaLexer but with support of ``project``
+    keyword.
+    """
+    name = 'GPR'
+    aliases = ['gpr']
+    filenames = ['*.gpr']
+    mimetypes = ['text/x-gpr']
+
+    flags = re.MULTILINE | re.I  # Ignore case
+
+    tokens = get_lexer_tokens(project_support=True)

gcc/ada/doc/share/conf.py

+# -*- coding: utf-8 -*-
+#
+# GNAT build configuration file
+
+import sys
+import os
+import time
+import re
+
+sys.path.append('.')
+
+import ada_pygments
+import latex_elements
+
+# Some configuration values for the various documentation handled by
+# this conf.py
+
+DOCS = {
+    'gnat_rm': {
+        'title': u'GNAT Reference Manual'},
+    'gnat_ugn': {
+        'title': u'GNAT User\'s Guide for Native Platforms'}}
+
+# Then retrieve the source directory
+root_source_dir = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+gnatvsn_spec = os.path.join(root_source_dir, '..', 'gnatvsn.ads')
+basever = os.path.join(root_source_dir, '..', '..', 'BASE-VER')
+texi_fsf = True  # Set to False when FSF doc is switched to sphinx by default
+
+with open(gnatvsn_spec, 'rb') as fd:
+    gnatvsn_content = fd.read()
+
+
+def get_copyright():
+    return u'2008-%s, Free Software Foundation' % time.strftime('%Y')
+
+
+def get_gnat_version():
+    m = re.search(r'Gnat_Static_Version_String : ' +
+                  r'constant String := "([^\(\)]+)\(.*\)?";',
+                  gnatvsn_content)
+    if m:
+        return m.group(1).strip()
+    else:
+        if texi_fsf and os.path.exists(basever):
+            return ''
+
+        try:
+            with open(basever, 'rb') as fd:
+                return fd.read()
+        except:
+            pass
+
+    print 'cannot find GNAT version in gnatvsn.ads or in ' + basever
+    sys.exit(1)
+
+
+def get_gnat_build_type():
+    m = re.search(r'Build_Type : constant Gnat_Build_Type := (.+);',
+                  gnatvsn_content)
+    if m:
+        return {'Gnatpro': 'PRO',
+                'FSF': 'FSF',
+                'GPL': 'GPL'}[m.group(1).strip()]
+    else:
+        print 'cannot compute GNAT build type'
+        sys.exit(1)
+
+
+# First retrieve the name of the documentation we are building
+doc_name = os.environ.get('DOC_NAME', None)
+if doc_name is None:
+    print 'DOC_NAME environment variable should be set'
+    sys.exit(1)
+
+if doc_name not in DOCS:
+    print '%s is not a valid documentation name' % doc_name
+    sys.exit(1)
+
+
+# Exclude sources that are not part of the current documentation
+exclude_patterns = []
+for d in os.listdir(root_source_dir):
+    if d not in ('share', doc_name, doc_name + '.rst'):
+        exclude_patterns.append(d)
+        print 'ignoring %s' % d
+
+if doc_name == 'gnat_rm':
+    exclude_patterns.append('share/gnat_project_manager.rst')
+    print 'ignoring share/gnat_project_manager.rst'
+
+extensions = []
+templates_path = ['_templates']
+source_suffix = '.rst'
+master_doc = doc_name
+
+# General information about the project.
+project = DOCS[doc_name]['title']
+
+copyright = get_copyright()
+
+version = get_gnat_version()
+release = get_gnat_version()
+
+pygments_style = 'sphinx'
+tags.add(get_gnat_build_type())
+html_theme = 'sphinxdoc'
+if os.path.isfile('adacore_transparent.png'):
+    html_logo = 'adacore_transparent.png'
+if os.path.isfile('favicon.ico'):
+    html_favicon = 'favicon.ico'
+
+html_static_path = ['_static']
+
+latex_elements = {
+    'preamble': latex_elements.TOC_DEPTH +
+    latex_elements.PAGE_BLANK +
+    latex_elements.TOC_CMD +
+    latex_elements.LATEX_HYPHEN +
+    latex_elements.doc_settings(DOCS[doc_name]['title'],
+                                get_gnat_version()),
+    'tableofcontents': latex_elements.TOC}
+
+latex_documents = [
+    (master_doc, '%s.tex' % doc_name, project, u'AdaCore', 'manual')]
+
+texinfo_documents = [
+    (master_doc, doc_name, project,
+     u'AdaCore', doc_name, doc_name, '')]
+
+
+def setup(app):
+    app.add_lexer('ada', ada_pygments.AdaLexer())
+    app.add_lexer('gpr', ada_pygments.GNATProjectLexer())

gcc/ada/doc/share/latex_elements.py

+# define some latex elements to be used for PDF output
+
+PAGE_BLANK = r'''
+\makeatletter
+\def\cleartooddpage{%%
+   \cleardoublepage%%
+}
+\def\cleardoublepage{%%
+\clearpage%%
+   \if@twoside%%
+      \ifodd\c@page%%
+         %% nothing to do
+      \else%%
+         \hbox{}%%
+         \thispagestyle{plain}%%
+         \vspace*{\fill}%%
+         \begin{center}%%
+         \textbf{\em This page is intentionally left blank.}%%
+         \end{center}%%
+         \vspace{\fill}%%
+         \newpage%%
+         \if@twocolumn%%
+            \hbox{}%%
+            \newpage%%
+         \fi%%
+      \fi%%
+   \fi%%
+}
+\makeatother
+'''
+
+TOC_DEPTH = r'''
+\pagenumbering{arabic}
+\setcounter{tocdepth}{3}
+'''
+
+TOC_CMD = r'''
+\makeatletter
+\def\tableofcontents{%%
+    \pagestyle{plain}%%
+    \chapter*{\contentsname}%%
+    \@mkboth{\MakeUppercase{\contentsname}}%%
+            {\MakeUppercase{\contentsname}}%%
+    \@starttoc{toc}%%
+}
+\makeatother
+'''
+
+TOC = r'''
+\cleardoublepage
+\tableofcontents
+\cleardoublepage\pagestyle{plain}
+'''
+
+LATEX_HYPHEN = r'''
+\hyphenpenalty=5000
+\tolerance=1000
+'''
+
+
+def doc_settings(full_document_name, version):
+    return '\n'.join([
+        r'\newcommand*{\GNATFullDocumentName}[0]{' + full_document_name + r'}',
+        r'\newcommand*{\GNATVersion}[0]{' + version + r'}'])