doc: Improve overrides and overlays documentation

2 files changed, 114 insertions, 92 deletions

diff --git a/doc/functions/overrides.xml b/doc/functions/overrides.xml
index 30cc6f3f6b1d..5532951d1a79 100644
--- a/doc/functions/overrides.xml
+++ b/doc/functions/overrides.xml
@@ -10,12 +10,9 @@
  </para>
 
  <para>
-  These overriding functions let you focus on one part of Nixpkgs and give you
-  back the requested variation. This is orthogonal but related to overlays and
-  the extending functions. Those also let you make modifications but return the
-  whole package set instead of just what you modified. When used together, the
-  override functions make the changes and overlays or extending functions add
-  those changes to the package sets.
+  These functions are used to make changes to packages, returning only single
+  packages. Overlays, on the other hand, can be used to combine the overridden
+  packages across the entire package set of Nixpkgs.
  </para>
 
  <section xml:id="sec-pkg-override">
diff --git a/doc/overlays.xml b/doc/overlays.xml
index af1ab26b5e97..90dd163072d3 100644
--- a/doc/overlays.xml
+++ b/doc/overlays.xml
@@ -17,97 +17,122 @@
   <title>Installing overlays</title>
 
   <para>
-   The list of overlays is determined as follows.
+   The list of overlays can be set either explicitly in a Nix expression, or
+   through <literal>&lt;nixpkgs-overlays></literal> or user configuration
+   files.
   </para>
 
-  <para>
-   If the <varname>overlays</varname> argument is not provided explicitly, we
-   look for overlays in a path. The path is determined as follows:
-   <orderedlist>
-    <listitem>
-     <para>
-      First, if an <varname>overlays</varname> argument to the nixpkgs function
-      itself is given, then that is used.
-     </para>
-     <para>
-      This can be passed explicitly when importing nixpkgs, for example
-      <literal>import &lt;nixpkgs> { overlays = [ overlay1 overlay2 ];
-      }</literal>.
-     </para>
-     <para>
-      Further overlays can be added by calling the
-      <literal>pkgs.extend</literal> or <literal>pkgs.appendOverlays</literal>,
-      although it is often preferable to avoid these functions, because they
-      recompute the Nixpkgs fixpoint, which is somewhat expensive to do.
-     </para>
-    </listitem>
-    <listitem>
-     <para>
-      Otherwise, if the Nix path entry <literal>&lt;nixpkgs-overlays></literal>
-      exists, we look for overlays at that path, as described below.
-     </para>
-     <para>
-      See the section on <literal>NIX_PATH</literal> in the Nix manual for more
-      details on how to set a value for
-      <literal>&lt;nixpkgs-overlays>.</literal>
-     </para>
-    </listitem>
-    <listitem>
-     <para>
-      If one of <filename>~/.config/nixpkgs/overlays.nix</filename> and
-      <filename>~/.config/nixpkgs/overlays/</filename> exists, then we look for
-      overlays at that path, as described below. It is an error if both exist.
-     </para>
-    </listitem>
-   </orderedlist>
-  </para>
+  <section xml:id="sec-overlays-argument">
+   <title>Set overlays in NixOS or Nix expressions</title>
 
-  <para>
-   If we are looking for overlays at a path, then there are two cases:
-   <itemizedlist>
-    <listitem>
-     <para>
-      If the path is a file, then the file is imported as a Nix expression and
-      used as the list of overlays.
-     </para>
-    </listitem>
-    <listitem>
-     <para>
-      If the path is a directory, then we take the content of the directory,
-      order it lexicographically, and attempt to interpret each as an overlay
-      by:
-      <itemizedlist>
-       <listitem>
-        <para>
-         Importing the file, if it is a <literal>.nix</literal> file.
-        </para>
-       </listitem>
-       <listitem>
-        <para>
-         Importing a top-level <filename>default.nix</filename> file, if it is
-         a directory.
-        </para>
-       </listitem>
-      </itemizedlist>
-     </para>
-    </listitem>
-   </itemizedlist>
-  </para>
+   <para>
+    On a NixOS system the value of the <literal>nixpkgs.overlays</literal>
+    option, if present, is passed to the system Nixpkgs directly as an
+    argument. Note that this does not affect the overlays for non-NixOS
+    operations (e.g. <literal>nix-env</literal>), which are
+    <link xlink:href="#sec-overlays-lookup">looked</link> up independently.
+   </para>
 
-  <para>
-   On a NixOS system the value of the <literal>nixpkgs.overlays</literal>
-   option, if present, is passed to the system Nixpkgs directly as an argument.
-   Note that this does not affect the overlays for non-NixOS operations (e.g.
-   <literal>nix-env</literal>), which are looked up independently.
-  </para>
+   <para>
+    The list of overlays can be passed explicitly when importing nixpkgs, for
+    example <literal>import &lt;nixpkgs> { overlays = [ overlay1 overlay2 ];
+    }</literal>.
+   </para>
 
-  <para>
-   The <filename>overlays.nix</filename> option therefore provides a convenient
-   way to use the same overlays for a NixOS system configuration and user
-   configuration: the same file can be used as
-   <filename>overlays.nix</filename> and imported as the value of
-   <literal>nixpkgs.overlays</literal>.
-  </para>
+   <para>
+    Further overlays can be added by calling the <literal>pkgs.extend</literal>
+    or <literal>pkgs.appendOverlays</literal>, although it is often preferable
+    to avoid these functions, because they recompute the Nixpkgs fixpoint,
+    which is somewhat expensive to do.
+   </para>
+  </section>
+
+  <section xml:id="sec-overlays-lookup">
+   <title>Install overlays via configuration lookup</title>
+
+   <para>
+    The list of overlays is determined as follows.
+   </para>
+
+   <para>
+    <orderedlist>
+     <listitem>
+      <para>
+       First, if an
+       <link xlink:href="#sec-overlays-argument"><varname>overlays</varname>
+       argument</link> to the nixpkgs function itself is given, then that is
+       used and no path lookup will be performed.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       Otherwise, if the Nix path entry
+       <literal>&lt;nixpkgs-overlays></literal> exists, we look for overlays at
+       that path, as described below.
+      </para>
+      <para>
+       See the section on <literal>NIX_PATH</literal> in the Nix manual for
+       more details on how to set a value for
+       <literal>&lt;nixpkgs-overlays>.</literal>
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       If one of <filename>~/.config/nixpkgs/overlays.nix</filename> and
+       <filename>~/.config/nixpkgs/overlays/</filename> exists, then we look
+       for overlays at that path, as described below. It is an error if both
+       exist.
+      </para>
+     </listitem>
+    </orderedlist>
+   </para>
+
+   <para>
+    If we are looking for overlays at a path, then there are two cases:
+    <itemizedlist>
+     <listitem>
+      <para>
+       If the path is a file, then the file is imported as a Nix expression and
+       used as the list of overlays.
+      </para>
+     </listitem>
+     <listitem>
+      <para>
+       If the path is a directory, then we take the content of the directory,
+       order it lexicographically, and attempt to interpret each as an overlay
+       by:
+       <itemizedlist>
+        <listitem>
+         <para>
+          Importing the file, if it is a <literal>.nix</literal> file.
+         </para>
+        </listitem>
+        <listitem>
+         <para>
+          Importing a top-level <filename>default.nix</filename> file, if it is
+          a directory.
+         </para>
+        </listitem>
+       </itemizedlist>
+      </para>
+     </listitem>
+    </itemizedlist>
+   </para>
+
+   <para>
+    Because overlays that are set in NixOS configuration do not affect
+    non-NixOS operations such as <literal>nix-env</literal>, the
+    <filename>overlays.nix</filename> option provides a convenient way to use
+    the same overlays for a NixOS system configuration and user configuration:
+    the same file can be used as <filename>overlays.nix</filename> and imported
+    as the value of <literal>nixpkgs.overlays</literal>.
+   </para>
+
+<!-- TODO: Example of sharing overlays between NixOS configuration
+     and configuration lookup. Also reference the example
+     from the sec-overlays-argument paragraph about NixOS.
+ -->
+  </section>
  </section>
 <!--============================================================-->
  <section xml:id="sec-overlays-definition">