Merge branch 'addParamPassing'

Conflicts:
	docs/source/buildfile.rst

3 files changed, 109 insertions, 64 deletions

diff --git a/docs/source/buildfile.rst b/docs/source/buildfile.rst
index 4a46233..58e226a 100644
--- a/docs/source/buildfile.rst
+++ b/docs/source/buildfile.rst
@@ -70,7 +70,7 @@ call ``mkdir`` of the ``xnt.tasks`` module. This function, if not obvious by
 the name, creates a directory named 'build' (see :doc:`taskreference`).
 
 Return Values
--------------
+=============
 
 The targets you define can return an error code (or '0' for success) however
 you see fit. Doing this will give you a status message at the end of the
@@ -91,73 +91,28 @@ Most tasks have been updated to return error codes as well to that you can
 return what it returns. If you find any tasks that can be updated to behave
 this way, please create an issue for it.
 
-.. _runningXnt:
+.. _buildProperties:
 
-Running Xnt
------------
-
-Invoking Xnt from the command line is very simple and very similar to how other
-build tools are invoked (this was intentional).
-
-.. _defaultUse:
-
-Default Use
-~~~~~~~~~~~
-
-The most simplistic use of Xnt is as follows::
-
-    $ xnt
-
-This will attempt to invoke the `default` target in the current directory's
-`build.py`.
-
-.. _invokeTarget:
-
-Invoke a Target
-~~~~~~~~~~~~~~~
-
-To invoke a particular target, use::
-
-    $ xnt {target}
-
-Where the value of `{target}` is dependent on your particular `build.py` file.
-
-.. _specialTargets:
-
-Special Targets
-~~~~~~~~~~~~~~~
-
-"Special" targets (for lack of a better name) are targets that do not exist in
-the build script, but rather are a part of Xnt.
-
-Thus far, I have only defined one "special" target, ``list-targets`` (I don't
-think this name is going to change again ...).
-
-* ``list-targets`` does exactly what the name should suggest: it prints a list
-  of the targets found in the current directory's `build.py` script, along with
-  any docstrings that may be defined with them.
-
-Usage::
-
-    $ xnt list-targets
-
-.. _xntOptions:
-
-Options
-~~~~~~~
-
-Xnt also has a few "options" that may be provided along with a regular targets.
+Build Properties
+================
 
-Usage::
+As mentioned in :ref:`xntPropertiesParameters`, Xnt can accept parameters from
+the command line and pass them into the build file. Xnt doesn't necessarily
+expect the dictionary (named `properties`) to exist; but if you ever intend to
+use it, it will have to be defined one way or another (either to an empty
+dictionary or actually hold values). For example, to define an empty
+`properties` dictionary, one could write their build file as such::
 
-    $ xnt [options] [target]
+    #!/usr/bin/env python
 
-Where options can be any and all of the following (unless otherwise specified):
+    from xnt import target
 
-* ``-v``: add verbose output to the execution of Xnt
+    properties = {}
 
-* ``--version``: Print the version of Xnt and exit
+    @target
+    def foo():
+        #uses properties somehow
+        return 0
 
-* ``--usage``: Print version, license, usage information and quit. [I've
-  debatted between putting this as a special target and leaving it as an
-  option.. not sure which is better...]
+The hope for this feature is that it is easy to use because it borrows syntax
+from other build tools that you may already be familiar with.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 6e1462c..164ea36 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -26,6 +26,7 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   xenant
    buildfile
    taskreference
    buildreference
diff --git a/docs/source/xenant.rst b/docs/source/xenant.rst
new file mode 100644
index 0000000..86a26da
--- /dev/null
+++ b/docs/source/xenant.rst
@@ -0,0 +1,89 @@
+Running Xnt
+===========
+
+Invoking Xnt from the command line is very simple and very similar to how other
+build tools are invoked (this was intentional).
+
+.. _defaultUse:
+
+Default Use
+-----------
+
+The most simplistic use of Xnt is as follows::
+
+    $ xnt
+
+This will attempt to invoke the `default` target in the current directory's
+`build.py`.
+
+.. _invokeTarget:
+
+Invoke a Target
+---------------
+
+To invoke a particular target, use::
+
+    $ xnt {target}
+
+Where the value of `{target}` is dependent on your particular `build.py` file.
+
+.. _specialTargets:
+
+Special Targets
+---------------
+
+"Special" targets (for lack of a better name) are targets that do not exist in
+the build script, but rather are a part of Xnt.
+
+Thus far, I have only defined one "special" target, ``list-targets`` (I don't
+think this name is going to change again ...).
+
+* ``list-targets`` does exactly what the name should suggest: it prints a list
+  of the targets found in the current directory's `build.py` script, along with
+  any docstrings that may be defined with them.
+
+Usage::
+
+    $ xnt list-targets
+
+.. _xntOptions:
+
+Options
+-------
+
+Xnt also has a few "options" that may be provided along with a regular targets.
+
+Usage::
+
+    $ xnt [options] [target]
+
+Where options can be any and all of the following (unless otherwise specified):
+
+* ``-v``: add verbose output to the execution of Xnt
+
+* ``--version``: Print the version of Xnt and exit
+
+* ``--usage``: Print version, license, usage information and quit. [I've
+  debatted between putting this as a special target and leaving it as an
+  option.. not sure which is better...]
+
+.. _xntPropertiesParameters:
+
+Properties and Parameter Passing
+--------------------------------
+
+Xnt now has the ability to accept command line parameters and forward them to
+your `build.py` file. This can be useful for a number of reasons: flipping
+debug flags, deployment flags and the like or whatever else you can imagine.
+
+The general semantic for passing the parameters is as follows::
+
+    $ xnt [-D{name}={value}]+ [options] [target]
+
+*Notice:* the `-D` is used to distinguish values to be passed to the `build`
+file from regular options. You may specify as many parameters as you like and
+there is no other real ordering required to be parsed correctly. Just know,
+spaces are used to delimit arguments; if your passed value *must* have a space,
+remember to quote it.
+
+Please see :ref:`buildProperties` to see how this works on the `build.py` side.