From 13480bf7867bed1cfa64613fddb0d6e53aa36b9e Mon Sep 17 00:00:00 2001
From: Marcelo Lira <marcelo.lira@openbossa.org>
Date: Wed, 12 Jan 2011 11:17:58 -0300
Subject: Added documentation for command line and XML generator project file
 options.

---
 doc/commandlineoptions.rst | 76 ++++++++++++++++++++++++++++++++++++++++++++++
 doc/contents.rst           |  2 ++
 doc/overview.rst           |  2 +-
 doc/projectfile.rst        | 71 +++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 150 insertions(+), 1 deletion(-)
 create mode 100644 doc/commandlineoptions.rst
 create mode 100644 doc/projectfile.rst

diff --git a/doc/commandlineoptions.rst b/doc/commandlineoptions.rst
new file mode 100644
index 000000000..0761982d4
--- /dev/null
+++ b/doc/commandlineoptions.rst
@@ -0,0 +1,76 @@
+.. _command-line:
+
+Command line options
+********************
+
+Usage
+-----
+
+::
+
+   generator [options] header-file typesystem-file
+
+
+Options
+-------
+
+.. _api-version:
+
+``--api-version``
+    Specify the supported api version used to generate the bindings.
+
+.. _debug-level:
+
+``--debug-level=[sparse|medium|full]``
+    Set the debug level.
+
+.. _documentation-only:
+
+``--documentation-only``
+    Do not generate any code, just the documentation.
+
+.. _generation-set:
+
+``--generation-set``
+    Generator set to be used (e.g. qtdoc).
+
+.. _help:
+
+``--help``
+    Display this help and exit.
+
+.. _include-paths:
+
+``--include-paths=<path>[:<path>:...]``
+    Include paths used by the C++ parser.
+
+.. _license-file=[license-file]:
+
+``--license-file=[license-file]``
+    File used for copyright headers of generated files.
+
+.. _no-suppress-warnings:
+
+``--no-suppress-warnings``
+    Show all warnings.
+
+.. _output-directory:
+
+``--output-directory=[dir]``
+    The directory where the generated files will be written.
+
+.. _silent:
+
+``--silent``
+    Avoid printing any message.
+
+.. _typesystem-paths:
+
+``--typesystem-paths=<path>[:<path>:...]``
+    Paths used when searching for type system files.
+
+.. _version:
+
+``--version``
+    Output version information and exit.
+
diff --git a/doc/contents.rst b/doc/contents.rst
index 5abd13bc5..c21930a74 100644
--- a/doc/contents.rst
+++ b/doc/contents.rst
@@ -5,3 +5,5 @@ Table of contents
     :maxdepth: 3
 
     overview.rst
+    commandlineoptions.rst
+    projectfile.rst
diff --git a/doc/overview.rst b/doc/overview.rst
index 6191c0edb..5f50610ff 100644
--- a/doc/overview.rst
+++ b/doc/overview.rst
@@ -4,7 +4,7 @@
 Generator Overview
 ******************
 
-In a few words, the Generator is a utility that parses a collecion of header and
+In a few words, the Generator is a utility that parses a collection of header and
 typesystem files, generating other files (code, documentation, etc.) as result.
 
 Creating new bindings
diff --git a/doc/projectfile.rst b/doc/projectfile.rst
new file mode 100644
index 000000000..6b91bc9dd
--- /dev/null
+++ b/doc/projectfile.rst
@@ -0,0 +1,71 @@
+.. _project-file:
+
+********************
+Binding Project File
+********************
+
+Instead of directing the Generator behaviour via command line, the binding developer
+can write a XML project file describing the same information, and avoid the hassle
+of a long stream of command line arguments.
+
+.. _project-file-structure:
+
+The project file structure
+==========================
+
+Here follows a comprehensive example of a generator project file.
+
+    .. code-block:: xml
+
+         <?xml version="1.0"?>
+         <generator-project>
+             <generator-set generator="path/to/generator/CHOICE_GENERATOR" />
+             <header-file location="DIR/global.h" />
+             <typesystem-file location="DIR/typesystem_for_your_binding.xml" />
+             <output-directory location="OUTPUTDIR" />
+             <include-paths>
+                 <path location="path/to/library/being/wrapped/headers/1" />
+                 <path location="path/to/library/being/wrapped/headers/2" />
+             </include-paths>
+             <typesystem-paths>
+                 <path location="path/to/directory/containing/type/system/files/1" />
+                 <path location="path/to/directory/containing/type/system/files/2" />
+             </typesystem-paths>
+             <enable-parent-ctor-heuristic />
+         </generator-project>
+
+
+Project file tags
+=================
+
+The generator project file tags are in direct relation to the
+:ref:`command line arguments <command-line>`. All of the current command line
+options provided by |project| were already seen on the :ref:`<project-file-structure>`,
+for new command line options provided by additional generator modules (e.g.: qtdoc,
+Shiboken) could also be used in the generator project file following simple conversion rules.
+
+For tags without options, just write as an empty tag without any attributes. Example:
+
+    .. code-block:: bash
+
+         --BOOLEAN-ARGUMENT
+
+becomes
+
+    .. code-block:: xml
+
+         <BOOLEAN-ARGUMENT />
+
+and
+
+    .. code-block:: bash
+
+         --VALUE-ARGUMENT=VALUE
+
+becomes
+
+    .. code-block:: xml
+
+         <VALUE-ARGUMENT value="VALUE" />
+
+
-- 
cgit v1.2.3