Wordier explanation of the active-repositories: configuration field. (#…

…7453)

Co-authored-by: Daniel Díaz <[email protected]>
Co-authored-by: Francesco Gazzetta <[email protected]>
Co-authored-by: Emily Pillmore <[email protected]>
Co-authored-by: Javier Neira <[email protected]>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

doc/cabal-project.rst

@@ -492,22 +492,59 @@ The following settings control the behavior of the dependency solver:
 
     :default: ``:rest``
 
-    This allows to specify the active package repositories,
-    when multiple are specified. This is useful as you
-    can specify the order and the way active repositories are merged.
+    Specifies which of the package repositories defined in the configuration
+    should be active. It's also useful for specifying the order and the way
+    active repositories are merged.
+
+    When searching for a certain version of a certain package name, the list of
+    active repositories is searched last-to-first. 
+
+    For example, suppose hackage.haskell.org has versions 1.0 and 2.0 of
+    package X, and my-repository has version 2.0 of a similarly named package.
+    Then, with the following configuration:
+
+    ::
+
+      -- Force my-repository to be the first repository considered
+      active-repositories:
+        , hackage.haskell.org
+        , my-repository
+
+    version 2.0 of X will come from my-repository, and version 1.0 will come
+    from hackage.haskell.org.
+
+    If we want to make a repository the sole provider of certain packages, we
+    can put it last in the active repositories list, and add the :override
+    modifier.
+
+    For example, if we modify the previous example like this:
 
     ::
 
-      -- for packages in head.hackage
-      -- only versions in head.hackage are considered
       active-repositories:
         , hackage.haskell.org
-        , head.hackage:override
+        , my-repository:override
+
+    then version 1.0 of package X won't be found in any case, because X is
+    present in my-repository only in version 2.0, and the :override forbids
+    searching for other versions of X further up the list.
+
+    :override has no effect for package names that aren't present in the
+    overriding repository.
 
-      -- Force head.hackage to be the primary repository considered
-      active-repositories: :rest, head.hackage
+    The special repository reference :rest stands for "all the other repositories"
+    and can be useful to avoid lenghty lists of repository names:
+
+    ::
+
+      -- Force my-repository to be the first repository considered
+      active-repositories: :rest, my-repository
+
+    The special repository reference "none" disables all repositories, effectively
+    putting cabal in "offline" mode:
+
+    ::
 
-      -- "Offline" mode
       active-repositories: none