bpo-33185: Improve wording and markup (GH-6477)

Adds some working and markup fixes that I missed
in the initial commit for this issue.

(Follow-up to GH-6419)

Author: ncoghlan

Doc/whatsnew/3.7.rst

@@ -1144,11 +1144,13 @@ Changes in Python behavior
   parentheses can be omitted only on calls.
   (Contributed by Serhiy Storchaka in :issue:`32012` and :issue:`32023`.)
 
-* When using the ``-m`` switch, the starting directory is now added to sys.path,
-  rather than the current working directory. Any programs that are checking for
-  the empty string in :data:`sys.path`, or otherwise relying on the previous
-  behaviour, will need to be updated accordingly (e.g. by checking for
-  ``os.getcwd()`` in addition to checking for the empty string).
+* When using the :option:`-m` switch, the initial working directory is now added
+  to :data:`sys.path`, rather than an empty string (which dynamically denoted
+  the current working directory at the time of each import). Any programs that
+  are checking for the empty string, or otherwise relying on the previous
+  behaviour, will need to be updated accordingly (e.g. by also checking for
+  ``os.getcwd()`` or ``os.path.dirname(__main__.__file__)``, depending on why
+  the code was checking for the empty string in the first place).
 
 
 Changes in the Python API

Lib/pydoc.py

@@ -2643,7 +2643,7 @@ def _get_revised_path(given_path, argv0):
 
 # Note: the tests only cover _get_revised_path, not _adjust_cli_path itself
 def _adjust_cli_sys_path():
-    """Ensures current directory is on sys.path, and __main__ directory is not
+    """Ensures current directory is on sys.path, and __main__ directory is not.
 
     Exception: __main__ dir is left alone if it's also pydoc's directory.
     """

Lib/test/test_pydoc.py

@@ -1103,7 +1103,7 @@ def _get_revised_path(self, given_path, argv0=None):
         return pydoc._get_revised_path(given_path, argv0)
 
     def _get_starting_path(self):
-        # Get a copy of sys.path without the current directory
+        # Get a copy of sys.path without the current directory.
         clean_path = sys.path.copy()
         for spelling in self.curdir_spellings:
             for __ in range(clean_path.count(spelling)):

Misc/NEWS.d/next/Library/2018-04-08-22-54-07.bpo-33185.Id-Ba9.rst

@@ -1,5 +1,5 @@
-Fixed regression when running pydoc with the ``-m`` switch. (The regression
-was introduced in 3.7.0b3 by the resolution of bpo-33053)
+Fixed regression when running pydoc with the :option:`-m` switch. (The regression
+was introduced in 3.7.0b3 by the resolution of :issue:`33053`)
 
-This fix also changed pydoc to add ``os.getcwd()`` to ``sys.path`` when
+This fix also changed pydoc to add ``os.getcwd()`` to :data:`sys.path` when
 necessary, rather than adding ``"."``.