Update overlay documentation by following nits from aneeshusa.

1 files changed, 40 insertions, 40 deletions

diff --git a/doc/overlays.xml b/doc/overlays.xml
index 4ad2764f33f9..c921289fd6c3 100644
--- a/doc/overlays.xml
+++ b/doc/overlays.xml
@@ -4,56 +4,53 @@
 
 <title>Overlays</title>
 
-<para>This chapter describes how to extend and change Nixpkgs content using
-overlays.  Overlays are used to add layers in the fix-point used by Nixpkgs
-to bind the dependencies of all packages.</para>
+<para>This chapter describes how to extend and change Nixpkgs packages using
+overlays. Overlays are used to add layers in the fix-point used by Nixpkgs
+to compose the set of all packages.</para>
 
 <!--============================================================-->
 
 <section xml:id="sec-overlays-install">
 <title>Installing Overlays</title>
 
-<para>The set of overlays are looked for in the following order, only the
+<para>The set of overlays is looked for in the following places. The
 first one present is considered, and all the rest are ignored:
 
 <orderedlist>
 
   <listitem>
 
-    <para>As argument of the imported attribute set. When importing Nixpkgs,
+    <para>As an argument of the imported attribute set. When importing Nixpkgs,
     the <varname>overlays</varname> attribute argument can be set to a list of
-    functions, which would be describe in <xref linkend="sec-overlays-layout"/>.</para>
+    functions, which is described in <xref linkend="sec-overlays-layout"/>.</para>
 
   </listitem>
 
   <listitem>
 
-    <para>As a directory pointed by the environment variable named
-<varname>NIXPKGS_OVERLAYS</varname>. This directory can contain symbolic
-links to Nix expressions.
-
+    <para>In the directory pointed by the environment variable
+<varname>NIXPKGS_OVERLAYS</varname>.
   </listitem>
 
   <listitem>
 
-    <para>As the directory located at
-<filename>~/.nixpkgs/overlays/</filename>. This directory can contain
-symbolic links to Nix expressions.
-
+    <para>In the directory <filename>~/.nixpkgs/overlays/</filename>.
   </listitem>
 
 </orderedlist>
 </para>
 
-<para>For the second and third option, the directory contains either
-directories providing a default.nix expression, or files, or symbolic links
-to the entry Nix expression of the overlay.  These Nix expressions are
-following the syntax described in <xref
-linkend="sec-overlays-layout"/>.</para>
+<para>For the second and third option, the directory should contain Nix expressions defining the
+overlays. Each overlay can be a file, a directory containing a
+<filename>default.nix</filename>, or a symlink to one of those. The expressions should follow
+the syntax described in <xref linkend="sec-overlays-layout"/>.</para>
 
-<para>To install an overlay, using the last option.  Clone the repository of
-the overlay, and add a symbolic link to it in the
-<filename>~/.nixpkgs/overlays/</filename> directory.</para>
+<para>The order of the overlay layers can influence the recipe of packages if multiple layers override
+the same recipe. In the case where overlays are loaded from a directory, these are loaded in
+alphabetical order.</para>
+
+<para>To install an overlay using the last option, you can clone the overlay's repository and add
+a symbolic link to in the <filename>~/.nixpkgs/overlays/</filename> directory.</para>
 
 </section>
 
@@ -62,37 +59,40 @@ the overlay, and add a symbolic link to it in the
 <section xml:id="sec-overlays-layout">
 <title>Overlays Layout</title>
 
-<para>An overlay is a Nix expression, which is a function which accepts 2
-arguments.</para>
+<para>Overlays are expressed as Nix functions which accept 2 arguments and return a set of
+packages</para>
 
 <programlisting>
 self: super:
 
 {
-  foo = super.foo.override { ... };
-  bar = import ./pkgs/bar {
-    inherit (self) stdenv fetchurl;
-    inherit (self) ninja crawl dwarf-fortress;
+  boost = super.boost.override {
+    python = self.python3;
+  };
+  rr = super.callPackage ./pkgs/rr {
+    stdenv = self.stdenv_32bit;
   };
 }
 </programlisting>
 
-<para>The first argument, usualy named <varname>self</varname>, corresponds
-to the final package set. You should use this set to inherit all the
-dependencies needed by your package expression.</para>
+<para>The first argument, usually named <varname>self</varname>, corresponds to the final package
+set. You should use this set for the dependencies of all packages specified in your
+overlay. For example, all the dependencies of <varname>rr</varname> in the example above come
+from <varname>self</varname>, as well as the overriden dependencies used in the
+<varname>boost</varname> override.</para>
 
-<para>The second argument, usualy named <varname>super</varname>,
+<para>The second argument, usually named <varname>super</varname>,
 corresponds to the result of the evaluation of the previous stages of
-Nixpkgs, it does not contain any of the packages added by the current
-overlay nor any of the following overlays.  This set is used in to override
-existing packages, either by changing their dependencies or their
-recipes.</para>
+Nixpkgs. It does not contain any of the packages added by the current
+overlay nor any of the following overlays. This set should be used either
+to refer to packages you wish to override, or to access functions defined
+in Nixpkgs. For example, the original recipe of <varname>boost</varname>
+in the above example, comes from <varname>super</varname>, as well as the
+<varname>callPackage</varname> function.</para>
 
 <para>The value returned by this function should be a set similar to
-<filename>pkgs/top-level/all-packages.nix</filename>, which contains either
-extra packages defined by the overlay, or which overwrite Nixpkgs packages
-with other custom defaults. This is similar to <xref
-linkend="sec-modify-via-packageOverrides"/>.</para>
+<filename>pkgs/top-level/all-packages.nix</filename>, which contains
+overridden and/or new packages.</para>
 
 </section>