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
-   functions that allow you to fetch fixed-output derivations in
+   and other files from the internet. Nixpkgs comes with a few helper
+   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,
-        <literal>sha256</literal>. Again, other hash algorithms are
-        also available but <literal>sha256</literal> is currently
+        tag (e.g <literal>v1.0</literal>) that will be downloaded from
+        Git. Finally, <literal>sha256</literal> corresponds to the
+        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
-   building derivations. The most important one,
+   Nixpkgs provides a couple of functions that help with building
+   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
-       refer to the derivation. <literal>env</literal> is an attribute
-       set specifying environment variables that will be set for this
-       derivation. <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>
+       <literal>name</literal> is just the name that Nix will append
+       to the store path in the same way that
+       <literal>stdenv.mkDerivation</literal> uses its
+       <literal>name</literal> attribute. <literal>env</literal> is an
+       attribute set specifying environment variables that will be set
+       for this derivation. These attributes are then passed to the
+       wrapped <literal>stdenv.mkDerivation</literal>.
+       <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
-       useful for creating scripts from Nix expressions. This takes an
-       attribute set and expects two arguments,
-       <literal>name</literal> and <literal>text</literal>.
-       <literal>name</literal> corresponds to the name used in the Nix
-       store path. <literal>text</literal> will be the contents of the
-       file. You can also set <literal>executable</literal> to true to
-       make this file have the executable bit set.
-    </para>
+       These functions write <literal>text</literal> to the Nix store.
+       This is useful for creating scripts from Nix expressions.
+       <literal>writeTextFile</literal> takes an attribute set and
+       expects two arguments, <literal>name</literal> and
+       <literal>text</literal>. <literal>name</literal> corresponds to
+       the name used in the Nix store path. <literal>text</literal>
+       will be the contents of the file. You can also set
+       <literal>executable</literal> to true to make this file have
+       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>