--- a/cmd2.py	Fri Feb 12 16:28:15 2010 -0500
+++ b/cmd2.py	Fri Feb 12 21:41:17 2010 -0500
@@ -393,7 +393,7 @@
     legalChars = '!#$%.:?@_' + pyparsing.alphanums + pyparsing.alphas8bit  
     shortcuts = {'?': 'help', '!': 'shell', '@': 'load', '@@': '_relative_load'}
     excludeFromHistory = '''run r list l history hi ed edit li eof'''.split()
-    default_to_shell = True
+    default_to_shell = False
     noSpecialParse = 'set ed edit exit'.split()
     defaultExtension = 'txt'            # For ``save``, ``load``, etc.
     default_file_name = 'command.txt'   # For ``save``, ``load``, etc.
@@ -407,13 +407,13 @@
     settable = stubbornDict('''
         prompt
         colors                Colorized output (*nix only)
-        continuation_prompt
-        debug
-        default_file_name     for `save`, `load`, etc.
-        editor
+        continuation_prompt   On 2nd+ line of input
+        debug                 Show full error stack on error
+        default_file_name     for ``save``, ``load``, etc.
+        editor                Program used by ``edit`` 	
         case_insensitive      upper- and lower-case both OK
         feedback_to_output    include nonessentials in `|`, `>` results 
-        quiet                 
+        quiet                 Don't print nonessential feedback
         echo                  Echo command issued into output
         timing                Report execution times
         abbrev                Accept abbreviated commands

--- a/docs/freefeatures.rst	Fri Feb 12 16:28:15 2010 -0500
+++ b/docs/freefeatures.rst	Fri Feb 12 21:41:17 2010 -0500
@@ -5,15 +5,31 @@
 These features are provided "for free" to a cmd_-based application
 simply by replacing ``import cmd`` with ``import cmd2 as cmd``.
 
+Abbreviated commands
+====================
+
+``cmd2`` apps will accept shortened command names
+so long as there is no ambiguity.  Thus, if 
+``do_divide`` is defined, then ``divid``, ``div``,
+or even ``d`` will suffice, so long as there are
+no other commands defined beginning with *divid*,
+*div*, or *d*.
+
+This behavior can be turned off with ``app.abbrev`` (see :ref:`parameters`)
+
 Script files
 ============
 
-Commands can be loaded and run from text files.
+Text files can serve as scripts for your ``cmd2``-based
+application, with the ``load``, ``save``, and ``edit``
+commands.
 
 .. automethod:: cmd2.Cmd.do_load
 
 .. automethod:: cmd2.Cmd.do_save
 
+.. automethod:: cmd2.Cmd.do_edit
+
 Output redirection
 ==================
 
@@ -29,7 +45,6 @@
     
 .. _pywin32:: http://sourceforge.net/projects/pywin32/
 .. _xclip:: http://www.cyberciti.biz/faq/xclip-linux-insert-files-command-output-intoclipboard/
-
   
 Commands at invocation
 ======================
@@ -113,5 +128,29 @@
 synonyms ``exit`` and simply ``q``).
 It's trivial, but it's one less thing for you to remember.
 
+Comments
+========
+
+Comments are omitted from the argument list
+before it is passed to a ``do_`` method.  By
+default, both Python-style and C-style comments
+are recognized; you may change this by overriding
+``app.commentGrammars`` with a different pyparsing_
+grammar.
+
+Comments can be useful in :ref:`script`s.  Used
+in an interactive session, they may indicate
+mental imbalance.
+
+::
+
+    def do_speak(self, arg):
+        self.stdout.write(arg + '\n')
+
+::
+
+  (Cmd) speak it was /* not */ delicious! # Yuck!
+  it was  delicious!
+  	
 Transcript-based testing
 ========================

--- a/docs/settingchanges.rst	Fri Feb 12 16:28:15 2010 -0500
+++ b/docs/settingchanges.rst	Fri Feb 12 21:41:17 2010 -0500
@@ -33,6 +33,7 @@
         def do_lengthycommand(self, args):
             # ...          
 
+ 
 Shortcuts
 =========
 
@@ -58,6 +59,32 @@
   class App(Cmd2):
       Cmd2.shortcuts.update({'*': 'sneeze', '~': 'squirm'})
 
+Default to shell
+================
+
+Every ``cmd2`` application can execute operating-system
+level (shell) commands with ``shell`` or a ``!``
+shortcut::
+
+  (Cmd) shell which python
+  /usr/bin/python
+  (Cmd) !which python
+  /usr/bin/python
+
+However, if the parameter ``default_to_shell`` is 
+``True``, then *every* command will be attempted on
+the operating system.  Only if that attempt fails
+(i.e., produces a nonzero return value) will the
+application's own ``default`` method be called.
+
+::
+
+  (Cmd) which python
+  /usr/bin/python
+  (Cmd) my dog has fleas
+  sh: my: not found
+  *** Unknown syntax: my dog has fleas
+
 Timing
 ======
 
@@ -74,15 +101,6 @@
                         during application execution.  
                         (See :ref:`parameters`)
 
-.. _quiet:
-
-Quiet
-=====
-
-Controls whether ``self.pfeedback('message')`` output is suppressed;
-useful for non-essential feedback that the user may not always want
-to read.  Only relevant if :ref:`outputters` are used.
-
 Settability
 ===========
 
@@ -91,5 +109,12 @@
 is running, add its name to ``App.settable``.  See
 :ref:`parameters`.
 
-Abbreviated commands
-====================
+Other user-settable parameters
+==============================
+
+A list of all user-settable parameters, with brief
+comments, is viewable from within a running application
+with::
+
+  (Cmd) set --long
+

--- a/docs/unfreefeatures.rst	Fri Feb 12 16:28:15 2010 -0500
+++ b/docs/unfreefeatures.rst	Fri Feb 12 21:41:17 2010 -0500
@@ -2,10 +2,77 @@
 Features requiring application changes
 ======================================
 
-Command shortcuts
+Multiline commands
+==================
+
+Command input may span multiple lines for the
+commands whose names are listed in the 
+parameter ``app.multilineCommands``.  These
+commands will be executed only
+after the user has entered a *terminator*.
+By default, the command terminators is
+``;``; replacing or appending to the list
+``app.terminators`` allows different 
+terminators.  A blank line
+is *always* considered a command terminator
+(cannot be overridden).
+
+Parsed statements
 =================
 
-.. _parameters:
+``cmd2`` passes ``arg`` to a ``do_`` method (or
+``default`) as a ParsedString, a subclass of 
+string that includes an attribute ``parsed``.
+``parsed`` is a ``pyparsing.ParseResults``_
+object produced by applying a pyparsing_ 
+grammar applied to ``arg``.  It may include:
+
+command
+  Name of the command called
+
+raw
+  Full input exactly as typed.  
+
+terminator
+  Character used to end a multiline command
+
+suffix
+  Remnant of input after terminator
+
+::
+
+    def do_parsereport(self, arg):
+        self.stdout.write(arg.parsed.dump() + '\n')
+
+::
+
+	(Cmd) parsereport A B /* C */ D; E
+	['parsereport', 'A B  D', ';', 'E']
+	- args: A B  D
+	- command: parsereport
+	- raw: parsereport A B /* C */ D; E
+	- statement: ['parsereport', 'A B  D', ';']
+	  - args: A B  D
+	  - command: parsereport
+	  - terminator: ;
+	- suffix: E
+	- terminator: ;
+
+If ``parsed`` does not contain an attribute,
+querying for it will return ``None``.  (This
+is a characteristic of ``pyparsing.ParseResults``_.)
+
+ParsedString was developed to support sqlpython_
+and reflects its needs.  The parsing grammar and
+process are painfully complex and should not be
+considered stable; future ``cmd2`` releases may
+change it somewhat (hopefully reducing complexity).
+   
+(Getting ``arg`` as a ``ParsedString`` is 
+technically "free", in that it requires no application
+changes from the cmd_ standard, but there will 
+be no result unless you change your application
+to *use* ``arg.parsed``.)
 
 Environment parameters
 ======================
@@ -56,6 +123,49 @@
 Commands with flags
 ===================
 
+All ``do_`` methods are responsible for interpreting
+the arguments passed to them.  However, ``cmd2`` lets
+a ``do_`` methods accept Unix-style *flags*.  It uses optparse_
+to parse the flags, and they work the same way as for
+that module.
+
+Flags are defined with the ``options`` decorator, 
+which is passed a list of optparse_-style options,
+each created with ``make_option``.  The method
+should accept a second argument, ``opts``, in
+addition to ``args``; the flags will be stripped
+from ``args``.
+
+::
+
+    @options([make_option('-p', '--piglatin', action="store_true", help="atinLay"),
+              make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"),
+              make_option('-r', '--repeat', type="int", help="output [n] times")
+             ])
+    def do_speak(self, arg, opts=None):
+        """Repeats what you tell me to."""
+        arg = ''.join(arg)
+        if opts.piglatin:
+            arg = '%s%say' % (arg[1:].rstrip(), arg[0])
+        if opts.shout:
+            arg = arg.upper()
+        repetitions = opts.repeat or 1
+        for i in range(min(repetitions, self.maxrepeats)):
+            self.stdout.write(arg)
+            self.stdout.write('\n')
+
+::
+
+	(Cmd) say goodnight, gracie
+	goodnight, gracie
+	(Cmd) say -sp goodnight, gracie
+	OODNIGHT, GRACIEGAY
+	(Cmd) say -r 2 --shout goodnight, gracie
+	GOODNIGHT, GRACIE
+	GOODNIGHT, GRACIE
+
+.. _optparse: 
+
 .. _outputters:
 
 poutput, pfeedback, perror
@@ -68,4 +178,14 @@
 
   - More concise
   - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter.
-  
\ No newline at end of file
+  
+.. _quiet:
+
+Quiet
+=====
+
+Controls whether ``self.pfeedback('message')`` output is suppressed;
+useful for non-essential feedback that the user may not always want
+to read.  ``quiet`` is only relevant if 
+``app.pfeedback`` is sometimes used.
+