Merge branch 'rewrite_xenant'

2 files changed, 58 insertions, 20 deletions

diff --git a/docs/source/buildfile.rst b/docs/source/buildfile.rst
index a2fbf99..cec8e30 100644
--- a/docs/source/buildfile.rst
+++ b/docs/source/buildfile.rst
@@ -63,7 +63,7 @@ Next, we will look at a new target::
 This is a standard definition of a Python function with a decorator.
 
 First, the ``target`` decorator marks the function definition as a target (to
-be used by the ``list-targets`` command, see :ref:`specialTargets`). Next, we
+be used by the ``list-targets`` command, see :ref:`otherCommands`). Next, we
 define the function; this function name *is* the name of the target. That is,
 the name given to the function will be the name given to the command to invoke
 this target.  Further, we have the docstring; (this is also used by the
@@ -77,10 +77,32 @@ 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
-invocation of Xnt that will inform you if the target ran successfully or not
-given your criteria (or will just say it succeeded if you don't specify a
-return value at all). For example::
+you see fit. Xnt will emit 'Failure' if the status code is *not* zero and will
+otherwise remain silent if the code is zero. Further, the status code returned
+by your target will be returned as the exit code of Xnt when finished
+executing.
+
+*Notice*, this allows Xnt to fail fast when attempting to execute multiple
+targets. That is, if you specify more than one target, Xnt will stop at the
+first failure.
+
+If you don't define a return value for a target, Xnt will assume success and
+return '0'.
+
+Examples
+--------
+
+Not defining the return value::
+
+    @target
+    def foo():
+        pass
+
+Will result in (no success message; other output may be shown)::
+
+    ...
+
+Returning success (no success message; other output may be shown)::
 
     @target
     def foo():
@@ -89,9 +111,19 @@ return value at all). For example::
 Will result in::
 
     ...
-    Success
 
-Most tasks have been updated to return error codes as well to that you can
+Returning failure (not 0)::
+
+    @target
+    def foo():
+        return 1
+
+Will result in::
+
+    ...
+    Failure
+
+Most tasks have been updated to return error codes as well so 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.
 
diff --git a/docs/source/xenant.rst b/docs/source/xenant.rst
index 5bd6235..e9456fa 100644
--- a/docs/source/xenant.rst
+++ b/docs/source/xenant.rst
@@ -38,16 +38,22 @@ example::
 
 Will execute `target1` through `targetN` in order of listing.
 
-.. _specialTargets:
+.. _otherCommands:
 
-Special Targets
----------------
+Othes Commands
+--------------
+
+Xnt has a number of other commands that can be invoked besides those defined in
+the current directory's `build.py` file. One will need a build file to run. The
+others, however, do not.
+
+* ``help`` prints a summary message, including information about the version of
+  Xnt, license, and usage.
 
-"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.
+Usage::
+
+    $ xnt help
 
-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
@@ -57,6 +63,12 @@ Usage::
 
     $ xnt list-targets
 
+* ``version`` prints Xnt's installed version.
+
+Usage::
+
+    $ xnt version
+
 .. _xntOptions:
 
 Options
@@ -72,12 +84,6 @@ 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