From e855c7e2c9a9a5cbe4406c1f9351181a9ebe6283 Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <eelco.dolstra@logicblox.com>
Date: Sat, 14 Apr 2012 18:38:52 +0200
Subject: nix-channel improvements

"nix-channel --add" now accepts a second argument: the channel name.
This allows channels to have a nicer name than (say) nixpkgs_unstable.
If no name is given, it defaults to the last component of the URL
(with "-unstable" or "-stable" removed).

Also, channels are now stored in a profile
(/nix/var/nix/profiles/per-user/$USER/channels).  One advantage of
this is that it allows rollbacks (e.g. if "nix-channel --update" gives
an undesirable update).
---
 doc/manual/nix-channel.xml | 48 +++++++++++++++++++++++++++++++---------------
 doc/manual/nix-store.xml   |  5 +++--
 2 files changed, 36 insertions(+), 17 deletions(-)

(limited to 'doc')

diff --git a/doc/manual/nix-channel.xml b/doc/manual/nix-channel.xml
index 024add8601e8..22d8900d8f1c 100644
--- a/doc/manual/nix-channel.xml
+++ b/doc/manual/nix-channel.xml
@@ -19,7 +19,7 @@
   <cmdsynopsis>
     <command>nix-channel</command>
     <group choice='req'>
-      <arg choice='plain'><option>--add</option> <replaceable>url</replaceable></arg>
+      <arg choice='plain'><option>--add</option> <replaceable>url</replaceable> <arg choice='opt'><replaceable>name</replaceable></arg></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>
@@ -31,32 +31,39 @@
 
 <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>
+just a URL that points to a place containing a set of Nix expressions
+and a <command>nix-push</command> manifest.  <phrase
+condition="manual">See also <xref linkend="sec-channels"
+/>.</phrase></para>
 
 <para>This command has the following operations:
 
 <variablelist>
 
-  <varlistentry><term><option>--add</option> <replaceable>url</replaceable></term>
+  <varlistentry><term><option>--add</option> <replaceable>url</replaceable> [<replaceable>name</replaceable>]</term>
 
-    <listitem><para>Adds <replaceable>url</replaceable> to the list of
-    subscribed channels.</para></listitem>
+    <listitem><para>Adds a channel named
+    <replaceable>name</replaceable> with URL
+    <replaceable>url</replaceable> to the list of subscribed channels.
+    If <replaceable>name</replaceable> is omitted, it defaults to the
+    last component of <replaceable>url</replaceable>, with the
+    suffixes <literal>-stable</literal> or
+    <literal>-unstable</literal> removed.</para></listitem>
 
   </varlistentry>
 
-  <varlistentry><term><option>--remove</option> <replaceable>url</replaceable></term>
+  <varlistentry><term><option>--remove</option> <replaceable>name</replaceable></term>
 
-    <listitem><para>Removes <replaceable>url</replaceable> from the
-    list of subscribed channels.</para></listitem>
+    <listitem><para>Removes the channel named
+    <replaceable>name</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>
+    <listitem><para>Prints the names and URLs of all subscribed
+    channels on standard output.</para></listitem>
 
   </varlistentry>
 
@@ -64,7 +71,7 @@ also <xref linkend="sec-channels" />.</para>
 
     <listitem><para>Downloads the Nix expressions of all subscribed
     channels, makes them the default for <command>nix-env</command>
-    operations (by symlinking them in the directory
+    operations (by symlinking them from the directory
     <filename>~/.nix-defexpr</filename>), and performs a
     <command>nix-pull</command> on the manifests of all channels to
     make pre-built binaries available.</para></listitem>
@@ -75,8 +82,8 @@ also <xref linkend="sec-channels" />.</para>
 
 </para>
 
-<para>Note that <option>--add</option> and <option>--remove</option>
-do not automatically perform an update.</para>
+<para>Note that <option>--add</option> does not automatically perform
+an update.</para>
 
 <para>The list of subscribed channels is stored in
 <filename>~/.nix-channels</filename>.</para>
@@ -90,4 +97,15 @@ respectively.</para>
 
 </refsection>
 
+<refsection><title>Examples</title>
+
+<para>To subscribe to the Nixpkgs channel and install the GNU Hello package:</para>
+
+<screen>
+$ nix-channel --add http://nixos.org/releases/nixpkgs/channels/nixpkgs-unstable
+$ nix-channel --update
+$ nix-env -iA nixpkgs.hello</screen>
+
+</refsection>
+
 </refentry>
diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml
index 6a4ca3f717ff..6cc765bf27ca 100644
--- a/doc/manual/nix-store.xml
+++ b/doc/manual/nix-store.xml
@@ -58,8 +58,9 @@ options.</phrase></para>
 
     <listitem><para>Causes the result of a realisation
     (<option>--realise</option> and <option>--force-realise</option>)
-    to be registered as a root of the garbage collector (see <xref
-    linkend="ssec-gc-roots" />).  The root is stored in
+    to be registered as a root of the garbage collector<phrase
+    condition="manual"> (see <xref linkend="ssec-gc-roots"
+    />)</phrase>.  The root is stored in
     <replaceable>path</replaceable>, which must be inside a directory
     that is scanned for roots by the garbage collector (i.e.,
     typically in a subdirectory of
-- 
cgit 1.4.1