diff --git a/tren.rst b/tren.rst
index 9bb271a..be77a9e 100644
--- a/tren.rst
+++ b/tren.rst
@@ -3,12 +3,42 @@
 
 **tren** - Advanced File Renaming
 
+
+HOW TO USE THIS DOCUMENT
+------------------------
+
+**tren** is a powerful command line file/directory renaming tool.  It
+implements multiple, sophisticated renaming features than can be a bit
+complex to learn.  For this reason, this document is split into two
+general sections: `REFERENCE`_ and `TUTORIAL AND DESCRIPTION`_.  If
+you are new to **tren**, start by studying the latter section first.
+It will take you from very simple- to the most complex renaming
+operations the program supports.  Once you've got a sense of what
+**tren** can do, the reference section will be handy to look up
+options and their arguments.
+
+.. WARNING:: **tren** is very powerful and can easily and
+             automatically rename things in ways you didn't intend.
+             It is ***strongly*** recommended that you try out new
+             **tren** operations with the ``-t`` option on the command
+             line.  This turns on the "test mode" and will show you
+             what the program *would* do without actually doing it.
+             It goes without saying that you should be even more
+             careful when using this program as the system root or
+             administrator.  It's quite easy to accidentally rename
+             system files and thereby clobber your OS.  You have been
+             warned!!!
+
+REFERENCE
+---------
+
+
 SYNOPSIS
 --------
 
 ::
 
-    tren.py [-1abCcdEefghqtvXx] [-I file] [-l string] [-r old=new]... file|dir file|dir ...
+    tren.py [-aCcdfhqtvXx] [-A alphabet] [-I file] [-i range]  [-P esc] [-R sep] [-r old=new] [-S suffix] [-w width] file|dir ...
 
 
 OPTIONS
@@ -25,10 +55,12 @@
 Think of any options set in ``$TREN`` as the "leftmost command line
 options".
 
-You may interweave option and file/dir name specifications on
-the command line::
+All options must precede the list of files and/or directories being
+renamed.  If one of your rename targets start with the ``-`` character,
+most command shells recognines the double dash as an explicit
+"end of options" delimiter::
 
-  tren.py -opt1 -opt2 -opt3 file|dir.. -opt4 -opt5 -opt6 file|dir ...
+  tren.py -opt -opt -opt -- -this_file_starts_with_a_dash
 
 This allows you to rename different files and directories with
 different options.  *However*, keep in mind that all the options to
@@ -293,8 +325,8 @@
 
 
 
-DESCRIPTION
------------
+TUTORIAL AND DESCRIPTION
+------------------------
 
 .. WARNING:: **tren** is a powerful file and directory renaming tool.
              Be **sure** you know what you're about to do.  If you're
@@ -1045,18 +1077,32 @@
     tren.py -e -r =/D/ file.1                 # file.20100112
 
 
-OTHER
------
+BUGS, MISFEATURES, OTHER
+------------------------
 
-You must have a reasonably current version of Python installed.
+You must be running Python 2.6.x or later.  **tren** makes use of
+features not supported in released prior to this.
 
+As a general matter, **tren** should run on any POSIX-compliant OS
+that has this version (or later) of Python on it.  It will also run on
+many Microsoft Windows systems.  If the Windows system has the
+``win32all`` Python extensions installed, **tren** will take advantage
+of them for purposes of deriving the names of the user and group that
+own the file or directory being renamed.
 
-BUGS AND MISFEATURES
---------------------
+As of this writing, **tren** will not run in the **cygwin** environment
+because their version of Python is still backleveled to 2.5.x.  When
+and if the **cygwin** team upgrades to 2.6.x, **tren** is expected to
+work there as well.
 
-On windows platforms, the ``/U/`` and ``/G/`` do not return the
-underlying operating system ownership information..  They return
-``winuser`` and ``wingroup`` respectively.
+This program is **EXPERIMENTAL** (see the license).  This means it's
+had some testing but is certainly not guaranteed to be perfect.  As of
+this writing, it has been run on FreeBSD, Linux, Windows XP, and Mac
+OS X.  It has not, however, been run on 64-bit versions of those OSs.
+
+If you have experience, positive or negative, using **tren** on other
+OS/bitsize systems, please contact us at the email address below.
+
 
 COPYRIGHT AND LICENSING
 -----------------------
@@ -1084,7 +1130,7 @@
 
 ::
 
-  $Id: tren.rst,v 1.136 2010/01/25 20:49:26 tundra Exp $
+  $Id: tren.rst,v 1.137 2010/03/19 17:19:14 tundra Exp $
 
 You can find the latest version of this program at: