nixpkgs/manual: address review comments

Mostly taken from requested changes exactly as recommended.

doc/functions/fetchers.xml

@@ -6,8 +6,8 @@
 
  <para>
    When using Nix, you will frequently need to download source code
-   and other file from the internet. Nixpkgs comes with a few helper
+   and other files from the internet. Nixpkgs comes with a few helper
-   functions that allow you to fetch fixed-output derivations in
+   functions that allow you to fetch fixed-output derivations in a
    structured way.
  </para>
 
@@ -48,7 +48,11 @@ stdenv.mkDerivation {
 
  <para>
    <function>fetchpatch</function> works very similarly to
-   <function>fetchurl</function> with the same arguments expected.
+   <function>fetchurl</function> with the same arguments expected. It
+   expects patch files as a source and and performs normalization on
+   them before computing the checksum. For example it will remove
+   comments or other unstable parts that are sometimes added by
+   version control systems and can change over time.
  </para>
 
  <para>
@@ -80,6 +84,9 @@ stdenv.mkDerivation {
       <para>
        Used with Git. Expects <literal>url</literal> to a Git repo,
        <literal>rev</literal>, and <literal>sha256</literal>.
+       <literal>rev</literal> in this case can be full the git commit
+       id (SHA1 hash) or a tag name like
+       <literal>refs/tags/v1.0</literal>.
       </para>
      </listitem>
    </varlistentry>
@@ -141,9 +148,10 @@ stdenv.mkDerivation {
         GitHub HTML page as
         <literal>owner</literal>/<literal>repo</literal>.
         <literal>rev</literal> corresponds to the Git commit hash or
-        tag that will be downloaded from Git. Finally,
+        tag (e.g <literal>v1.0</literal>) that will be downloaded from
-        <literal>sha256</literal>. Again, other hash algorithms are
+        Git. Finally, <literal>sha256</literal> corresponds to the
-        also available but <literal>sha256</literal> is currently
+        hash of the extracted directory. Again, other hash algorithms
+        are also available but <literal>sha256</literal> is currently
         preferred.
       </para>
      </listitem>

doc/functions/trivial-builders.xml

@@ -5,10 +5,10 @@
  <title>Trivial builders</title>
 
  <para>
-   There are a couple of functions provide in Nixpkgs that help with
+   Nixpkgs provides a couple of functions that help with building
-   building derivations. The most important one,
+   derivations. The most important one,
    <function>stdenv.mkDerivation</function>, has already been
-   documented above. These wrap
+   documented above. The following functions wrap
    <function>stdenv.mkDerivation</function>, making it easier to use
    in certain cases.
  </para>
@@ -22,14 +22,42 @@
      <para>
        This takes three arguments, <literal>name</literal>,
        <literal>env</literal>, and <literal>buildCommand</literal>.
-       <literal>name</literal> is just the name that Nix will use to
+       <literal>name</literal> is just the name that Nix will append
-       refer to the derivation. <literal>env</literal> is an attribute
+       to the store path in the same way that
-       set specifying environment variables that will be set for this
+       <literal>stdenv.mkDerivation</literal> uses its
-       derivation. <literal>buildCommand</literal> specifies the
+       <literal>name</literal> attribute. <literal>env</literal> is an
-       commands that will be run to create this derivation. Note that
+       attribute set specifying environment variables that will be set
-       you will need to create <literal>$out</literal> for Nix to
+       for this derivation. These attributes are then passed to the
-       register the command as successful.
+       wrapped <literal>stdenv.mkDerivation</literal>.
-    </para>
+       <literal>buildCommand</literal> specifies the commands that
+       will be run to create this derivation. Note that you will need
+       to create <literal>$out</literal> for Nix to register the
+       command as successful.
+     </para>
+     <para>
+       An example of using <literal>runCommand</literal> is provided
+       below.
+     </para>
+     <programlisting>
+       (import &lt;nixpkgs&gt; {}).runCommand "my-example" {} ''
+         echo My example command is running
+
+         mkdir $out
+
+         echo I can write data to the Nix store > $out/message
+
+         echo I can also run basic commands like:
+
+         echo ls
+         ls
+
+         echo whoami
+         whoami
+
+         echo date
+         date
+       ''
+     </programlisting>
    </listitem>
   </varlistentry>
   <varlistentry>
@@ -47,19 +75,30 @@
   </varlistentry>
   <varlistentry>
    <term>
-    <literal>writeTextFile</literal>
+    <literal>writeTextFile</literal>, <literal>writeText</literal>,
+    <literal>writeTextDir</literal>, <literal>writeScript</literal>,
+    <literal>writeScriptBin</literal>
    </term>
    <listitem>
      <para>
-       This writes <literal>text</literal> to the Nix store. This is
+       These functions write <literal>text</literal> to the Nix store.
-       useful for creating scripts from Nix expressions. This takes an
+       This is useful for creating scripts from Nix expressions.
-       attribute set and expects two arguments,
+       <literal>writeTextFile</literal> takes an attribute set and
-       <literal>name</literal> and <literal>text</literal>.
+       expects two arguments, <literal>name</literal> and
-       <literal>name</literal> corresponds to the name used in the Nix
+       <literal>text</literal>. <literal>name</literal> corresponds to
-       store path. <literal>text</literal> will be the contents of the
+       the name used in the Nix store path. <literal>text</literal>
-       file. You can also set <literal>executable</literal> to true to
+       will be the contents of the file. You can also set
-       make this file have the executable bit set.
+       <literal>executable</literal> to true to make this file have
-    </para>
+       the executable bit set.
+     </para>
+     <para>
+       Many more commands wrap <literal>writeTextFile</literal>
+       including <literal>writeText</literal>,
+       <literal>writeTextDir</literal>,
+       <literal>writeScript</literal>, and
+       <literal>writeScriptBin</literal>. These are convenience
+       functions over <literal>writeTextFile</literal>.
+     </para>
    </listitem>
   </varlistentry>
   <varlistentry>
@@ -75,7 +114,7 @@
      <literal>name</literal> is the name used in the Nix store path
      for the created derivation. <literal>paths</literal> is a list of
      paths that will be symlinked. These paths can be to Nix store
-     derivations or any other directory.
+     derivations or any other subdirectory contained within.
     </para>
    </listitem>
   </varlistentry>

doc/stdenv.xml

@@ -2207,7 +2207,8 @@ addEnvHooks "$hostOffset" myBashFunction
        This setup hook moves any installed documentation to the
        <literal>/share</literal> subdirectory directory. This includes
        the man, doc and info directories. This is needed for legacy
-       programs that do not know use the share subdirectory.
+       programs that do not know how to use the
+       <literal>share</literal> subdirectory.
        </para>
      </listitem>
     </varlistentry>
@@ -2219,7 +2220,7 @@ addEnvHooks "$hostOffset" myBashFunction
        <para>
        This setup hook compresses any man pages that have been
        installed. The compression is done using the gzip program. This
-       helps to reduce installed size of packages.
+       helps to reduce the installed size of packages.
        </para>
      </listitem>
     </varlistentry>
@@ -2230,9 +2231,9 @@ addEnvHooks "$hostOffset" myBashFunction
      <listitem>
        <para>
        This runs the strip command on installed binaries and
-       libraries. This removed things like debug symbols when they are
+       libraries. This removes unnecessary information like debug
-       not needed. This also helps to reduce installed size of
+       symbols when they are not needed. This also helps to reduce the
-       packages.
+       installed size of packages.
        </para>
      </listitem>
     </varlistentry>
@@ -2244,10 +2245,11 @@ addEnvHooks "$hostOffset" myBashFunction
        <para>
        This setup hook patches installed scripts to use the full path
        to the shebang interpreter. A shebang interpreter is the first
-       commented line of a script telling the operating system
+       commented line of a script telling the operating system which
-       what to use to run this script. In Nix, we want an exact path
+       program will run the script (e.g <literal>#!/bin/bash</literal>). In
-       to that interpreter to be used. This often replcaes
+       Nix, we want an exact path to that interpreter to be used. This
-       <literal>/bin/sh</literal> with a path in the Nix store.
+       often replaces <literal>/bin/sh</literal> with a path in the
+       Nix store.
        </para>
      </listitem>
     </varlistentry>
@@ -2260,7 +2262,7 @@ addEnvHooks "$hostOffset" myBashFunction
        This verifies that no references are left from the install
        binaries to the directory used to build those binaries. This
        ensures that the binaries do not need things outside the Nix
-       store. This currently Linux only.
+       store. This is currently supported in Linux only.
        </para>
      </listitem>
     </varlistentry>
@@ -2425,9 +2427,9 @@ addEnvHooks "$hostOffset" myBashFunction
 
   <para>
    Here are some more packages that provide a setup hook. Since the
-   mechanism is modular, this probably isn't an exhaustive list. Then
+   list of hooks is extensible, this is not an exhaustive list the
-   again, since the mechanism is only to be used as a last resort, it
+   mechanism is only to be used as a last resort, it might cover most
-   might be.
+   uses.
    <variablelist>
     <varlistentry>
      <term>