Merge branch 'master' of https://github.com/python-cmd2/cmd2 into argparse

24 files changed, 36 insertions, 735 deletions

diff --git a/docs/conf.py b/docs/conf.py
index f79d5b3c..1212a6e2 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -62,7 +62,7 @@ author = 'Catherine Devlin and Todd Leonhardt'
 # The short X.Y version.
 version = '0.7'
 # The full version, including alpha/beta/rc tags.
-release = '0.7.7'
+release = '0.7.8'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/docs/index.rst b/docs/index.rst
index ae7ea300..8e8817b2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -46,10 +46,8 @@ Resources
 * cmd_
 * `cmd2 project page`_
 * `project bug tracker`_
-* `PyCon 2010 presentation <https://github.com/python-cmd2/cmd2/blob/master/docs/pycon2010/pycon2010.rst>`_,
-  *Easy Command-Line Applications with cmd and cmd2*:
-  :doc:`slides <pycon2010/pycon2010>`,
-  `video <http://pyvideo.org/pycon-us-2010/pycon-2010--easy-command-line-applications-with-c.html>`_
+* Florida PyCon 2017: `slides <https://docs.google.com/presentation/d/1LRmpfBt3V-pYQfgQHdczf16F3hcXmhK83tl77R6IJtE>`_
+* PyOhio 2011: `video <https://archive.org/details/pyvideo_541___pyohio-2011-interactive-command-line-interpreters-with-cmd-and-cmd2>`_
 
 These docs will refer to ``App`` as your ``cmd2.Cmd``
 subclass, and ``app`` as an instance of ``App``.  Of
diff --git a/docs/install.rst b/docs/install.rst
index 1edba409..9e330c3c 100644
--- a/docs/install.rst
+++ b/docs/install.rst
@@ -107,6 +107,10 @@ the following Python packages are installed:
   * pyparsing
   * pyperclip
 
+On Windows, there is an additional dependency:
+
+  * pyreadline
+
 
 Upgrading cmd2
 --------------
diff --git a/docs/integrating.rst b/docs/integrating.rst
index 32ab37e0..bcb9301c 100644
--- a/docs/integrating.rst
+++ b/docs/integrating.rst
@@ -46,10 +46,14 @@ code like the following::
 
         # Do this within whatever event loop mechanism you wish to run a single command
         cmd_line_text = "help history"
-        app.onecmd_plus_hooks(cmd_line_text)
+        app.runcmds_plus_hooks([cmd_line_text])
 
         app.postloop()
 
+The **runcmds_plus_hooks()** method is a convenience method to run multiple commands via **onecmd_plus_hooks()**.  It
+properly deals with ``load`` commands which under the hood put commands in a FIFO queue as it reads them in from a
+script file.
+
 The **onecmd_plus_hooks()** method will do the following to execute a single ``cmd2`` command in a normal fashion:
 
 #. Parse the command line text
@@ -70,4 +74,10 @@ several disadvantages, including:
 * Does not support transcript testing
 * Does not allow commands at invocation via command-line arguments
 
+Here is a little more info on ``runcmds_plus_hooks``:
+
+.. automethod:: cmd2.Cmd.runcmds_plus_hooks
+
+
+
 
diff --git a/docs/pycon2010/akkad.png b/docs/pycon2010/akkad.png
deleted file mode 100644
index 57799e97..00000000
--- a/docs/pycon2010/akkad.png
+++ /dev/null
diff --git a/docs/pycon2010/apple.jpg b/docs/pycon2010/apple.jpg
deleted file mode 100644
index 2148af3b..00000000
--- a/docs/pycon2010/apple.jpg
+++ /dev/null
diff --git a/docs/pycon2010/hook.jpg b/docs/pycon2010/hook.jpg
deleted file mode 100644
index 819370d0..00000000
--- a/docs/pycon2010/hook.jpg
+++ /dev/null
diff --git a/docs/pycon2010/pirate.py b/docs/pycon2010/pirate.py
deleted file mode 100644
index bd8b5170..00000000
--- a/docs/pycon2010/pirate.py
+++ /dev/null
@@ -1,10 +0,0 @@
-# coding=utf-8
-from cmd import Cmd
-
-
-class Pirate(Cmd):
-    pass
-
-
-pirate = Pirate()
-pirate.cmdloop()
diff --git a/docs/pycon2010/pirate2.py b/docs/pycon2010/pirate2.py
deleted file mode 100644
index 343f94ff..00000000
--- a/docs/pycon2010/pirate2.py
+++ /dev/null
@@ -1,24 +0,0 @@
-# coding=utf-8
-from cmd import Cmd
-
-
-# using ``do_`` methods
-
-class Pirate(Cmd):
-    gold = 3
-
-    def do_loot(self, arg):
-        'Seize booty from a passing ship.'
-        self.gold += 1
-        print('Now we gots {0} doubloons'
-              .format(self.gold))
-
-    def do_drink(self, arg):
-        'Drown your sorrrows in rrrum.'
-        self.gold -= 1
-        print('Now we gots {0} doubloons'
-              .format(self.gold))
-
-
-pirate = Pirate()
-pirate.cmdloop()
diff --git a/docs/pycon2010/pirate3.py b/docs/pycon2010/pirate3.py
deleted file mode 100644
index 46f26501..00000000
--- a/docs/pycon2010/pirate3.py
+++ /dev/null
@@ -1,30 +0,0 @@
-# coding=utf-8
-from cmd import Cmd
-
-
-# using hook
-
-class Pirate(Cmd):
-    gold = 3
-    initial_gold = gold
-
-    def do_loot(self, arg):
-        'Seize booty from a passing ship.'
-        self.gold += 1
-
-    def do_drink(self, arg):
-        'Drown your sorrrows in rrrum.'
-        self.gold -= 1
-
-    def precmd(self, line):
-        self.initial_gold = self.gold
-        return line
-
-    def postcmd(self, stop, line):
-        if self.gold != self.initial_gold:
-            print('Now we gots {0} doubloons'
-                  .format(self.gold))
-
-
-pirate = Pirate()
-pirate.cmdloop()
diff --git a/docs/pycon2010/pirate4.py b/docs/pycon2010/pirate4.py
deleted file mode 100644
index ae1e1f4b..00000000
--- a/docs/pycon2010/pirate4.py
+++ /dev/null
@@ -1,36 +0,0 @@
-# coding=utf-8
-from cmd import Cmd
-
-
-# using arguments
-
-class Pirate(Cmd):
-    gold = 3
-    initial_gold = gold
-
-    def do_loot(self, arg):
-        'Seize booty from a passing ship.'
-        self.gold += 1
-
-    def do_drink(self, arg):
-        '''Drown your sorrrows in rrrum.
-
-        drink [n] - drink [n] barrel[s] o' rum.'''
-        try:
-            self.gold -= int(arg)
-        except:
-            if arg:
-                print('''What's "{0}"?  I'll take rrrum.'''.format(arg))
-            self.gold -= 1
-
-    def precmd(self, line):
-        self.initial_gold = self.gold
-        return line
-
-    def postcmd(self, stop, line):
-        if self.gold != self.initial_gold:
-            print('Now we gots {0} doubloons'.format(self.gold))
-
-
-pirate = Pirate()
-pirate.cmdloop()
diff --git a/docs/pycon2010/pirate5.py b/docs/pycon2010/pirate5.py
deleted file mode 100644
index 68da88a5..00000000
--- a/docs/pycon2010/pirate5.py
+++ /dev/null
@@ -1,45 +0,0 @@
-# coding=utf-8
-from cmd import Cmd
-
-
-# quitting
-
-class Pirate(Cmd):
-    gold = 3
-    initial_gold = gold
-
-    def do_loot(self, arg):
-        'Seize booty from a passing ship.'
-        self.gold += 1
-
-    def do_drink(self, arg):
-        '''Drown your sorrrows in rrrum.
-
-        drink [n] - drink [n] barrel[s] o' rum.'''
-        try:
-            self.gold -= int(arg)
-        except:
-            if arg:
-                print('''What's "{0}"?  I'll take rrrum.'''.format(arg))
-            self.gold -= 1
-
-    def precmd(self, line):
-        self.initial_gold = self.gold
-        return line
-
-    def postcmd(self, stop, line):
-        if self.gold != self.initial_gold:
-            print('Now we gots {0} doubloons'
-                  .format(self.gold))
-        if self.gold < 0:
-            print("Off to debtorrr's prison.")
-            stop = True
-        return stop
-
-    def do_quit(self, arg):
-        print("Quiterrr!")
-        return True
-
-
-pirate = Pirate()
-pirate.cmdloop()
diff --git a/docs/pycon2010/pirate6.py b/docs/pycon2010/pirate6.py
deleted file mode 100644
index bd5f5fe2..00000000
--- a/docs/pycon2010/pirate6.py
+++ /dev/null
@@ -1,50 +0,0 @@
-# coding=utf-8
-from cmd2 import Cmd
-
-
-# prompts and defaults
-
-class Pirate(Cmd):
-    gold = 3
-    initial_gold = gold
-    prompt = 'arrr> '
-
-    def default(self, line):
-        print('What mean ye by "{0}"?'
-              .format(line))
-
-    def do_loot(self, arg):
-        'Seize booty from a passing ship.'
-        self.gold += 1
-
-    def do_drink(self, arg):
-        '''Drown your sorrrows in rrrum.
-
-        drink [n] - drink [n] barrel[s] o' rum.'''
-        try:
-            self.gold -= int(arg)
-        except:
-            if arg:
-                print('''What's "{0}"?  I'll take rrrum.'''.format(arg))
-            self.gold -= 1
-
-    def precmd(self, line):
-        self.initial_gold = self.gold
-        return line
-
-    def postcmd(self, stop, line):
-        if self.gold != self.initial_gold:
-            print('Now we gots {0} doubloons'
-                  .format(self.gold))
-        if self.gold < 0:
-            print("Off to debtorrr's prison.")
-            stop = True
-        return stop
-
-    def do_quit(self, arg):
-        print("Quiterrr!")
-        return True
-
-
-pirate = Pirate()
-pirate.cmdloop()
diff --git a/docs/pycon2010/pirate7.py b/docs/pycon2010/pirate7.py
deleted file mode 100644
index 799f73ed..00000000
--- a/docs/pycon2010/pirate7.py
+++ /dev/null
@@ -1,59 +0,0 @@
-# coding=utf-8
-from cmd2 import Cmd
-
-
-# prompts and defaults
-
-class Pirate(Cmd):
-    gold = 3
-    initial_gold = gold
-    prompt = 'arrr> '
-
-    def default(self, line):
-        print('What mean ye by "{0}"?'.format(line))
-
-    def do_loot(self, arg):
-        'Seize booty from a passing ship.'
-        self.gold += 1
-
-    def do_drink(self, arg):
-        '''Drown your sorrrows in rrrum.
-
-        drink [n] - drink [n] barrel[s] o' rum.'''
-        try:
-            self.gold -= int(arg)
-        except:
-            if arg:
-                print('''What's "{0}"?  I'll take rrrum.'''.format(arg))
-            self.gold -= 1
-
-    def precmd(self, line):
-        self.initial_gold = self.gold
-        return line
-
-    def postcmd(self, stop, line):
-        if self.gold != self.initial_gold:
-            print('Now we gots {0} doubloons'
-                  .format(self.gold))
-        if self.gold < 0:
-            print("Off to debtorrr's prison.")
-            stop = True
-        return stop
-
-    def do_quit(self, arg):
-        print("Quiterrr!")
-        return True
-
-    default_to_shell = True
-    multilineCommands = ['sing']
-    terminators = Cmd.terminators + ['...']
-    songcolor = 'blue'
-    settable = Cmd.settable + 'songcolor Color to ``sing`` in (red/blue/green/cyan/magenta, bold, underline)'
-    Cmd.shortcuts.update({'~': 'sing'})
-
-    def do_sing(self, arg):
-        print(self.colorize(arg, self.songcolor))
-
-
-pirate = Pirate()
-pirate.cmdloop()
diff --git a/docs/pycon2010/pirate8.py b/docs/pycon2010/pirate8.py
deleted file mode 100644
index 58b56208..00000000
--- a/docs/pycon2010/pirate8.py
+++ /dev/null
@@ -1,71 +0,0 @@
-# coding=utf-8
-from cmd2 import Cmd, options, make_option
-
-
-# prompts and defaults
-
-class Pirate(Cmd):
-    gold = 3
-    initial_gold = gold
-    prompt = 'arrr> '
-
-    def default(self, line):
-        print('What mean ye by "{0}"?'.format(line))
-
-    def do_loot(self, arg):
-        'Seize booty from a passing ship.'
-        self.gold += 1
-
-    def do_drink(self, arg):
-        '''Drown your sorrrows in rrrum.
-
-        drink [n] - drink [n] barrel[s] o' rum.'''
-        try:
-            self.gold -= int(arg)
-        except:
-            if arg:
-                print('''What's "{0}"?  I'll take rrrum.'''.format(arg))
-            self.gold -= 1
-
-    def precmd(self, line):
-        self.initial_gold = self.gold
-        return line
-
-    def postcmd(self, stop, line):
-        if self.gold != self.initial_gold:
-            print('Now we gots {0} doubloons'
-                  .format(self.gold))
-        if self.gold < 0:
-            print("Off to debtorrr's prison.")
-            stop = True
-        return stop
-
-    def do_quit(self, arg):
-        print("Quiterrr!")
-        return True
-
-    default_to_shell = True
-    multilineCommands = ['sing']
-    terminators = Cmd.terminators + ['...']
-    songcolor = 'blue'
-    settable = Cmd.settable + 'songcolor Color to ``sing`` in (red/blue/green/cyan/magenta, bold, underline)'
-    Cmd.shortcuts.update({'~': 'sing'})
-
-    def do_sing(self, arg):
-        print(self.colorize(arg, self.songcolor))
-
-    @options([make_option('--ho', type='int', default=2,
-                          help="How often to chant 'ho'"),
-              make_option('-c', '--commas',
-                          action="store_true",
-                          help="Intersperse commas")])
-    def do_yo(self, arg, opts):
-        chant = ['yo'] + ['ho'] * opts.ho
-        separator = ', ' if opts.commas else ' '
-        chant = separator.join(chant)
-        print('{0} and a bottle of {1}'
-              .format(chant, arg))
-
-
-pirate = Pirate()
-pirate.cmdloop()
diff --git a/docs/pycon2010/pycon2010.rst b/docs/pycon2010/pycon2010.rst
deleted file mode 100644
index 6c3af676..00000000
--- a/docs/pycon2010/pycon2010.rst
+++ /dev/null
@@ -1,382 +0,0 @@
-================================================
-Easy command-line interpreters with cmd and cmd2
-================================================
-
-:author:  Catherine Devlin
-:date:    2010-02-20
-:slides:  http://pypi.python.org/pypi/cmd2
-
-Web 2.0
-=======
-
-.. image:: web-2-0-logos.gif
-   :height: 350px
-
-But first...
-============
-
-.. image:: sargon.jpg
-   :height: 250px
-
-.. image:: akkad.png
-   :height: 250px
-
-Sargon the Great
-  Founder of Akkadian Empire
-
-.. twenty-third century BC
-
-In between
-==========
-
-.. image:: apple.jpg
-   :height: 250px
-
-Command-Line Interface
-  Unlike the Akkadian Empire,
-  the CLI will never die.
-
-Defining CLI
-============
-
-Also known as
-
-- "Line-oriented command interpreter"
-- "Command-line interface"
-- "Shell"
-
-1. Accepts free text input at prompt
-2. Outputs lines of text
-3. (repeat)
-
-Examples
-========
-
-.. class:: big
-
-   * Bash, Korn, zsh
-   * Python shell
-   * screen
-   * Zork
-   * SQL clients: psql, SQL*\Plus, mysql...
-   * ed
-
-.. ``ed`` proves that CLI is sometimes the wrong answer.
-
-!= Command Line Utilities
-=========================
-
-.. class:: big
-
-   (``ls``, ``grep``, ``ping``, etc.)
-
-   1. Accept arguments at invocation
-   2. execute
-   3. terminate
-
-   Use ``sys.argv``, ``optparse``
-
-!="Text User Interface"
-=======================
-
-* Use entire (session) screen
-* I/O is *not* line-by-line
-* See ``curses``, ``urwid``
-
-.. image:: urwid.png
-   :height: 250px
-
-
-Decide your priorities
-======================
-
-.. image:: strategy.png
-   :height: 350px
-
-A ``cmd`` app: pirate.py
-========================
-
-::
-
-   from cmd import Cmd
-
-   class Pirate(Cmd):
-       pass
-
-   pirate = Pirate()
-   pirate.cmdloop()
-
-.. Nothing here... but history and help
-
-.. ctrl-r for bash-style history
-
-Fundamental prrrinciple
-=======================
-
-.. class:: huge
-
-   ``(Cmd) foo a b c``
-
-   becomes
-
-   ``self.do_foo('a b c')``
-
-``do_``-methods: pirate2.py
-===========================
-
-::
-
-   class Pirate(Cmd):
-       gold = 3
-       def do_loot(self, arg):
-           'Seize booty frrrom a passing ship.'
-           self.gold += 1
-           print('Now we gots {0} doubloons'
-                 .format(self.gold))
-       def do_drink(self, arg):
-           'Drown your sorrrows in rrrum.'
-           self.gold -= 1
-           print('Now we gots {0} doubloons'
-                 .format(self.gold))
-
-.. do_methods; more help
-
-Hooks
-=====
-
-.. image:: hook.jpg
-   :height: 250px
-
-::
-
-   self.preloop()
-   self.postloop()
-   self.precmd(line)
-   self.postcmd(stop, line)
-
-Hooks: pirate3.py
-=================
-
-::
-
-    def do_loot(self, arg):
-        'Seize booty from a passing ship.'
-        self.gold += 1
-    def do_drink(self, arg):
-        'Drown your sorrrows in rrrum.'
-        self.gold -= 1
-    def precmd(self, line):
-        self.initial_gold = self.gold
-        return line
-    def postcmd(self, stop, line):
-        if self.gold != self.initial_gold:
-            print('Now we gots {0} doubloons'
-                  .format(self.gold))
-
-Arguments: pirate4.py
-=====================
-
-::
-
-        def do_drink(self, arg):
-            '''Drown your sorrrows in rrrum.
-
-            drink [n] - drink [n] barrel[s] o' rum.'''
-            try:
-                self.gold -= int(arg)
-            except:
-                if arg:
-                    print('''What's "{0}"?  I'll take rrrum.'''
-                          .format(arg))
-                self.gold -= 1
-
-quitting: pirate5.py
-====================
-
-::
-
-    def postcmd(self, stop, line):
-        if self.gold != self.initial_gold:
-            print('Now we gots {0} doubloons'
-                  .format(self.gold))
-        if self.gold < 0:
-            print("Off to debtorrr's prison.")
-            stop = True
-        return stop
-    def do_quit(self, arg):
-        print("Quiterrr!")
-        return True
-
-prompts, defaults: pirate6.py
-=============================
-
-::
-
-    prompt = 'arrr> '
-    def default(self, line):
-        print('What mean ye by "{0}"?'
-              .format(line))
-
-Other CLI packages
-==================
-
-.. class:: big
-
-   * CmdLoop
-   * cly
-   * CMdO
-   * pycopia
-   * cmdlin
-   * cmd2
-
-Demo
-====
-
-.. class:: huge
-
-   Convert ``cmd`` app to ``cmd2``
-
-cmd2
-====
-
-.. image:: schematic.png
-   :height: 350px
-
-As you wish, Guido
-==================
-
-.. class:: huge
-
-   Python 3 compatible
-
-(um, mostly)
-
-Absolutely free
-===============
-
-Script files
-
-Commands at invocation
-
-Output redirection
-
-Python
-
-Transcript testing
-
-But wait, there's more
-======================
-
-    * Abbreviated commands
-    * Shell commands
-    * Quitting
-    * Timing
-    * Echo
-    * Debug
-
-Minor changes: pirate7.py
-=========================
-
-::
-
-    default_to_shell = True
-    multilineCommands = ['sing']
-    terminators = Cmd.terminators + ['...']
-    songcolor = 'blue'
-    settable = Cmd.settable + 'songcolor Color to ``sing`` in (red/blue/green/cyan/magenta, bold, underline)'
-    Cmd.shortcuts.update({'~': 'sing'})
-    def do_sing(self, arg):
-        print(self.colorize(arg, self.songcolor))
-
-Now how much would you pay?
-===========================
-
-options / flags
-
-Quiet (suppress feedback)
-
-BASH-style ``select``
-
-Parsing: terminators, suffixes
-
-Options: pirate8.py
-===================
-
-::
-
-    @options([make_option('--ho', type='int', default=2,
-                          help="How often to chant 'ho'"),
-              make_option('-c', '--commas',
-                          action="store_true",
-                          help="Intersperse commas")])
-    def do_yo(self, arg, opts):
-        chant = ['yo'] + ['ho'] * opts.ho
-        separator = ', ' if opts.commas else ' '
-        chant = separator.join(chant)
-            print('{0} and a bottle of {1}'
-                      .format(chant, arg))
-
-Serious example: sqlpython
-==========================
-
-.. class:: big
-
-   ``cmd``-based app by Luca Canali @ CERN
-
-   Replacement for Oracle SQL\*Plus
-
-   Now ``cmd2``-based; postgreSQL; MySQL
-
-File reporter
-=============
-
-.. class:: huge
-
-   Gather info: Python
-
-   Store: postgresql
-
-   Report: html
-
-fileutil.py
-===========
-
-::
-
-    import glob
-    import os.path
-
-    for fullfilename in glob.glob('/home/cat/proj/cmd2/*.py'):
-        (dirpath, fname) = os.path.split(fullfilename)
-        stats = os.stat(fullfilename)
-        binds['path'] = dirpath
-        binds['name'] = fname
-        binds['bytes'] = stats.st_size
-        cmd("""INSERT INTO cat.files (path, name, bytes)
-               VALUES (%(path)s, %(name)s, %(bytes)s)""")
-    quit()
-
-sqlpython features
-==================
-
-.. class:: big
-
-   * from ``cmd2``: scripts, redirection,
-     py, etc.
-   * multiple connections
-   * UNIX: ls, cat, grep
-   * Special output
-
-
-Thank you
-=========
-
-.. class:: big
-
-    http://pypi.python.org/pypi/cmd2
-
-    http://catherinedevlin.blogspot.com
-
-    http://catherinedevlin.pythoneers.com
-
-
diff --git a/docs/pycon2010/sargon.jpg b/docs/pycon2010/sargon.jpg
deleted file mode 100644
index 5960f1e0..00000000
--- a/docs/pycon2010/sargon.jpg
+++ /dev/null
diff --git a/docs/pycon2010/schematic.png b/docs/pycon2010/schematic.png
deleted file mode 100644
index d4b39092..00000000
--- a/docs/pycon2010/schematic.png
+++ /dev/null
diff --git a/docs/pycon2010/script.txt b/docs/pycon2010/script.txt
deleted file mode 100644
index c638b1a7..00000000
--- a/docs/pycon2010/script.txt
+++ /dev/null
@@ -1,5 +0,0 @@
-loot
-loot
-drink /* arrr */ 2 # matey
-drink chardonnay
-
diff --git a/docs/pycon2010/strategy.png b/docs/pycon2010/strategy.png
deleted file mode 100644
index 7d6afdcd..00000000
--- a/docs/pycon2010/strategy.png
+++ /dev/null
diff --git a/docs/pycon2010/transcript.txt b/docs/pycon2010/transcript.txt
deleted file mode 100644
index d00e44fc..00000000
--- a/docs/pycon2010/transcript.txt
+++ /dev/null
@@ -1,12 +0,0 @@
-arrr> loot
-Now we gots 4 doubloons
-arrr> loot
-Now we gots 5 doubloons
-arrr> drink 3
-Now we gots 2 doubloons
-arrr> drink chardonnay
-What's "chardonnay"?  I'll take rrrum.
-Now we gots 1 doubloons
-arrr> quit
-Quiterrr!
-
diff --git a/docs/pycon2010/urwid.png b/docs/pycon2010/urwid.png
deleted file mode 100644
index c2b5a9bf..00000000
--- a/docs/pycon2010/urwid.png
+++ /dev/null
diff --git a/docs/pycon2010/web-2-0-logos.gif b/docs/pycon2010/web-2-0-logos.gif
deleted file mode 100644
index 9d48e37d..00000000
--- a/docs/pycon2010/web-2-0-logos.gif
+++ /dev/null
diff --git a/docs/settingchanges.rst b/docs/settingchanges.rst
index 326db3f5..0a24651b 100644
--- a/docs/settingchanges.rst
+++ b/docs/settingchanges.rst
@@ -19,11 +19,11 @@ Whether or not you set ``case_insensitive``, *please do not* define
 command method names with any uppercase letters.  ``cmd2`` expects all command methods
 to be lowercase.
 
-Shortcuts
-=========
+Shortcuts (command aliases)
+===========================
 
-Special-character shortcuts for common commands can make life more convenient for your
-users.  Shortcuts are used without a space separating them from their arguments,
+Command aliases for long command names such as special-character shortcuts for common commands can make life more
+convenient for your users.  Shortcuts are used without a space separating them from their arguments,
 like ``!ls``.  By default, the following shortcuts are defined:
 
   ``?``
@@ -42,7 +42,20 @@ To define more shortcuts, update the dict ``App.shortcuts`` with the
 {'shortcut': 'command_name'} (omit ``do_``)::
 
   class App(Cmd2):
-      Cmd2.shortcuts.update({'*': 'sneeze', '~': 'squirm'})
+      def __init__(self):
+        # Make sure you update the shortcuts attribute before calling the super class __init__
+        self.shortcuts.update({'*': 'sneeze', '~': 'squirm'})
+
+        # Make sure to call this super class __init__ after updating shortcuts
+        cmd2.Cmd.__init__(self)
+
+.. warning::
+
+  Command aliases needed to be created by updating the ``shortcuts`` dictionary attribute prior to calling the
+  ``cmd2.Cmd`` super class ``__init__()`` method.  Moreover, that super class init method needs to be called after
+  updating the ``shortcuts`` attribute  This warning applies in general to many other attributes which are not
+  settable at runtime such as ``commentGrammars``, ``multilineCommands``, etc.
+
 
 Default to shell
 ================