diff --git a/doc/how-to-source-packages.rst b/doc/how-to-source-packages.rst
index 385dba47d88..94b613090c1 100644
--- a/doc/how-to-source-packages.rst
+++ b/doc/how-to-source-packages.rst
@@ -87,13 +87,10 @@ tools to interpret and make effective use of this information.
 
    The ``source-repository-package`` field, the one with a "-package" suffix,
    doesn't belong to a package! It's for a project dependency. This name is a
-   bit misleading because it can describe multiple dependencies and not just
-   one. That it is for "package" also makes sense. Ultimately it is the union of
-   all dependencies of local packages within the project that actually declare
-   the set of project dependencies, not the project.  The project can tighten
-   version constraint ranges with ``constraints`` or loosen them with
-   ``allow-newer`` or ``allow-older`` but it cannot add or remove dependencies.
-
+   bit misleading being singular because it can describe multiple dependency
+   packages at the same location, each offset by a directory containing a
+   package description, a ``.cabal`` file.
+   
    This project stanza is like a redirect or override for dependencies of all
    the packages in the project saying "use this source code repository" for this
    package dependency, not Hackage.
@@ -116,6 +113,16 @@ tools to interpret and make effective use of this information.
          location: https://github.com/haskell/vector.git
          subdir:   vector
 
+.. Warning::
+
+   Cabal project, ``cabal.project``, files don't declare dependencies!
+   
+   The union of the dependencies of all ``packages`` within the project declares
+   the set of project dependencies.  While the project can tighten version
+   constraint ranges with ``constraints`` or loosen them with ``allow-newer`` or
+   ``allow-older``, it cannot add package names to or remove package names from
+   the set of dependencies.
+
 .. _pkg-consumers:
 
 *Source code* when taking a package dependency