added some basic docs

CHANGELOG.rst

@@ -7,6 +7,14 @@ Current Developments
 
 **Added:** 
 
+* ``trace`` alias added that enables users to turn on and off the printing 
+  of source code lines prior to their execution. This is useful for debugging scripts.
+* New ability to force callable alias functions to be run in the foreground, i.e.
+  the main thread from which the function was called. This is useful for debuggers 
+  and profilers which may require such access. Use the ``xonsh.proc.foreground``
+  decorator on an alias function to flag it. ``ForegroundProcProxy`` and
+  ``SimpleForegroundProcProxy`` classes have been added to support this feature.
+  Normally, forcing a foreground alias is not needed.
 * Added boolean ``$RAISE_SUBPROC_ERROR`` environment variable. If true
   and a subprocess command exits with a non-zero return code, a 
   CalledProcessError will be raised. This is useful in scripts that should
@@ -20,6 +28,7 @@ Current Developments
 
 **Fixed:**
 
+* Hundreds of bugs related to line and column numbers have been addressed.
 * Fixed path completion not working for absolute paths or for expanded paths on Windows.
 
 **Security:** None

docs/tutorial.rst

@@ -831,6 +831,20 @@ built-in mapping.  Here is an example using a function value:
     >>> banana
     'My spoon is tooo big!'
 
+Usually, callable alias comamnds will be run in a separate thread so that 
+users may background them interactively. However, some aliases may need to be 
+executed on the thread that they were called from. This is mostly useful for debuggers
+and profilers. To make an alias run in the foreground, decorate its function
+with the ``xonsh.proc.foreground`` decorator. 
+
+.. code-block:: python
+
+    from xonsh.proc import foreground
+
+    @foreground
+    def mycmd(args, stdin=None):
+        return 'In your face!'
+
 Aliasing is a powerful way that xonsh allows you to seamlessly interact to
 with Python and subprocess.
 
@@ -1021,7 +1035,11 @@ operates on a given argument, rather than on the string ``'xonsh'`` (notice how
 Additionally, if the script should exit if a command fails, set the 
 environment variable ``$RAISE_SUBPROC_ERROR = True`` at the top of the 
 file. Errors in Python mode will already raise exceptions and so this 
-is roughly equivelent to Bash's `set -e`.
+is roughly equivelent to Bash's ``set -e``.
+
+Furthermore, you can also toggle the ability to print source code lines with the
+``trace on`` and ``trace off`` commands.  This is roughly equivalent to 
+Bash's ``set -x`` or Python's ``python -m trace``, but you know, better.
 
 Importing Xonsh (``*.xsh``)
 ==============================