Tweak docs about version_path_separator

1 files changed, 9 insertions, 3 deletions

diff --git a/docs/build/tutorial.rst b/docs/build/tutorial.rst
index cf3fe19..fffd074 100644
--- a/docs/build/tutorial.rst
+++ b/docs/build/tutorial.rst
@@ -162,16 +162,18 @@ The file generated with the "generic" configuration looks like::
     # version location specification; This defaults
     # to ${script_location}/versions.  When using multiple version
     # directories, initial revisions must be specified with --version-path.
-    # The path separator used here should be the separator specified by "version_path_separator"
+    # The path separator used here should be the separator specified by "version_path_separator" below.
     # version_locations = %(here)s/bar:%(here)s/bat:${script_location}/versions
 
     # version path separator; As mentioned above, this is the character used to split
-    # version_locations. Valid values are:
+    # version_locations. The default within new alembic.ini files is "os", which uses os.pathsep.
+    # If this key is omitted entirely, it falls back to the legacy behavior of splitting on spaces and/or commas.
+    # Valid values for version_path_separator are:
     #
     # version_path_separator = :
     # version_path_separator = ;
     # version_path_separator = space
-    version_path_separator = os  # default: use os.pathsep
+    version_path_separator = os  # Use os.pathsep. Default configuration used for new projects.
 
     # the output encoding used when revision files
     # are written from script.py.mako
@@ -307,6 +309,10 @@ This file contains the following features:
   allow revisions to exist in multiple directories simultaneously.
   See :ref:`multiple_bases` for examples.
 
+* ``version_path_separator`` - a separator of ``version_locations`` paths.
+  It should be defined if multiple ``version_locations`` is used.
+  See :ref:`multiple_bases` for examples.
+
 * ``output_encoding`` - the encoding to use when Alembic writes the
   ``script.py.mako`` file into a new migration file.  Defaults to ``'utf-8'``.