Integrate the unfreefeatures legacy documentation

1 files changed, 0 insertions, 231 deletions

diff --git a/docs/unfreefeatures.rst b/docs/unfreefeatures.rst
deleted file mode 100644
index 19c4e547..00000000
--- a/docs/unfreefeatures.rst
+++ /dev/null
@@ -1,231 +0,0 @@
-Features requiring application changes
-======================================
-
-
-Parsed statements
------------------
-
-``cmd2`` passes ``arg`` to a ``do_`` method (or ``default``) as a Statement, a
-subclass of string that includes many attributes of the parsed input:
-
-command
-    Name of the command called
-
-args
-    The arguments to the command with output redirection
-    or piping to shell commands removed
-
-command_and_args
-    A string of just the command and the arguments, with
-    output redirection or piping to shell commands removed
-
-argv
-    A list of arguments a-la ``sys.argv``, including
-    the command as ``argv[0]`` and the subsequent
-    arguments as additional items in the list.
-    Quotes around arguments will be stripped as will
-    any output redirection or piping portions of the command
-
-raw
-    Full input exactly as typed.
-
-terminator
-    Character used to end a multiline command
-
-
-
-If ``Statement`` does not contain an attribute, querying for it will return
-``None``.
-
-(Getting ``arg`` as a ``Statement`` 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* any of the additional attributes.)
-
-.. _cmd: https://docs.python.org/3/library/cmd.html
-
-
-Environment parameters
-----------------------
-
-Your application can define user-settable parameters which your code can
-reference. First create a class attribute with the default value. Then update
-the ``settable`` dictionary with your setting name and a short description
-before you initialize the superclass. Here's an example, from
-``examples/environment.py``:
-
-.. literalinclude:: ../examples/environment.py
-
-If you want to be notified when a setting changes (as we do above), then define
-a method ``_onchange_{setting}()``. This method will be called after the user
-changes a setting, and will receive both the old value and the new value.
-
-.. code-block:: text
-
-   (Cmd) set --long | grep sunny
-   sunny: False                # Is it sunny outside?
-   (Cmd) set --long | grep degrees
-   degrees_c: 22               # Temperature in Celsius
-   (Cmd) sunbathe
-   Too dim.
-   (Cmd) set degrees_c 41
-   degrees_c - was: 22
-   now: 41
-   (Cmd) set sunny
-   sunny: True
-   (Cmd) sunbathe
-   UV is bad for your skin.
-   (Cmd) set degrees_c 13
-   degrees_c - was: 41
-   now: 13
-   (Cmd) sunbathe
-   It's 13 C - are you a penguin?
-
-
-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 argparse_ to parse the flags, and they work the same way as for that
-module.
-
-``cmd2`` defines a few decorators which change the behavior of how arguments
-get parsed for and passed to a ``do_`` method.  See the section
-:ref:`decorators` for more information.
-
-.. _argparse: https://docs.python.org/3/library/argparse.html
-
-poutput, pfeedback, perror, ppaged
-==================================
-
-Standard ``cmd`` applications produce their output with
-``self.stdout.write('output')`` (or with ``print``, but ``print`` decreases
-output flexibility).  ``cmd2`` applications can use ``self.poutput('output')``,
-``self.pfeedback('message')``, ``self.perror('errmsg')``, and
-``self.ppaged('text')`` instead.  These methods have these advantages:
-
-- Handle output redirection to file and/or pipe appropriately
-- More concise
-    - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter.
-- Option to display long output using a pager via ``ppaged()``
-
-.. automethod:: cmd2.cmd2.Cmd.poutput
-    :noindex:
-.. automethod:: cmd2.cmd2.Cmd.perror
-    :noindex:
-.. automethod:: cmd2.cmd2.Cmd.pfeedback
-    :noindex:
-.. automethod:: cmd2.cmd2.Cmd.ppaged
-    :noindex:
-
-
-Colored Output
-==============
-
-The output methods in the previous section all honor the ``allow_ansi``
-setting, which has three possible values:
-
-Never
-    poutput(), pfeedback(), and ppaged() strip all ANSI escape sequences
-    which instruct the terminal to colorize output
-
-Terminal
-    (the default value) poutput(), pfeedback(), and ppaged() do not strip any
-    ANSI escape sequences when the output is a terminal, but if the output is a
-    pipe or a file the escape sequences are stripped. If you want colorized
-    output you must add ANSI escape sequences using either cmd2's internal ansi
-    module or another color library such as `plumbum.colors`, `colorama`, or
-    `colored`.
-
-Always
-    poutput(), pfeedback(), and ppaged() never strip ANSI escape sequences,
-    regardless of the output destination
-
-Colored and otherwise styled output can be generated using the `ansi.style()`
-function:
-
-.. automethod:: cmd2.ansi.style
-
-
-.. _quiet:
-
-Suppressing non-essential output
-================================
-
-The ``quiet`` setting controls whether ``self.pfeedback()`` actually produces
-any output. If ``quiet`` is ``False``, then the output will be produced. If
-``quiet`` is ``True``, no output will be produced.
-
-This makes ``self.pfeedback()`` useful for non-essential output like status
-messages. Users can control whether they would like to see these messages by
-changing the value of the ``quiet`` setting.
-
-
-select
-======
-
-Presents numbered options to user, as bash ``select``.
-
-``app.select`` is called from within a method (not by the user directly; it is
-``app.select``, not ``app.do_select``).
-
-.. automethod:: cmd2.cmd2.Cmd.select
-    :noindex:
-
-::
-
-    def do_eat(self, arg):
-        sauce = self.select('sweet salty', 'Sauce? ')
-        result = '{food} with {sauce} sauce, yum!'
-        result = result.format(food=arg, sauce=sauce)
-        self.stdout.write(result + '\n')
-
-::
-
-    (Cmd) eat wheaties
-        1. sweet
-        2. salty
-    Sauce? 2
-    wheaties with salty sauce, yum!
-
-
-Exit code to shell
-==================
-
-The ``self.exit_code`` attribute of your ``cmd2`` application controls what
-exit code is returned from ``cmdloop()`` when it completes.  It is your job to
-make sure that this exit code gets sent to the shell when your application
-exits by calling ``sys.exit(app.cmdloop())``.
-
-
-Disabling Commands
-==================
-
-``cmd2`` supports disabling commands during runtime. This is useful if certain
-commands should only be available when the application is in a specific state.
-When a command is disabled, it will not show up in the help menu or tab
-complete. If a user tries to run the command, a command-specific message
-supplied by the developer will be printed. The following functions support this
-feature.
-
-enable_command()
-    Enable an individual command
-
-enable_category()
-    Enable an entire category of commands
-
-disable_command()
-    Disable an individual command and set the message that will print when this
-    command is run or help is called on it while disabled
-
-disable_category()
-    Disable an entire category of commands and set the message that will print
-    when anything in this category is run or help is called on it while
-    disabled
-
-See the definitions of these functions for descriptions of their arguments.
-
-See the ``do_enable_commands()`` and ``do_disable_commands()`` functions in the
-HelpCategories_ example for a demonstration.
-
-.. _HelpCategories: https://github.com/python-cmd2/cmd2/blob/master/examples/help_categories.py