diff --git a/tren.rst b/tren.rst
index 80751be..5f44626 100644
--- a/tren.rst
+++ b/tren.rst
@@ -62,6 +62,16 @@
 
   tren.py -opt -opt -opt -- -this_file_starts_with_a_dash
 
+Most shells aren't too fussy about space between an option
+that takes an argument, and that argument::
+
+  -i 1
+  -i1
+
+Use whichever form you prefer.  Just be aware that there are places
+where spaces matter.  For example, you can quote spaces on your
+command line to create renaming requests that, say, replace spaces
+with dashes..
 
 Some options below are "global" - they change the state of the entire
 program permanently and cannot be undone by subsequent options.  Some
@@ -704,7 +714,70 @@
 Multiple Substitutions
 ======================
 
+You can put as many renaming requests on a **tren** command line as
+you like .... well, up to the length limit imposed by your operating
+system and shell, anyway.  As we just saw, this can be handy when
+a single renaming request can't quite do everything we want.
 
+BUT ... there's a catch.  In designing your renaming requests,
+you have to keep in mind that **tren** processes the command
+line *from left to right*, incrementally constructing the new name
+as it goes.  For instance::
+
+  tren.py -r foo=bar -r foo=baz  foo1-foo2-foo3.foo4
+
+Produces ... wait a second ... why on earth are there two renaming
+requests with idential "old" strings on the same command line?
+Shouldn't this produce a final name of ``baz1-foo2-foo3.foo4``?
+
+Nope.  After the leftmost renaming request has been processed,
+the new name is ``bar1-foo2-foo3.foo4``.  Remember that, by
+default, **tren** only replaces the *leftmost* or 0th instance
+of an "old" string.  So, when the second renaming request is
+processed, the instance 0 of ``foo`` is now found in the
+string ``foo2``.  So, the final name will be, ``bar1-baz2-foo3.foo4``.
+
+The lesson to learn from this is that multiple renaming requests
+on the command line will work fine, but you have to do one of
+two things (or both):
+
+  1) Make sure you're tracking what the "intermediate" names
+     will look like as the new file name is being constructed,
+     renaming request, by renaming request.
+
+  2) Make sure the renaming requests operate on completely 
+     disjoint parts of the file name.
+
+.. NOTE:: Similarly, **tren** remembers the last state of each option
+          as you move from left to right on the command line. For instance::
+
+            tren.py -i1 -r f=F -r o=O foo1-foo2-foo3.foo4
+
+          You might be tempted to believe that this would produce,
+          ``fOo1-Foo2-foo3.foo4``, but it doesn't.  It produces,
+          ``foO1-Foo2-foo3.foo4`` instead because the ``-i 1`` appears
+          prior to *both* renaming requests and thus applies to each
+          of them.  If you want the first instance of "o" to be
+          replaced, you need a command line like this::
+
+            tren.py -i1 -r f=F -i0 -r o=O foo1-foo2-foo3.foo4
+
+          This sort of thing is generally true for *all* options, so
+          be sure they're set the way you want them to the left of a
+          renaming request.
+
+As a practical matter, this can get really complicated to track.  If
+in doubt, it's always better to run two separate **tren** commands in,
+say, a shell script to make the renaming explicit, rather than to
+obscure things with clever command line trickery.
+
+So, let's go back to our example from the previous section.  We
+want to replace the 2nd and 4th instances of the string "foo"
+in our file name.  We do this with two renaming requests on the
+same command line, considering what each one does to the name
+as it is encountered::
+
+  tren.py -i1 -r foo=bar -i2 -r foo=bar foo1-foo2-foo3.foo4
 
 
 
@@ -1390,68 +1463,6 @@
                absolute time is both more useful and more readable.
 
 
-EXAMPLES
---------
-
-Here are some common examples of **tren** in action - the resulting
-file name(s) shown to the right as a comment.  Study each example
-carefully.  Small subtleties are introduced in various adjacent
-examples to illustrate different features of **tren**:
-
-
-  Get help::
-
-    tren.py -h
-
-  Print out detailed version information::
-
-    tren.py -v
-
-  Simple rename::
-
-    tren.py -r old=New  fold.txt log.old     # fNew.txt log.New
-
-  Change file "name"::
-
-    tren.py -b -r old=New  fold.txt log.old  # fNew.txt log.old
-
-  Change file "extension"::
-
-    tren.py -e -r old=New  fold.txt log.old  # fold.txt log.New
-
-  Rename all instances of a given string::
-
-    tren.py -g -r bin=Bin binary_bin.binbin  # Binary_Bin.BinBin
-
-  Rename, ignoring case::
-
-    tren.py -c -r bin=BIN Binary_bIN.txt     # BINary_bIN.txt
-
-  Rename multiple strings at once::
-
-    tren.py -r log=txt -r New=old New.log    # old.txt
-
-  Rename using regular expressions::
-
-    tren.py -x -r a+=a  Saaaaaaaally.doc     # Sally.doc
-
-  Rename a file containing the ``=`` symbol::
-
-    tren.py -r a\=b=c\=d  a=b.txt            # c=d.txt
-
-  Use renaming token::
-
-    tren.py -r =/I/ file.1                    # 2010-01-12
-
-  Use renaming token to change file "name"::
-
-    tren.py -b -r =/I/ file.1 file.2          # 2010-01-12.1 2010-01-12.2
-
-  Use renaming token to change file "extension"::
-
-    tren.py -e -r =/D/ file.1                 # file.20100112
-
-
 BUGS, MISFEATURES, OTHER
 ------------------------
 
@@ -1518,7 +1529,7 @@
 
 ::
 
-  $Id: tren.rst,v 1.149 2010/03/25 23:36:58 tundra Exp $
+  $Id: tren.rst,v 1.150 2010/03/26 00:17:52 tundra Exp $
 
 You can find the latest version of this program at: