3 files changed, 28 insertions, 12 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index 33cb27e054bd..42da3c8b0c09 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -21,6 +21,8 @@ man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \
  nix-prefetch-url.1 nix-channel.1 \
  nix-install-package.1 nix-hash.1 nix-copy-closure.1
 
+man5_MANS = nix.conf.5
+
 man8_MANS = nix-worker.8
 
 FIGURES = figures/user-environments.png
diff --git a/doc/manual/conf-file.xml b/doc/manual/conf-file.xml
index 25a009de9d45..7fd104eb4ac8 100644
--- a/doc/manual/conf-file.xml
+++ b/doc/manual/conf-file.xml
@@ -1,27 +1,36 @@
-<section xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xml:id="sec-conf-file">
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink"
+          xmlns:xi="http://www.w3.org/2001/XInclude"
+          xml:id="sec-conf-file">
 
-<title>Nix configuration file</title>
+<refmeta>
+  <refentrytitle>nix.conf</refentrytitle>
+  <manvolnum>5</manvolnum>
+  <refmiscinfo class="source">Nix</refmiscinfo>
+  <refmiscinfo class="version"><xi:include href="version.txt" parse="text"/></refmiscinfo>
+</refmeta>
 
+<refnamediv>
+  <refname>nix.conf</refname>
+  <refpurpose>Nix configuration file</refpurpose>
+</refnamediv>
+
+<refsection><title>Description</title>
 
 <para>A number of persistent settings of Nix are stored in the file
 <filename><replaceable>sysconfdir</replaceable>/nix/nix.conf</filename>.
 This file is a list of <literal><replaceable>name</replaceable> =
 <replaceable>value</replaceable></literal> pairs, one per line.
-Comments start with a <literal>#</literal> character.  An example
-configuration file is shown in <xref linkend="ex-nix-conf" />.</para>
-
-<example xml:id='ex-nix-conf'><title>Nix configuration file</title>
+Comments start with a <literal>#</literal> character.  Here is an example
+configuration file:</para>
 
 <programlisting>
 gc-keep-outputs = true       # Nice for developers
 gc-keep-derivations = true   # Idem
 env-keep-derivations = false
 </programlisting>
-</example>
 
-<para>The following variables are currently available: 
+<para>The following settings are currently available: 
 
 <variablelist>
 
@@ -323,5 +332,6 @@ build-use-chroot = /dev /proc /bin</programlisting>
 
 </para>
 
+</refsection>
 
-</section>
+</refentry>
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index 95fbe7d90414..ccff9423cf17 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -40,7 +40,6 @@
     <title>Command Reference</title>
     <xi:include href="opt-common.xml" />
     <xi:include href="env-common.xml" />
-    <xi:include href="conf-file.xml" />
     
     <section>
       <title>Main commands</title>
@@ -63,6 +62,11 @@
       <xi:include href="nix-worker.xml" />
     </section>
 
+    <section>
+      <title>Files</title>
+      <xi:include href="conf-file.xml" />
+    </section>
+    
   </appendix>
 
   <xi:include href="troubleshooting.xml" />