Update documentation: Add Parameter passing

Restructure documentation to better suite the parameter passing
section(s); add two sections: how to invoke xnt to pass parameters,
and how to add/use them in the build file

1 files changed, 18 insertions, 63 deletions

diff --git a/docs/source/buildfile.rst b/docs/source/buildfile.rst
index 3867830..4372874 100644
--- a/docs/source/buildfile.rst
+++ b/docs/source/buildfile.rst
@@ -69,73 +69,28 @@ purpose of the target, or what the target accomplishes when ran. Finally, we
 call ``mkdir`` of the ``xnt.tasks`` module. This function, if not obvious by
 the name, creates a directory named 'build' (see :doc:`taskreference`).
 
-.. _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.