[Ada] Improve documentation of xml2gnat

2018-01-11  Bob Duff  <duff@adacore.com>

gcc/ada/

	* doc/gnat_ugn/gnat_utility_programs.rst: Improve documentation of
	xml2gnat.

From-SVN: r256509

diff --git a/gcc/ada/ChangeLog b/gcc/ada/ChangeLog
index ce0d63ce13da025fd1912abe97b842ffbbf259fb..77f554e7273458328a848e2ff66e4575399734c8 100644 (file)
--- a/gcc/ada/ChangeLog
+++ b/gcc/ada/ChangeLog
@@ -1,3 +1,8 @@
+2018-01-11  Bob Duff  <duff@adacore.com>
+
+       * doc/gnat_ugn/gnat_utility_programs.rst: Improve documentation of
+       xml2gnat.
+
 2018-01-11  Bob Duff  <duff@adacore.com>
 
        * binde.adb (Force_Elab_Order): Give an error if there are duplicate

diff --git a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
index 74dbe4ea836709deadc2be10cb4f0b1a3d2299d9..cbef8a04ba72b116fca1445c66abf5e105a26c8d 100644 (file)
--- a/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
+++ b/gcc/ada/doc/gnat_ugn/gnat_utility_programs.rst
@@ -1451,11 +1451,25 @@ Alternatively, you may run the script using the following command line:
   ``gnat2xml`` generates XML files that will validate against
   :file:`ada-schema.xsd`.
 
-  ``xml2gnat`` is a back-translator that translates the XML back
-  into Ada source code. The Ada generated by ``xml2gnat`` has
-  identical semantics to the original Ada code passed to
-  ``gnat2xml``. It is not textually identical, however --- for
-  example, no attempt is made to preserve the original indentation.
+  ``xml2gnat`` is a back-translator that translates the XML back into
+  Ada source code. This is primarily for the purpose of testing
+  ``gnat2xml``, rather than for users. The Ada generated by ``xml2gnat``
+  has identical semantics to the original Ada code passed to
+  ``gnat2xml``. It is not textually identical, however --- for example,
+  no attempt is made to preserve the original indentation.
+
+  The ``xml2gnat`` command line contains a list of the same Ada files
+  passed to gnat2xml (not the names of xml files). The xml files are
+  assumed to be in an 'xml' subdirectory of the directory in which the
+  Ada source files are. So for example, if the Ada source file is
+  some/dir/mumble.adb, then the xml file is found in
+  some/dir/xml/mumble.adb.xml. You should use the :switch:`--output-dir`
+  switch of ``gnat2xml`` to tell it to generate the output in the xml
+  subdirectory, so ``xml2gnat`` can find it.
+
+  Output goes into subdirectories "generated_ada" and "self_rep" of the
+  output directory, which is the current directory by default, but can
+  be overridden with --output-dir=dir on the command line.
 
   .. _Structure_of_the_XML: