From: Bob Duff <duff@adacore.com>
Date: Thu, 11 Jan 2018 08:53:32 +0000 (+0000)
Subject: [Ada] Improve documentation of xml2gnat
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=e22e7f06331fed25942cd3629e00fc2bfe1a8dc4;p=gcc.git

[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 ce0d63ce13d..77f554e7273 100644
--- 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 74dbe4ea836..cbef8a04ba7 100644
--- 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: