Make some minor revisions/corrections to the docs (#2542)

Makes some minor revisions & grammatical corrections to the docs.  Some
notable items:

- tries to make references to PEP 8 consistent (rather than PEP-8, PEP 8,
  PEP-08, etc)
- general typos

4 files changed, 33 insertions, 37 deletions

diff --git a/doc/intro.rst b/doc/intro.rst
index a249b494d..aea0495e4 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -8,12 +8,12 @@ What is Pylint?
 ---------------
 
 Pylint is a tool that checks for errors in Python code, tries to enforce a
-coding standard and looks for code smells. It can also look for certain type
+coding standard and looks for `code smells`_. It can also look for certain type
 errors, it can recommend suggestions about how particular blocks
 can be refactored and can offer you details about the code's complexity.
 
 Other similar projects would include pychecker_ (now defunct), pyflakes_,
-flake8_, and mypy_. The default coding style used by Pylint is close to `PEP 008`_.
+flake8_, and mypy_. The default coding style used by Pylint is close to `PEP 8`_.
 
 Pylint will display a number of messages as it analyzes the code and it can
 also be used for displaying some statistics about the number of warnings and
@@ -27,9 +27,10 @@ severity of the warnings and errors.
 .. _pyflakes: https://github.com/pyflakes/pyflakes
 .. _flake8: https://gitlab.com/pycqa/flake8/
 .. _mypy: https://github.com/JukkaL/mypy
-.. _`PEP 008`: https://www.python.org/dev/peps/pep-0008/
+.. _`PEP 8`: https://www.python.org/dev/peps/pep-0008/
 .. _`Guido's style guide`: https://www.python.org/doc/essays/styleguide/
 .. _`refactoring book`: https://www.refactoring.com/
+.. _`code smells`: https://martinfowler.com/bliki/CodeSmell.html
 
 What Pylint is not?
 -------------------
diff --git a/doc/tutorial.rst b/doc/tutorial.rst
index 77610d04c..92f48092c 100644
--- a/doc/tutorial.rst
+++ b/doc/tutorial.rst
@@ -18,8 +18,9 @@ in open source.  Whatever the motivation, your good intentions may not have the
 desired outcome if people find your code hard to use or understand.  The Python
 community has formalized some recommended programming styles to help everyone
 write code in a common, agreed-upon style that makes the most sense for shared
-code.  This style is captured in PEP-8_.  Pylint can be a quick and easy way of
-seeing if your code has captured the essence of PEP-8 and is therefore
+code.  This style is captured in `PEP 8`_, the "Style Guide for Python Code".  
+Pylint can be a quick and easy way of
+seeing if your code has captured the essence of `PEP 8`_ and is therefore
 ``friendly`` to other potential users.
 
 Perhaps you're not ready to share your code but you'd like to learn a bit more
@@ -37,7 +38,7 @@ My command line prompt for these examples is:
 
   robertk01 Desktop$
 
-.. _PEP-8: http://www.python.org/dev/peps/pep-0008/
+.. _PEP 8: http://www.python.org/dev/peps/pep-0008/
 
 Getting Started
 ---------------
@@ -96,8 +97,7 @@ preferences a bit better (and thus make it emit messages only when needed).
 Your First Pylint'ing
 ---------------------
 
-We'll use a basic python script as fodder for our tutorial.  I borrowed
-extensively from the code here: http://www.daniweb.com/code/snippet748.html
+We'll use a basic Python script as fodder for our tutorial.
 The starting code we will use is called simplecaeser.py and is here in its
 entirety:
 
@@ -173,7 +173,7 @@ command line and try this:
   belongs to the basic checker.
 
 
-Yeah, ok. That one was a bit of a no-brainer but I have run into error messages
+Yeah, ok. That one was a bit of a no-brainer, but I have run into error messages
 that left me with no clue about what went wrong, simply because I was unfamiliar
 with the underlying mechanism of code theory.  One error that puzzled my newbie
 mind was: ::
@@ -192,9 +192,9 @@ do with the remaining warnings.
 
 If we add a docstring to describe what the code is meant to do that will help.
 There are 5 ``invalid-name`` messages that we will get to later.  Lastly, I
-violated the convention of using spaces around an operator such as "=" so I'll
+violated the convention of using spaces around an operator such as ``=`` so I'll
 fix that too. To sum up, I'll add a docstring to line 2, and put spaces around
-the = sign on line 16.
+the ``=`` sign on line 16.
 
 Here is the updated code:
 
@@ -253,9 +253,9 @@ in the name.  This lends itself well to checking via a regular expression, thus
 the **should match (([A-Z\_][A-Z1-9\_]*)|(__.*__))$**.
 
 In this case Pylint is telling me that those variables appear to be constants
-and should be all UPPERCASE. This is an in-house convention that lives with Pylint
+and should be all UPPERCASE. This is an in-house convention that has lived with Pylint
 since its inception. You too can create your own in-house naming
-conventions but for the purpose of this tutorial, we want to stick to the PEP-8
+conventions but for the purpose of this tutorial, we want to stick to the `PEP 8`_
 standard. In this case, the variables I declared should follow the convention
 of all lowercase.  The appropriate rule would be something like:
 "should match [a-z\_][a-z0-9\_]{2,30}$".  Notice the lowercase letters in the
@@ -277,8 +277,8 @@ example but go ahead and `read up`_ on them if you want.
 
 .. tip::
  It would really be a pain to specify that regex on the command line all the time, particularly if we're using many other options.
- That's what the configuration file is for. We can configure our Pylint to
- store our options for us so we don't have to declare them on the command line.  Using the configuration file is a nice way of formalizing your rules and
+ That's what a configuration file is for. We can configure our Pylint to
+ store our options for us so we don't have to declare them on the command line.  Using a configuration file is a nice way of formalizing your rules and
  quickly sharing them with others. Invoking ``pylint --generate-rcfile`` will create a sample rcfile with all the options set and explained in comments.
 
 That's it for the basic intro. More tutorials will follow.
diff --git a/doc/user_guide/installation.rst b/doc/user_guide/installation.rst
index 53bb433a9..0b72b3bf6 100644
--- a/doc/user_guide/installation.rst
+++ b/doc/user_guide/installation.rst
@@ -25,4 +25,3 @@ directory and simply run ::
 Or you can install it in editable mode, using ::
 
     python setup.py develop
-
diff --git a/doc/user_guide/run.rst b/doc/user_guide/run.rst
index 37f140867..ca7e3f16b 100644
--- a/doc/user_guide/run.rst
+++ b/doc/user_guide/run.rst
@@ -17,7 +17,7 @@ You should pay attention to your ``PYTHONPATH``, since it is a common error
 to analyze an installed version of a module instead of the
 development version.
 
-It is also possible to analyze python files, with a few
+It is also possible to analyze Python files, with a few
 restrictions. The thing to keep in mind is that Pylint will try to
 convert the file name to a module name, and only be able to process
 the file if it succeeds.  ::
@@ -35,9 +35,9 @@ python path.
 
 For more details on this see the :ref:`faq`.
 
-It is also possible to call Pylint from another python program,
-thanks to ``Run()`` function in ``pylint.lint`` module,
-assuming Pylint options are stored in a list of strings ``pylint_options``, as:
+It is also possible to call Pylint from another Python program,
+thanks to the ``Run()`` function in the ``pylint.lint`` module
+(assuming Pylint options are stored in a list of strings ``pylint_options``) as:
 
 .. sourcecode:: python
 
@@ -62,14 +62,14 @@ First of all, we have two basic (but useful) options.
 --version             show program's version number and exit
 -h, --help            show help about the command line options
 
-Pylint is architectured around several checkers. you can disable a specific
-checker or some of its messages or messages categories by specifying
+Pylint is architected around several checkers. You can disable a specific
+checker or some of its messages or message categories by specifying
 ``--disable=<symbol>``. If you want to enable only some checkers or some
 message symbols, first use ``--disable=all`` then
-``--enable=<symbol>`` with <symbol> being a comma separated list of checker
+``--enable=<symbol>`` with ``<symbol>`` being a comma-separated list of checker
 names and message symbols. See the list of available features for a
 description of provided checkers with their functionalities.
-The ``--disable`` and ``--enable`` options can be used with comma separated lists
+The ``--disable`` and ``--enable`` options can be used with comma-separated lists
 mixing checkers, message ids and categories like ``-d C,W,no-error,design``
 
 It is possible to disable all messages with ``--disable=all``. This is
@@ -77,7 +77,7 @@ useful to enable only a few checkers or a few messages by first
 disabling everything, and then re-enabling only what you need.
 
 Each checker has some specific options, which can take either a yes/no
-value, an integer, a python regular expression, or a comma separated
+value, an integer, a python regular expression, or a comma-separated
 list of values (which are generally used to override a regular
 expression in special cases). For a full list of options, use ``--help``
 
@@ -109,7 +109,7 @@ includes:
 * Any configuration file found as explained above
 * Options appearing before ``--generate-rcfile`` on the Pylint command line
 
-Of course you can also start with the default values and hand tune the
+Of course you can also start with the default values and hand-tune the
 configuration.
 
 Other useful global options include:
@@ -126,10 +126,10 @@ Parallel execution
 ------------------
 
 It is possible to speed up the execution of Pylint. If the running computer
-has more CPUs than one, then the files for checking could be spread on all
+has more CPUs than one, then the work for checking all files could be spread across all
 cores via Pylints's sub-processes.
-This functionality is exposed via ``-j`` command line parameter.
-If the provided number is 0, then the total number of CPUs will be used.
+This functionality is exposed via the ``-j`` command-line parameter.
+If the provided number is 0, then the total number of CPUs will be autodetected and used.
 
 Example::
 
@@ -137,21 +137,17 @@ Example::
 
 This will spawn 4 parallel Pylint sub-process, where each provided module will
 be checked in parallel. Discovered problems by checkers are not displayed
-immediately. They are shown just after completing checking a module.
+immediately. They are shown just after checking a module is complete.
 
-There are some limitations in running checks in parallel in current
+There are some limitations in running checks in parallel in the current
 implementation. It is not possible to use custom plugins
 (i.e. ``--load-plugins`` option), nor it is not possible to use
-initialization hooks (i.e. ``--init-hook`` option).
-
-This will spawn 4 parallel Pylint subprocesses, each provided module being checked
-by one or another subprocess.
-
+initialization hooks (i.e. the ``--init-hook`` option).
 
 Exit codes
 ----------
 
-Pylint returns bit-encoded exit codes. If applicable the table lists related
+Pylint returns bit-encoded exit codes. If applicable, the table below lists the related
 stderr stream message output.
 
 =========  =========================  ==========================================