Rename relative_to() to relative(), removing the old relative() method.

pep-0428.txt

@@ -383,8 +383,8 @@ as a factory function::
     >>> path_factory('bar')
     PurePosixPath('foo/bar')
 
-Changing the path name
-^^^^^^^^^^^^^^^^^^^^^^
+Changing the path's final component
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The ``with_name()`` method returns a new path, with the name changed::
 
@@ -404,9 +404,6 @@ It fails with a ``ValueError`` if the path doesn't have an actual name::
     >>> p.name
     ''
 
-Changing the path suffix
-^^^^^^^^^^^^^^^^^^^^^^^^
-
 The ``with_suffix()`` method returns a new path with the suffix changed.
 However, if the path has no suffix, the new suffix is added::
 
@@ -417,6 +414,24 @@ However, if the path has no suffix, the new suffix is added::
     >>> p.with_suffix('.bz2')
     PureNTPath('README.bz2')
 
+Making the path relative
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The ``relative()`` method computes the relative difference of a path to
+another::
+
+    >>> PurePosixPath('/usr/bin/python').relative('/usr')
+    PurePosixPath('bin/python')
+
+ValueError is raised if the method cannot return a meaningful value::
+
+    >>> PurePosixPath('/usr/bin/python').relative('/etc')
+    Traceback (most recent call last):
+      File "<stdin>", line 1, in <module>
+      File "pathlib.py", line 926, in relative
+        .format(str(self), str(formatted)))
+    ValueError: '/usr/bin/python' does not start with '/etc'
+
 
 Sequence-like access
 --------------------
@@ -481,18 +496,6 @@ as ``CON`` or ``NUL``.  It always returns False for POSIX paths.
     >>> PureNTPath('c:/PATHLIB/setup.py').match('c:*lib/*.PY')
     True
 
-``relative()`` returns a new relative path by stripping the drive and root::
-
-    >>> PurePosixPath('setup.py').relative()
-    PurePosixPath('setup.py')
-    >>> PurePosixPath('/setup.py').relative()
-    PurePosixPath('setup.py')
-
-``relative_to()`` computes the relative difference of a path to another::
-
-    >>> PurePosixPath('/usr/bin/python').relative_to('/usr')
-    PurePosixPath('bin/python')
-
 ``normcase()`` returns a case-folded version of the path for NT paths::
 
     >>> PurePosixPath('CAPS').normcase()