From e2eed05224ed9bbc64014db9158bbc42bd3d9bef Mon Sep 17 00:00:00 2001
From: Eelco Dolstra <e.dolstra@tudelft.nl>
Date: Thu, 28 Sep 2006 09:10:53 +0000
Subject: [PATCH] * Manual updates. * Documented nix-{pack,unpack}-closure.

---
 doc/manual/Makefile.am            |  3 +-
 doc/manual/introduction.xml       |  5 ---
 doc/manual/manual.xml             |  8 ++++
 doc/manual/nix-pack-closure.xml   | 64 +++++++++++++++++++++++++++++++
 doc/manual/nix-unpack-closure.xml | 28 ++++++++++++++
 doc/manual/quick-start.xml        | 13 ++++---
 6 files changed, 110 insertions(+), 11 deletions(-)
 create mode 100644 doc/manual/nix-pack-closure.xml
 create mode 100644 doc/manual/nix-unpack-closure.xml

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index e06fbf5cd..23c663fba 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -8,7 +8,8 @@ XSLTPROC = $(xsltproc) $(xmlflags) \
 
 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-channel.1
+ nix-prefetch-url.1 nix-channel.1 \
+ nix-pack-closure.1 nix-unpack-closure.1
 
 FIGURES = figures/user-environments.png
 
diff --git a/doc/manual/introduction.xml b/doc/manual/introduction.xml
index 644e62e3c..8080c80d7 100644
--- a/doc/manual/introduction.xml
+++ b/doc/manual/introduction.xml
@@ -3,11 +3,6 @@
 
 <title>Introduction</title>
 
-<!--
-<epigraph><para><quote>The number of Nix installations in the world
-has grown to 5, with more expected.</quote></para></epigraph>
--->
-
 <para>Nix is a system for the deployment of software.  Software
 deployment is concerned with the creation, distribution, and
 management of software components (<quote>packages</quote>).  Its main
diff --git a/doc/manual/manual.xml b/doc/manual/manual.xml
index 5ca7f491f..ea85a7da5 100644
--- a/doc/manual/manual.xml
+++ b/doc/manual/manual.xml
@@ -74,6 +74,14 @@
       <title>nix-prefetch-url</title>
       <xi:include href="nix-prefetch-url.xml" />
     </section>
+    <section>
+      <title>nix-pack-closure</title>
+      <xi:include href="nix-pack-closure.xml" />
+    </section>
+    <section>
+      <title>nix-unpack-closure</title>
+      <xi:include href="nix-unpack-closure.xml" />
+    </section>
   </appendix>
 
   <xi:include href="troubleshooting.xml" />
diff --git a/doc/manual/nix-pack-closure.xml b/doc/manual/nix-pack-closure.xml
new file mode 100644
index 000000000..20e39157c
--- /dev/null
+++ b/doc/manual/nix-pack-closure.xml
@@ -0,0 +1,64 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
+
+<refnamediv>
+  <refname>nix-pack-closure</refname>
+  <refpurpose>pack the closure of a store path into a single file that
+  can be unpacked with
+  <command>nix-unpack-closure</command></refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-pack-closure</command>
+    <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-pack-closure</command> packs the
+contents of the store paths <replaceable>paths</replaceable> and
+<emphasis>all their dependencies</emphasis> into a single file, which
+is written to standard output.  (That is, it
+<emphasis>serialises</emphasis> <replaceable>paths</replaceable>.)
+The output can then be unpacked into the Nix store of another machine
+using <command>nix-unpack-closure</command>.</para>
+
+<para>Together, <command>nix-pack-closure</command> and
+<command>nix-unpack-closure</command> provide a quick and easy way to
+deploy a package to a different machine.  However, as the output of
+<command>nix-pack-closure</command> tends to be rather large (since it
+contains all dependencies), it’s not very efficient.
+<command>nix-push</command> and <command>nix-pull</command> are more
+efficient, but are also a bit more cumbersome to use.</para>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<para>To copy some instance of Subversion with all its dependencies to
+another machine:
+
+<screen>
+$ nix-pack-closure /nix/store/hj232g1r...-subversion-1.3.0 > svn.closure
+
+<lineannotation>Copy <!-- !!! <filename> --> svn.closure to the remote machine, then on the remote machine do:</lineannotation>
+$ nix-unpack-closure &lt; svn.closure</screen>
+
+</para>
+
+<para>Copy the program <command>azureus</command> with all its
+dependencies to the machine <literal>scratchy</literal>:
+
+<screen>
+$ nix-pack-closure $(which azureus) | ssh scratchy nix-unpack-closure</screen>
+    
+</para>
+
+</refsection>
+
+
+</refentry>
diff --git a/doc/manual/nix-unpack-closure.xml b/doc/manual/nix-unpack-closure.xml
new file mode 100644
index 000000000..7c6d12d08
--- /dev/null
+++ b/doc/manual/nix-unpack-closure.xml
@@ -0,0 +1,28 @@
+<refentry xmlns="http://docbook.org/ns/docbook"
+          xmlns:xlink="http://www.w3.org/1999/xlink">
+
+<refnamediv>
+  <refname>nix-unpack-closure</refname>
+  <refpurpose>unpack the closure of a store path created by <command>nix-pack-closure</command> into the Nix store</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+  <cmdsynopsis>
+    <command>nix-unpack-closure</command>
+  </cmdsynopsis>
+</refsynopsisdiv>
+
+
+<refsection><title>Description</title>
+
+<para>The command <command>nix-unpack-closure</command> unpacks the
+closure of a set of store paths created by
+<command>nix-pack-closure</command> into the local Nix store.  The
+closure is a single file read from standard input.  See the
+description of <command>nix-pack-closure</command> for details and
+examples.</para>
+
+</refsection>
+
+
+</refentry>
diff --git a/doc/manual/quick-start.xml b/doc/manual/quick-start.xml
index f520522db..a89ac9336 100644
--- a/doc/manual/quick-start.xml
+++ b/doc/manual/quick-start.xml
@@ -31,7 +31,8 @@ file).</para></listitem>
 <listitem><para>Subscribe to the Nix Packages channel.
 
 <screen>
-$ nix-channel --add http://nix.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable</screen>
+$ nix-channel --add \
+    http://nix.cs.uu.nl/dist/nix/channels-v3/nixpkgs-unstable</screen>
 
 </para></listitem>
 
@@ -49,7 +50,7 @@ available remotely.</para></listitem>
 available in the channel:
 
 <screen>
-$ nix-env -qa
+$ nix-env -qa ’*’ <lineannotation>(mind the quotes!)</lineannotation>
 docbook-xml-4.2
 firefox-1.0pre-PR-0.10.1
 hello-2.1.1
@@ -109,13 +110,15 @@ to get rid of unused packages, since uninstalls or upgrades don't
 actually delete them:
 
 <screen>
-$ nix-env --delete-generations old
-$ nix-store --gc</screen>
+$ nix-collect-garbage -d</screen>
 
+<!--
 The first command deletes old “generations” of your profile (making
 rollbacks impossible, but also making the components in those old
 generations available for garbage collection), while the second
-command actually deletes them.</para></listitem>
+command actually deletes them.-->
+
+</para></listitem>
 
 </orderedlist>