Finish documenting settings and add new builtin_commands document

3 files changed, 120 insertions, 29 deletions

diff --git a/docs/features/builtin_commands.rst b/docs/features/builtin_commands.rst
new file mode 100644
index 00000000..ab4ca60e
--- /dev/null
+++ b/docs/features/builtin_commands.rst
@@ -0,0 +1,48 @@
+Builtin Commands
+================
+
+Applications which subclass :class:`cmd2.cmd2.Cmd` inherit a number of commands
+which may be useful to your users.
+
+edit
+----
+
+This command launches an editor program and instructs it to open the given file
+name. Here's an example::
+
+  (Cmd) edit ~/.ssh/config
+
+The program to be launched is determined by the value of the
+:ref:`features/settings:editor` setting.
+
+
+set
+---
+
+A list of all user-settable parameters, with brief comments, is viewable from
+within a running application::
+
+    (Cmd) set --long
+    allow_ansi: Terminal           # Allow ANSI escape sequences in output (valid values: Terminal, Always, Never)
+    continuation_prompt: >         # On 2nd+ line of input
+    debug: False                   # Show full error stack on error
+    echo: False                    # Echo command issued into output
+    editor: vim                    # Program used by ``edit``
+    feedback_to_output: False      # include nonessentials in `|`, `>` results
+    locals_in_py: False            # Allow access to your application in py via self
+    max_completion_items: 50       # Maximum number of CompletionItems to display during tab completion
+    prompt: (Cmd)                  # The prompt issued to solicit input
+    quiet: False                   # Don't print nonessential feedback
+    timing: False                  # Report execution times
+
+Any of these user-settable parameters can be set while running your app with
+the ``set`` command like so::
+
+    (Cmd) set allow_ansi Never
+
+
+Removing A Builtin Command
+--------------------------
+
+[TODO] show how to remove a builtin command if you don't want it available to
+your users.
diff --git a/docs/features/index.rst b/docs/features/index.rst
index efeb9e6c..dc64badd 100644
--- a/docs/features/index.rst
+++ b/docs/features/index.rst
@@ -5,6 +5,7 @@ Features
    :maxdepth: 1
 
    argument_processing
+   builtin_commands
    clipboard
    commands
    completion
diff --git a/docs/features/settings.rst b/docs/features/settings.rst
index f117c171..e1564ef6 100644
--- a/docs/features/settings.rst
+++ b/docs/features/settings.rst
@@ -1,36 +1,25 @@
 Settings
 ========
 
-- current settings and what they do
-- how a developer can add their own
-- how to hide built in settings from a user
+Settings provide a mechanism for a user to control the behavior of a ``cmd2``
+based application. A setting is stored in an instance attribute on your
+subclass of :class:`cmd2.cmd2.Cmd` and must also appear in the
+:attr:`cmd2.cmd2.Cmd.settable` dictionary. Developers may set default values
+for these settings and users can modify them at runtime using the
+:ref:`features/builtin_commands:set` command. Developers can
+:ref:`features/settings:Create New Settings` and can also
+:ref:`features/settings:Hide Builtin Settings` from the user.
 
-Built In Settings
------------------
-
-``cmd2`` has a number of built in settings, which a developer can set a default
-value, and which users can modify to change the behavior of the application.
 
-A list of all user-settable parameters, with brief comments, is viewable from
-within a running application::
+Builtin Settings
+-----------------
 
-    (Cmd) set --long
-    allow_ansi: Terminal           # Allow ANSI escape sequences in output (valid values: Terminal, Always, Never)
-    continuation_prompt: >         # On 2nd+ line of input
-    debug: False                   # Show full error stack on error
-    echo: False                    # Echo command issued into output
-    editor: vim                    # Program used by ``edit``
-    feedback_to_output: False      # include nonessentials in `|`, `>` results
-    locals_in_py: False            # Allow access to your application in py via self
-    max_completion_items: 50       # Maximum number of CompletionItems to display during tab completion
-    prompt: (Cmd)                  # The prompt issued to solicit input
-    quiet: False                   # Don't print nonessential feedback
-    timing: False                  # Report execution times
 
-Any of these user-settable parameters can be set while running your app with
-the ``set`` command like so::
+``cmd2`` has a number of builtin settings. These settings control the behavior
+of certain application features and :ref:`features/builtin_commands:Builtin
+Commands`. Users can use the :ref:`features/builtin_commands:set` command to
+show all settings and to modify the value of any setting.
 
-    (Cmd) set allow_ansi Never
 
 allow_ansi
 ~~~~~~~~~~
@@ -56,6 +45,16 @@ This setting can be one of three values:
 - ``Always`` - ANSI escape sequences are always passed through, regardless
 
 
+continuation_prompt
+~~~~~~~~~~~~~~~~~~~
+
+When a user types a :ref:`Multiline Command
+<features/multiline_commands:Multiline Commands>` it may span more than one
+line of input. The prompt for the first line of input is specified by the
+:ref:`features/settings:prompt` setting. The prompt for subsequent lines of
+input is defined by this setting.
+
+
 debug
 ~~~~~
 
@@ -72,6 +71,14 @@ If ``True``, each command the user issues will be repeated to the screen before
 it is executed.  This is particularly useful when running scripts.
 
 
+editor
+~~~~~~
+
+Similar to the ``EDITOR`` shell variable, this setting contains the name of the
+program which should be run by the :ref:`features/builtin_commands:edit`
+command.
+
+
 feedback_to_output
 ~~~~~~~~~~~~~~~~~~
 
@@ -85,10 +92,30 @@ feedback output will be mixed in with and indistinguishable from output
 generated with :meth:`~cmd2.cmd2.Cmd.poutput`.
 
 
+locals_in_py
+~~~~~~~~~~~~
+
+Allow access to your application in one of the
+:ref:`features/embedded_python_shells:Embedded Python Shells` via ``self``.
+
+
+max_completion_items
+~~~~~~~~~~~~~~~~~~~~
+
+The maximum number of tab-completion items to display.
+
+
+prompt
+~~~~~~
+
+This setting contains the string which should be printed as a prompt for user
+input.
+
+
 quiet
 ~~~~~
 
-If ``True``, output generated by calling :meth:`~cmd2.Cmd.pfeedback` is
+If ``True``, output generated by calling :meth:`~.cmd2.Cmd.pfeedback` is
 suppressed. If ``False``, the :ref:`features/settings:feedback_to_output`
 setting controls where the output is sent.
 
@@ -96,8 +123,7 @@ setting controls where the output is sent.
 timing
 ~~~~~~
 
-Setting ``App.timing`` to ``True`` outputs timing data after every application
-command is executed.  |settable|
+If ``True``, the elapsed time is reported for each command executed.
 
 
 Create New Settings
@@ -137,5 +163,21 @@ changes a setting, and will receive both the old value and the new value.
    It's 13 C - are you a penguin?
 
 
-Hide Built-in Settings
+Hide Builtin Settings
 ----------------------
+
+You may want to prevent a user from modifying a builtin setting. A setting
+must appear in the :attr:`cmd2.cmd2.Cmd.settable` dictionary in order for it
+to be available to the :ref:`features/builtin_commands:set` command.
+
+Let's say your program does not have any
+:ref:`features/multiline_commands:Multiline Commands`. You might want to hide
+the :ref:`features/settings:continuation_prompt` setting from your users since
+it is only applicable to multiline commands. To do so, remove it from the
+:attr:`cmd2.cmd2.Cmd.settable` dictionary after you initialize your object::
+
+  class MyApp(cmd2.Cmd):
+
+    def __init__(self):
+        super().__init__()
+        self.settable.pop('continuation_prompt')