Merge pull request #1316 from strawstack/7.x

Increase readibility of 'why' page in docs

1 files changed, 27 insertions, 31 deletions

diff --git a/docs/why.rst b/docs/why.rst
index 75c1980..85e6a90 100644
--- a/docs/why.rst
+++ b/docs/why.rst
@@ -10,7 +10,7 @@ line utility for Python out there which ticks the following boxes:
 *   is lazily composable without restrictions
 *   supports implementation of Unix/POSIX command line conventions
 *   supports loading values from environment variables out of the box
-*   supports for prompting of custom values
+*   support for prompting of custom values
 *   is fully nestable and composable
 *   works the same in Python 2 and 3
 *   supports file handling out of the box
@@ -18,9 +18,9 @@ line utility for Python out there which ticks the following boxes:
     ANSI colors, fetching direct keyboard input, screen clearing,
     finding config paths, launching apps and editors, etc.)
 
-There are many alternatives to Click and you can have a look at them if
-you enjoy them better.  The obvious ones are ``optparse`` and ``argparse``
-from the standard library.
+There are many alternatives to Click; the obvious ones are ``optparse``
+and ``argparse`` from the standard library. Have a look to see if something
+else resonates with you.
 
 Click actually implements its own parsing of arguments and does not use
 ``optparse`` or ``argparse`` following the ``optparse`` parsing behavior.
@@ -28,13 +28,10 @@ The reason it's not based on ``argparse`` is that ``argparse`` does not
 allow proper nesting of commands by design and has some deficiencies when
 it comes to POSIX compliant argument handling.
 
-Click is designed to be fun to work with and at the same time not stand in
-your way.  It's not overly flexible either.  Currently, for instance, it
-does not allow you to customize the help pages too much. This is intentional
-because Click is designed to allow you to nest command line utilities.  The
-idea is that you can have a system that works together with another system by
-tacking two Click instances together and they will continue working as they
-should.
+Click is designed to be fun and customizable but not overly flexible.
+For instance, the customizability of help pages is constrained. This
+constraint is intentional because Click promises multiple Click instances
+will continue to function as intended when strung together.
 
 Too much customizability would break this promise.
 
@@ -43,31 +40,30 @@ microframework ecosystem because no tool could provide it with the
 functionality it needed.
 
 To get an understanding of what Click is all about, I strongly recommend
-looking at the :ref:`complex-guide` chapter to see what it's useful for.
+looking at the :ref:`complex-guide` chapter.
 
 Why not Argparse?
 -----------------
 
-Click is internally based on optparse instead of argparse.  This however
+Click is internally based on ``optparse`` instead of ``argparse``.  This
 is an implementation detail that a user does not have to be concerned
-with.  The reason however Click is not using argparse is that it has some
+with.  The reason Click is not using argparse is it has some
 problematic behaviors that make handling arbitrary command line interfaces
 hard:
 
 *   argparse has built-in magic behavior to guess if something is an
-    argument or an option.  This becomes a problem when dealing with
-    incomplete command lines as it's not possible to know without having a
-    full understanding of the command line how the parser is going to
-    behave.  This goes against Click's ambitions of dispatching to
-    subparsers.
+    argument or an option.  This behavior becomes a problem when dealing with
+    incomplete command lines; the parsers behaviour becomes unpredictable
+    without full knowledge of a command line.  This goes against Click's
+    ambitions of dispatching to subparsers.
 *   argparse currently does not support disabling of interspersed
-    arguments.  Without this feature it's not possible to safely implement
+    arguments.  Without this feature, it's not possible to safely implement
     Click's nested parsing nature.
 
 Why not Docopt etc.?
 --------------------
 
-Docopt and many tools like it are cool in how they work, but very few of
+Docopt, and many tools like, it are cool in how they work, but very few of
 these tools deal with nesting of commands and composability in a way like
 Click.  To the best of the developer's knowledge, Click is the first
 Python library that aims to create a level of composability of applications
@@ -78,13 +74,13 @@ according to those rules.  The side effect of this is that docopt is quite
 rigid in how it handles the command line interface.  The upside of docopt
 is that it gives you strong control over your help page; the downside is
 that due to this it cannot rewrap your output for the current terminal
-width and it makes translations hard.  On top of that docopt is restricted
+width, and it makes translations hard.  On top of that, docopt is restricted
 to basic parsing.  It does not handle argument dispatching and callback
 invocation or types.  This means there is a lot of code that needs to be
 written in addition to the basic help page to handle the parsing results.
 
 Most of all, however, it makes composability hard.  While docopt does
-support dispatching to subcommands, it for instance does not directly
+support dispatching to subcommands, it, for instance, does not directly
 support any kind of automatic subcommand enumeration based on what's
 available or it does not enforce subcommands to work in a consistent way.
 
@@ -95,25 +91,25 @@ following:
 -   Click does not just parse, it also dispatches to the appropriate code.
 -   Click has a strong concept of an invocation context that allows
     subcommands to respond to data from the parent command.
--   Click has strong information available for all parameters and commands
-    so that it can generate unified help pages for the full CLI and to
+-   Click has strong information available for all parameters and commands,
+    so it can generate unified help pages for the full CLI and
     assist the user in converting the input data as necessary.
--   Click has a strong understanding of what types are and can give the user
+-   Click has a strong understanding of what types are, and it can give the user
     consistent error messages if something goes wrong.  A subcommand
     written by a different developer will not suddenly die with a
     different error message because it's manually handled.
 -   Click has enough meta information available for its whole program
-    that it can evolve over time to improve the user experience without
+    to evolve over time and improve the user experience without
     forcing developers to adjust their programs.  For instance, if Click
     decides to change how help pages are formatted, all Click programs
     will automatically benefit from this.
 
-The aim of Click is to make composable systems, whereas the aim of docopt
+The aim of Click is to make composable systems. Whereas, the aim of docopt
 is to build the most beautiful and hand-crafted command line interfaces.
 These two goals conflict with one another in subtle ways.  Click
 actively prevents people from implementing certain patterns in order to
-achieve unified command line interfaces.  You have very little input on
-reformatting your help pages for instance.
+achieve unified command line interfaces.  For instance, as a developer, you
+are given very little choice in formatting your help pages.
 
 
 Why Hardcoded Behaviors?
@@ -144,7 +140,7 @@ even optparse and argparse support automatic expansion of long arguments.
 The reason for this is that it's a liability for backwards compatibility.
 If people start relying on automatically modified parameters and someone
 adds a new parameter in the future, the script might stop working.  These
-kinds of problems are hard to find so Click does not attempt to be magical
+kinds of problems are hard to find, so Click does not attempt to be magical
 about this.
 
 This sort of behavior however can be implemented on a higher level to