Add REVISION_SCRIPT_FILENAME token for post_write_hooks options

I include a token called `REVISION_SCRIPT_FILENAME` which can be used in the `options` setting of a post-write hook. This token is replaced by the filename of the revision script, allowing the filename to be passed to the post-write hook in a flexible manner. Thus I can do:

```ini
[post_write_hooks]
hooks = pre-commit
pre-commit.type = console_scripts
pre-commit.entrypoint = pre-commit
pre-commit.options = run --files REVISION_SCRIPT_FILENAME
```

Note that the existing behavior is to prepend `REVISION_SCRIPT_FILENAME` to the argument list. In order to preserve backwards compatibility, this is done when `REVISION_SCRIPT_FILENAME` is not present.

### Description
* Implement the `REVISION_SCRIPT_FILENAME` token.
* Switch from `str.split()` to `shlex.split()` for robust command line argument processing.
* Insert `REVISION_SCRIPT_FILENAME` in appropriate locations in the docs and templates.
* Properly document that `REVISION_SCRIPT_FILENAME` is prepended instead of appended to the argument list.
* Refactored existing "test of `black` as a post-write hook" in order to avoid code duplication.
* Add a test for `REVISION_SCRIPT_FILENAME` and shlex.

### Checklist
<!-- go over following points. check them with an `x` if they do apply, (they turn into clickable checkboxes once the PR is submitted, so no need to do everything at once)

-->

This pull request is:

- [X] A new feature implementation
	- please include the issue number, and create an issue if none exists, which must
	  include a complete example of how the feature would look.
	- Please include: `Fixes: #<issue number>` in the commit message
	- please include tests.

Fixes issue #819

Closes: #820
Pull-request: https://github.com/sqlalchemy/alembic/pull/820
Pull-request-sha: 73dd0a4d60758a06551a0aff47b9723b0345d74a

Change-Id: Ibfc677d59086703872d7cfd5c2da32bd0220a25f

1 files changed, 25 insertions, 23 deletions

diff --git a/docs/build/autogenerate.rst b/docs/build/autogenerate.rst
index 00fd743..a5129f8 100644
--- a/docs/build/autogenerate.rst
+++ b/docs/build/autogenerate.rst
@@ -738,42 +738,44 @@ generated file path.    Example::
   # format using "black"
   hooks=black
 
-  black.type=console_scripts
-  black.entrypoint=black
-  black.options=-l 79
+  black.type = console_scripts
+  black.entrypoint = black
+  black.options = -l 79
 
-Above, we configure a single post write hook that we call ``"black"``. Note
-that this name is arbitrary.  We then define the configuration for the
-``"black"`` post write hook, which includes:
+Above, we configure ``hooks`` to be a single post write hook labeled
+``"black"``.   Note that this label is arbitrary.   We then define the
+configuration for the ``"black"`` post write hook, which includes:
 
-* ``type`` - this is the type of hook we are running.   Alembic includes
+* ``type`` - this is the type of hook we are running.  Alembic includes
   a hook runner called ``"console_scripts"``, which is specifically a
   Python function that uses ``subprocess.run()`` to invoke a separate
-  Python script against the revision file.    For a custom-written hook
+  Python script against the revision file.  For a custom-written hook
   function, this configuration variable would refer to the name under
   which the custom hook was registered; see the next section for an example.
 
 * ``entrypoint`` - this part of the configuration is specific to the
   ``"console_scripts"`` hook runner.  This is the name of the `setuptools entrypoint <https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points>`_
-  that is used to define the console script.    Within the scope of standard
+  that is used to define the console script.   Within the scope of standard
   Python console scripts, this name will match the name of the shell command
   that is usually run for the code formatting tool, in this case ``black``.
 
 * ``options`` - this is also specific to the ``"console_scripts"`` hook runner.
   This is a line of command-line options that will be passed to the
   code formatting tool.  In this case, we want to run the command
-  as ``black -l 79 /path/to/revision.py``.   The path of the revision file
-  is sent as a single positional argument to the script after the options.
+  ``black /path/to/revision.py -l 79``.  By default, the revision path is
+  positioned as the first argument.  In order specify a different position,
+  we can use the ``REVISION_SCRIPT_FILENAME`` token as illustrated by the
+  subsequent examples.
 
   .. note:: Make sure options for the script are provided such that it will
      rewrite the input file **in place**.  For example, when running
      ``autopep8``, the ``--in-place`` option should be provided::
 
         [post_write_hooks]
-        hooks=autopep8
-        autopep8.type=console_scripts
-        autopep8.entrypoint=autopep8
-        autopep8.options=--in-place
+        hooks = autopep8
+        autopep8.type = console_scripts
+        autopep8.entrypoint = autopep8
+        autopep8.options = --in-place REVISION_SCRIPT_FILENAME
 
 
 When running ``alembic revision -m "rev1"``, we will now see the ``black``
@@ -798,13 +800,13 @@ configuration as follows::
   # format using "black", then "zimports"
   hooks=black, zimports
 
-  black.type=console_scripts
-  black.entrypoint=black
-  black.options=-l 79
+  black.type = console_scripts
+  black.entrypoint = black
+  black.options = -l 79 REVISION_SCRIPT_FILENAME
 
-  zimports.type=console_scripts
-  zimports.entrypoint=zimports
-  zimports.options=--style google
+  zimports.type = console_scripts
+  zimports.entrypoint = zimports
+  zimports.options = --style google REVISION_SCRIPT_FILENAME
 
 When using the above configuration, a newly generated revision file will
 be processed first by the "black" tool, then by the "zimports" tool.
@@ -855,9 +857,9 @@ Our new ``"spaces_to_tabs"`` hook can be configured in alembic.ini as follows::
 
   [post_write_hooks]
 
-  hooks=spaces_to_tabs
+  hooks = spaces_to_tabs
 
-  spaces_to_tabs.type=spaces_to_tabs
+  spaces_to_tabs.type = spaces_to_tabs
 
 
 When ``alembic revision`` is run, the ``env.py`` file will be loaded in all