Minor updates to the documentation (#1540)rewrite

1 files changed, 25 insertions, 23 deletions

diff --git a/docs/cli_interface.rst b/docs/cli_interface.rst
index ac27056..f3cca80 100644
--- a/docs/cli_interface.rst
+++ b/docs/cli_interface.rst
@@ -3,18 +3,20 @@ CLI interface
 
 .. _cli_flags:
 
-cli flags
+CLI flags
 ~~~~~~~~~
 
-``virtualenv`` is primarily a command line interface application. It's mainly aimed to be used from a command line, as
-such you'll need to to have a shell to run it. Then you can type in ``virtualenv`` (name of the application) followed by
-flags that control its behaviour. All options do have a sensible default, so if you pass no options you'll get a
-virtual environment in the current working directories ``venv`` folder. The Default values for the command line
-options can be modified either via the :ref:`conf_file` or :ref:`env_vars`. Environment variables takes priority over
-the configuration file values (the ``--help`` will show if a default comes from the environment variable as the help
-message will end in this case either with ``via env var`` or ``via config file``).
+``virtualenv`` is primarily a command line application.
 
-Below you can see the options you can pass in, together with its default value, and a short description of what it does:
+It modifies the environment variables in a shell to create an isolated Python environment, so you'll need to have a
+shell to run it. You can type in ``virtualenv`` (name of the application) followed by flags that control its
+behaviour. All options have sensible defaults, so you'll get a working virtual environment in a ``venv`` folder even
+if you don't pass any options. The default values for the command line options can be overridden via the
+:ref:`conf_file` or :ref:`env_vars`. Environment variables takes priority over the configuration file values
+(``--help`` will show if a default comes from the environment variable as the help message will end in this case
+with environment variables or the configuration file).
+
+The options that can be passed to virtualenv, along with their default values and a short description are listed below.
 
 :command:`virtualenv [OPTIONS]`
 
@@ -30,19 +32,19 @@ Defaults
 Configuration file
 ^^^^^^^^^^^^^^^^^^
 
-virtualenv looks for a standard ini config file. The exact place depends on the operating system you're using, as
-determined by :pypi:`appdirs` application data definition. The config file location is printed as epilog for the CLI
-tools help message.
+virtualenv looks for a standard ini configuration file. The exact location depends on the operating system you're using,
+as determined by :pypi:`appdirs` application data definition. The configuration file location is printed as at the end of
+the output when ``--help`` is passed.
 
-The keys of the settings are derived from the long command line option, e.g. the option :option:`--python <python>`
-would look like this:
+The keys of the settings are derived from the long command line option. For example, :option:`--python <python>`
+would be specified as:
 
 .. code-block:: ini
 
   [virtualenv]
   python = /opt/python-3.3/bin/python
 
-Appending options like :option:`extra-search-dir` can be written on multiple lines:
+Options that take multiple values, like :option:`extra-search-dir` can be specified as:
 
 .. code-block:: ini
 
@@ -56,25 +58,25 @@ Appending options like :option:`extra-search-dir` can be written on multiple lin
 Environment Variables
 ^^^^^^^^^^^^^^^^^^^^^
 
-Each command line option is automatically used to look for environment variables with the name format
-``VIRTUALENV_<UPPER_NAME>``. That means the name of the command line options are capitalized and have dashes (``'-'``)
-replaced with underscores (``'_'``).
+Each command line option has a corresponding environment variables with the name format
+``VIRTUALENV_<UPPER_NAME>``. The ``UPPER_NAME`` is the name of the command line options capitalized and
+dashes (``'-'``) replaced with underscores (``'_'``).
 
-For example, to automatically use a custom Python binary instead of the one virtualenv is run with you can also set an
-environment variable:
+For example, to use a custom Python binary, instead of the one virtualenv is run with, you can set the environment
+variable ``VIRTUALENV_PYTHON`` like:
 
 .. code-block:: console
 
    env VIRTUALENV_PYTHON=/opt/python-3.8/bin/python virtualenv
 
-This also works for appending command line options, like :option:`extra-search-dir`. Just pass a literal newline
-between the passed values, e.g.:
+This also works for appending command line options, like :option:`extra-search-dir`, where a literal newline
+is used to separate the values:
 
 .. code-block:: console
 
   env VIRTUALENV_EXTRA_SEARCH_DIR="/path/to/dists\n/path/to/other/dists" virtualenv
 
-is the same as calling:
+The equivalent CLI-flags based invocation, for the above example, would be:
 
 .. code-block:: console