From 9b7654f6ff326a7e35b48ce3c54d7f8bb71d9a13 Mon Sep 17 00:00:00 2001
From: Robert Hensing <robert@roberthensing.nl>
Date: Mon, 15 Oct 2018 13:47:36 +0200
Subject: [PATCH] nixpkgs docs: Point to pkgs.extend, pkgs.appendOverlays and
 improve override section

---
 doc/functions/overrides.xml | 15 +++++++++++++--
 doc/overlays.xml            |  8 +++++++-
 2 files changed, 20 insertions(+), 3 deletions(-)

diff --git a/doc/functions/overrides.xml b/doc/functions/overrides.xml
index 99e2a63631a7..30cc6f3f6b1d 100644
--- a/doc/functions/overrides.xml
+++ b/doc/functions/overrides.xml
@@ -6,8 +6,16 @@
 
  <para>
   Sometimes one wants to override parts of <literal>nixpkgs</literal>, e.g.
-  derivation attributes, the results of derivations or even the whole package
-  set.
+  derivation attributes, the results of derivations.
+ </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.
  </para>
 
  <section xml:id="sec-pkg-override">
@@ -25,6 +33,9 @@
   <para>
    Example usages:
 <programlisting>pkgs.foo.override { arg1 = val1; arg2 = val2; ... }</programlisting>
+<!-- TODO: move below programlisting to a new section about extending and overlays
+           and reference it
+  -->
 <programlisting>
 import pkgs.path { overlays = [ (self: super: {
   foo = super.foo.override { barSupport = true ; };
diff --git a/doc/overlays.xml b/doc/overlays.xml
index 2decf9febe80..af1ab26b5e97 100644
--- a/doc/overlays.xml
+++ b/doc/overlays.xml
@@ -30,10 +30,16 @@
       itself is given, then that is used.
      </para>
      <para>
-      This can be passed explicitly when importing nipxkgs, for example
+      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>