Get rid of <example>

Markdown doesn't have floats so we can't have this.

6 files changed, 157 insertions, 135 deletions

diff --git a/doc/manual/expressions/builtins.xml b/doc/manual/expressions/builtins.xml
index 478b67ce8..877fd3a1b 100644
--- a/doc/manual/expressions/builtins.xml
+++ b/doc/manual/expressions/builtins.xml
@@ -434,88 +434,93 @@ stdenv.mkDerivation { … }
         </varlistentry>
       </variablelist>
 
-      <example>
-        <title>Fetching a private repository over SSH</title>
-        <programlisting>builtins.fetchGit {
+      <para>Here are some examples of how to use
+      <literal>fetchGit</literal>.</para>
+
+      <itemizedlist>
+
+        <listitem>
+          <para>To fetch a private repository over SSH:</para>
+
+          <programlisting>builtins.fetchGit {
   url = "git@github.com:my-secret/repository.git";
   ref = "master";
   rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
 }</programlisting>
-      </example>
 
-      <example>
-        <title>Fetching an arbitrary ref</title>
-        <programlisting>builtins.fetchGit {
+        </listitem>
+
+        <listitem>
+          <para>To fetch an arbitrary reference:</para>
+
+          <programlisting>builtins.fetchGit {
   url = "https://github.com/NixOS/nix.git";
   ref = "refs/heads/0.5-release";
 }</programlisting>
-      </example>
-
-      <example>
-        <title>Fetching a repository's specific commit on an arbitrary branch</title>
-        <para>
-          If the revision you're looking for is in the default branch
-          of the git repository you don't strictly need to specify
-          the branch name in the <varname>ref</varname> attribute.
-        </para>
-        <para>
-          However, if the revision you're looking for is in a future
-          branch for the non-default branch you will need to specify
-          the the <varname>ref</varname> attribute as well.
-        </para>
-        <programlisting>builtins.fetchGit {
+        </listitem>
+
+        <listitem>
+          <para>
+            If the revision you're looking for is in the default branch
+            of the git repository you don't strictly need to specify
+            the branch name in the <varname>ref</varname> attribute.
+          </para>
+          <para>
+            However, if the revision you're looking for is in a future
+            branch for the non-default branch you will need to specify
+            the the <varname>ref</varname> attribute as well.
+          </para>
+
+          <programlisting>builtins.fetchGit {
   url = "https://github.com/nixos/nix.git";
   rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
   ref = "1.11-maintenance";
 }</programlisting>
-        <note>
+
+          <note>
+            <para>
+              It is nice to always specify the branch which a revision
+              belongs to. Without the branch being specified, the
+              fetcher might fail if the default branch changes.
+              Additionally, it can be confusing to try a commit from a
+              non-default branch and see the fetch fail. If the branch
+              is specified the fault is much more obvious.
+            </para>
+          </note>
+        </listitem>
+
+        <listitem>
           <para>
-            It is nice to always specify the branch which a revision
-            belongs to. Without the branch being specified, the
-            fetcher might fail if the default branch changes.
-            Additionally, it can be confusing to try a commit from a
-            non-default branch and see the fetch fail. If the branch
-            is specified the fault is much more obvious.
+            If the revision you're looking for is in the default branch
+            of the git repository you may omit the
+            <varname>ref</varname> attribute.
           </para>
-        </note>
-      </example>
-
-      <example>
-        <title>Fetching a repository's specific commit on the default branch</title>
-        <para>
-          If the revision you're looking for is in the default branch
-          of the git repository you may omit the
-          <varname>ref</varname> attribute.
-        </para>
-        <programlisting>builtins.fetchGit {
+          <programlisting>builtins.fetchGit {
   url = "https://github.com/nixos/nix.git";
   rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
 }</programlisting>
-      </example>
+        </listitem>
 
-      <example>
-        <title>Fetching a tag</title>
-        <programlisting>builtins.fetchGit {
+        <listitem>
+          <para>To fetch a specific tag:</para>
+          <programlisting>builtins.fetchGit {
   url = "https://github.com/nixos/nix.git";
   ref = "refs/tags/1.9";
 }</programlisting>
-      </example>
-
-      <example>
-        <title>Fetching the latest version of a remote branch</title>
-        <para>
-          <function>builtins.fetchGit</function> can behave impurely
-           fetch the latest version of a remote branch.
-        </para>
-        <note><para>Nix will refetch the branch in accordance to
-        <xref linkend="conf-tarball-ttl" />.</para></note>
-        <note><para>This behavior is disabled in
-        <emphasis>Pure evaluation mode</emphasis>.</para></note>
+        </listitem>
+
+        <listitem>
+          <para>To fetch the latest version of a remote branch:</para>
         <programlisting>builtins.fetchGit {
   url = "ssh://git@github.com/nixos/nix.git";
   ref = "master";
 }</programlisting>
-      </example>
+          <note><para>Nix will refetch the branch in accordance to
+          <xref linkend="conf-tarball-ttl" />.</para></note>
+          <note><para>This behavior is disabled in <emphasis>Pure
+          evaluation mode</emphasis>.</para></note>
+        </listitem>
+      </itemizedlist>
     </listitem>
   </varlistentry>
 
diff --git a/doc/manual/packages/copy-closure.xml b/doc/manual/packages/copy-closure.xml
index 012030e3e..a336fb293 100644
--- a/doc/manual/packages/copy-closure.xml
+++ b/doc/manual/packages/copy-closure.xml
@@ -4,7 +4,7 @@
          version="5.0"
          xml:id="ssec-copy-closure">
 
-<title>Copying Closures Via SSH</title>
+<title>Copying Closures via SSH</title>
 
 <para>The command <command
 linkend="sec-nix-copy-closure">nix-copy-closure</command> copies a Nix
diff --git a/doc/manual/packages/s3-substituter.xml b/doc/manual/packages/s3-substituter.xml
index 868b5a66d..aa5df2026 100644
--- a/doc/manual/packages/s3-substituter.xml
+++ b/doc/manual/packages/s3-substituter.xml
@@ -5,10 +5,10 @@
          version="5.0"
          xml:id="ssec-s3-substituter">
 
-<title>Serving a Nix store via AWS S3 or S3-compatible Service</title>
+<title>Serving a Nix store via S3</title>
 
 <para>Nix has built-in support for storing and fetching store paths
-from Amazon S3 and S3 compatible services. This uses the same
+from Amazon S3 and S3-compatible services. This uses the same
 <emphasis>binary</emphasis> cache mechanism that Nix usually uses to
 fetch prebuilt binaries from <uri>cache.nixos.org</uri>.</para>
 
@@ -170,13 +170,22 @@ the S3 URL:</para>
 }
 ]]></programlisting>
 
+</section>
+
+<section><title>Examples</title>
+
+<para>To upload with a specific credential profile for Amazon S3:</para>
 
-  <example><title>Uploading with a specific credential profile for Amazon S3</title>
-    <para><command>nix copy --to 's3://example-nix-cache?profile=cache-upload&amp;region=eu-west-2' nixpkgs.hello</command></para>
-  </example>
+<screen>
+nix copy --to 's3://example-nix-cache?profile=cache-upload&amp;region=eu-west-2' nixpkgs.hello
+</screen>
+
+<para>To upload to an S3-compatible binary cache:</para>
+
+<screen>
+nix copy --to 's3://example-nix-cache?profile=cache-upload&amp;scheme=https&amp;endpoint=minio.example.com' nixpkgs.hello
+</screen>
 
-  <example><title>Uploading to an S3-Compatible Binary Cache</title>
-    <para><command>nix copy --to 's3://example-nix-cache?profile=cache-upload&amp;scheme=https&amp;endpoint=minio.example.com' nixpkgs.hello</command></para>
-  </example>
 </section>
+
 </section>
diff --git a/doc/manual/src/expressions/builtins.md b/doc/manual/src/expressions/builtins.md
index f60af9d24..8faf4b939 100644
--- a/doc/manual/src/expressions/builtins.md
+++ b/doc/manual/src/expressions/builtins.md
@@ -169,70 +169,76 @@ For instance, `derivation` is also available as `builtins.derivation`.
         A Boolean parameter that specifies whether submodules should be
         checked out. Defaults to `false`.
     
-    <!-- end list -->
+    Here are some examples of how to use `fetchGit`.
     
-        builtins.fetchGit {
-          url = "git@github.com:my-secret/repository.git";
-          ref = "master";
-          rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
-        }
-    
-        builtins.fetchGit {
-          url = "https://github.com/NixOS/nix.git";
-          ref = "refs/heads/0.5-release";
-        }
-    
-    If the revision you're looking for is in the default branch of the
-    git repository you don't strictly need to specify the branch name in
-    the `ref` attribute.
-    
-    However, if the revision you're looking for is in a future branch
-    for the non-default branch you will need to specify the the `ref`
-    attribute as well.
-    
-        builtins.fetchGit {
-          url = "https://github.com/nixos/nix.git";
-          rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
-          ref = "1.11-maintenance";
-        }
-    
-    > **Note**
-    > 
-    > It is nice to always specify the branch which a revision belongs
-    > to. Without the branch being specified, the fetcher might fail if
-    > the default branch changes. Additionally, it can be confusing to
-    > try a commit from a non-default branch and see the fetch fail. If
-    > the branch is specified the fault is much more obvious.
-    
-    If the revision you're looking for is in the default branch of the
-    git repository you may omit the `ref` attribute.
-    
-        builtins.fetchGit {
-          url = "https://github.com/nixos/nix.git";
-          rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
-        }
-    
-        builtins.fetchGit {
-          url = "https://github.com/nixos/nix.git";
-          ref = "refs/tags/1.9";
-        }
-    
-    `builtins.fetchGit` can behave impurely fetch the latest version of
-    a remote branch.
+      - To fetch a private repository over SSH:
+        
+            builtins.fetchGit {
+              url = "git@github.com:my-secret/repository.git";
+              ref = "master";
+              rev = "adab8b916a45068c044658c4158d81878f9ed1c3";
+            }
     
-    > **Note**
-    > 
-    > Nix will refetch the branch in accordance to
-    > [???](#conf-tarball-ttl).
+      - To fetch an arbitrary reference:
+        
+            builtins.fetchGit {
+              url = "https://github.com/NixOS/nix.git";
+              ref = "refs/heads/0.5-release";
+            }
+    
+      - If the revision you're looking for is in the default branch of
+        the git repository you don't strictly need to specify the branch
+        name in the `ref` attribute.
+        
+        However, if the revision you're looking for is in a future
+        branch for the non-default branch you will need to specify the
+        the `ref` attribute as well.
+        
+            builtins.fetchGit {
+              url = "https://github.com/nixos/nix.git";
+              rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
+              ref = "1.11-maintenance";
+            }
+        
+        > **Note**
+        > 
+        > It is nice to always specify the branch which a revision
+        > belongs to. Without the branch being specified, the fetcher
+        > might fail if the default branch changes. Additionally, it can
+        > be confusing to try a commit from a non-default branch and see
+        > the fetch fail. If the branch is specified the fault is much
+        > more obvious.
+    
+      - If the revision you're looking for is in the default branch of
+        the git repository you may omit the `ref` attribute.
+        
+            builtins.fetchGit {
+              url = "https://github.com/nixos/nix.git";
+              rev = "841fcbd04755c7a2865c51c1e2d3b045976b7452";
+            }
     
-    > **Note**
-    > 
-    > This behavior is disabled in *Pure evaluation mode*.
+      - To fetch a specific tag:
+        
+            builtins.fetchGit {
+              url = "https://github.com/nixos/nix.git";
+              ref = "refs/tags/1.9";
+            }
     
-        builtins.fetchGit {
-          url = "ssh://git@github.com/nixos/nix.git";
-          ref = "master";
-        }
+      - To fetch the latest version of a remote branch:
+        
+            builtins.fetchGit {
+              url = "ssh://git@github.com/nixos/nix.git";
+              ref = "master";
+            }
+        
+        > **Note**
+        > 
+        > Nix will refetch the branch in accordance to
+        > [???](#conf-tarball-ttl).
+        
+        > **Note**
+        > 
+        > This behavior is disabled in *Pure evaluation mode*.
 
   - `builtins.filter` f xs  
     Return a list consisting of the elements of xs for which the
diff --git a/doc/manual/src/package-management/copy-closure.md b/doc/manual/src/package-management/copy-closure.md
index 6573862c0..d78b77e36 100644
--- a/doc/manual/src/package-management/copy-closure.md
+++ b/doc/manual/src/package-management/copy-closure.md
@@ -1,4 +1,4 @@
-# Copying Closures Via SSH
+# Copying Closures via SSH
 
 The command `nix-copy-closure` copies a Nix store path along with all
 its dependencies to or from another machine via the SSH protocol. It
diff --git a/doc/manual/src/package-management/s3-substituter.md b/doc/manual/src/package-management/s3-substituter.md
index 4740b8b1c..d96114e3c 100644
--- a/doc/manual/src/package-management/s3-substituter.md
+++ b/doc/manual/src/package-management/s3-substituter.md
@@ -1,7 +1,7 @@
-# Serving a Nix store via AWS S3 or S3-compatible Service
+# Serving a Nix store via S3
 
 Nix has built-in support for storing and fetching store paths from
-Amazon S3 and S3 compatible services. This uses the same *binary* cache
+Amazon S3 and S3-compatible services. This uses the same *binary* cache
 mechanism that Nix usually uses to fetch prebuilt binaries from
 [cache.nixos.org](cache.nixos.org).
 
@@ -124,10 +124,12 @@ Your account will need the following IAM policy to upload to the cache:
       ]
     }
 
-`nix copy --to
-'s3://example-nix-cache?profile=cache-upload&region=eu-west-2'
-nixpkgs.hello`
+## Examples
 
-`nix copy --to
-'s3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com'
-nixpkgs.hello`
+To upload with a specific credential profile for Amazon S3:
+
+    nix copy --to 's3://example-nix-cache?profile=cache-upload&region=eu-west-2' nixpkgs.hello
+
+To upload to an S3-compatible binary cache:
+
+    nix copy --to 's3://example-nix-cache?profile=cache-upload&scheme=https&endpoint=minio.example.com' nixpkgs.hello