7 files changed, 108 insertions, 17 deletions
diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index f5a93cf308c8..81367fd14173 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -5,12 +5,12 @@ XSLTPROC = $(ENV) $(xsltproc) $(xmlflags) --catalogs \
  --param section.autolabel 1 \
  --param section.label.includes.component.label 1 \
  --param html.stylesheet \'style.css\' \
- --param xref.with.number.and.title 0 \
+ --param xref.with.number.and.title 1 \
  --param toc.section.depth 3
 
 man1_MANS = nix-env.1 nix-build.1 nix-store.1 nix-instantiate.1 \
  nix-collect-garbage.1 nix-push.1 nix-pull.1 \
- nix-prefetch-url.1
+ nix-prefetch-url.1 nix-channel.1
 
 FIGURES = figures/user-environments.png
 
diff --git a/doc/manual/conf-file.xml b/doc/manual/conf-file.xml
index 13fac53356c9..629dd3bac788 100644
--- a/doc/manual/conf-file.xml
+++ b/doc/manual/conf-file.xml
@@ -7,7 +7,7 @@ This file is a list of <literal><replaceable>name</replaceable> =
 Comments start with a <literal>#</literal> character.  An example
 configuration file is shown in <xref linkend="ex-nix-conf" />.</para>
 
-<example id='ex-nix-conf'><title>Nix expression for GNU Hello</title>
+<example id='ex-nix-conf'><title>Nix configuration file</title>
 
 <programlisting>
 gc-keep-outputs = true       # Nice for developers
diff --git a/doc/manual/env-common.xml b/doc/manual/env-common.xml
index ec468eba1ad5..2d25d3b283da 100644
--- a/doc/manual/env-common.xml
+++ b/doc/manual/env-common.xml
@@ -246,11 +246,10 @@ $ mount -o bind /mnt/otherdisk/nix /nix</screen>
     <varlistentry><term><filename>references</filename></term>
 
       <listitem><para>The reference graph of the inputs, in the format
-      accepted by the command <link
-      linkend="rsec-nix-store-reg-val"><command>nix-store
-      --register-validity</command></link>.  It is necessary to run
-      this command on the remote machine after copying the inputs to
-      inform Nix on the remote machine that the inputs are valid
+      accepted by the command <command>nix-store
+      --register-validity</command>.  It is necessary to run this
+      command on the remote machine after copying the inputs to inform
+      Nix on the remote machine that the inputs are valid
       paths.</para></listitem>
 
     </varlistentry>
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index f1dd0430a14d..a9e4473e020a 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -56,6 +56,10 @@
       <title>nix-collect-garbage</title>
       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-collect-garbage.xml" />
     </sect1>
+    <sect1 id="sec-nix-channel">
+      <title>nix-channel</title>
+      <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-channel.xml" />
+    </sect1>
     <sect1>
       <title>nix-push</title>
       <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="nix-push.xml" />
diff --git a/doc/manual/nix-channel.xml b/doc/manual/nix-channel.xml
new file mode 100644
index 000000000000..059832a86c1d
--- /dev/null
+++ b/doc/manual/nix-channel.xml
@@ -0,0 +1,83 @@
+<refentry>
+  
+<refnamediv>
+  <refname>nix-channel</refname>
+  <refpurpose>manage Nix channels</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-channel</command>
+    <group choice='req'>
+      <arg choice='plain'><option>--add</option> <replaceable>url</replaceable></arg>
+      <arg choice='plain'><option>--remove</option> <replaceable>url</replaceable></arg>
+      <arg choice='plain'><option>--list</option></arg>
+      <arg choice='plain'><option>--update</option></arg>
+    </group>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+<refsection><title>Description</title>
+
+<para>A Nix channel is mechanism that allows you to automatically stay
+up-to-date with a set of pre-built Nix expressions.  A Nix channel is
+just a URL that points to a place that contains a set of Nix
+expressions, as well as a <command>nix-push</command> manifest.  See
+also <xref linkend="sec-channels" />.</para>
+
+<para>This command has the following operations:
+
+<variablelist>
+
+  <varlistentry><term><option>--add</option> <replaceable>url</replaceable></term>
+
+    <listitem><para>Adds <replaceable>url</replaceable> to the list of
+    subscribed channels.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--remove</option> <replaceable>url</replaceable></term>
+
+    <listitem><para>Removes <replaceable>url</replaceable> from the
+    list of subscribed channels.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--list</option></term>
+
+    <listitem><para>Prints the URLs of all subscribed channels on
+    standard output.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--update</option></term>
+
+    <listitem><para>Downloads the Nix expressions of all subscribed
+    channels, makes the conjunction of these the default for
+    <command>nix-env</command> operations (by calling <command>nix-env
+    -I</command>), and performs a <command>nix-pull</command> on the
+    manifests of all channels to make pre-built binaries
+    available.</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
+
+</para>
+
+<para>Note that <option>--add</option> and <option>--remove</option>
+do not automatically perform an update.</para>
+
+<para>The list of subscribed channels is stored in
+<filename>~/.nix-channels</filename>.</para>
+
+<para>A channel consists of two elements: a bzipped Tar archive
+containing the Nix expressions, and a manifest created by
+<command>nix-push</command>.  These must be stored under
+<literal><replaceable>url</replaceable>/nixexprs.tar.bz2</literal> and
+<literal><replaceable>url</replaceable>/MANIFEST</literal>,
+respectively.</para>
+
+</refsection>
+
+</refentry>
diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml
index 614d30b6aceb..eead48397262 100644
--- a/doc/manual/nix-store.xml
+++ b/doc/manual/nix-store.xml
@@ -571,13 +571,14 @@ $ gv graph.ps</screen>
 
 <!--######################################################################-->
 
-<refsection id="rsec-nix-store-reg-val"><title>Operation <option>--register-validity</option></title>
+<!--
+<refsection id="rsec-nix-store-reg-val"><title>Operation <option>-XXX-register-validity</option></title>
 
 <refsection><title>Synopsis</title>
 
 <cmdsynopsis>
   <command>nix-store</command>
-  <arg choice='plain'><option>--register-validity</option></arg>
+  <arg choice='plain'><option>-XXX-register-validity</option></arg>
 </cmdsynopsis>
 </refsection>
 
@@ -588,18 +589,20 @@ $ gv graph.ps</screen>
 </refsection>
             
 </refsection>
+-->
 
 
 
 <!--######################################################################-->
 
-<refsection><title>Operation <option>--substitute</option></title>
+<!--
+<refsection><title>Operation <option>-XXX-substitute</option></title>
 
 <refsection><title>Synopsis</title>
 
 <cmdsynopsis>
   <command>nix-store</command>
-  <arg choice='plain'><option>--substitute</option></arg>
+  <arg choice='plain'><option>-XXX-substitute</option></arg>
   <arg choice='plain'
        rep='repeat'><replaceable>srcpath</replaceable> <replaceable>subpath</replaceable></arg>
 </cmdsynopsis>
@@ -607,7 +610,7 @@ $ gv graph.ps</screen>
 
 <refsection><title>Description</title>
             
-<para>The operation <option>--substitute</option> registers that the
+<para>The operation <option>-XXX-substitute</option> registers that the
 store path <replaceable>srcpath</replaceable> can be built by
 realising the derivation expression in
 <replaceable>subpath</replaceable>.  This is used to implement binary
@@ -616,6 +619,7 @@ deployment.</para>
 </refsection>
             
 </refsection>
+-->
 
 
 
diff --git a/doc/manual/package-management.xml b/doc/manual/package-management.xml
index b827ae75b6c5..450353337e5a 100644
--- a/doc/manual/package-management.xml
+++ b/doc/manual/package-management.xml
@@ -408,7 +408,7 @@ followed to prevent infinite recursion.</para>
 </sect1>
 
 
-<sect1><title>Channels</title>
+<sect1 id="sec-channels"><title>Channels</title>
 
 <para>If you want to stay up to date with a set of packages, it’s not
 very convenient to manually download the latest set of Nix expressions
@@ -418,9 +418,10 @@ pre-built binaries (if available), and upgrade using
 <emphasis>Nix channels</emphasis>.</para>
 
 <para>A Nix channel is just a URL that points to a place that contains
-a set of Nix expressions and a manifest.  Using the command
-<command>nix-channel</command> you can automatically stay up to date
-with whatever is available at that URL.</para>
+a set of Nix expressions and a manifest.  Using the command <link
+linkend="sec-nix-channel"><command>nix-channel</command></link> you
+can automatically stay up to date with whatever is available at that
+URL.</para>
 
 <para>You can <quote>subscribe</quote> to a channel using
 <command>nix-channel --add</command>, e.g.,