[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

gcc/ada/ChangeLog

 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
 	unit names.
 

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: