* Some more updates.

doc/manual/nix-push.xml

@@ -1,4 +1,5 @@
 <refentry>
+
 <refnamediv>
   <refname>nix-push</refname>
   <refpurpose>push store paths onto a network cache</refpurpose>
@@ -7,111 +8,90 @@
 <refsynopsisdiv>
   <cmdsynopsis>
     <command>nix-push</command>
+    <group choice='req'>
+      <arg choice='req'>
         <arg choice='plain'><replaceable>archives-put-url</replaceable></arg>
         <arg choice='plain'><replaceable>archives-get-url</replaceable></arg>
         <arg choice='plain'><replaceable>manifest-put-url</replaceable></arg>
+      </arg>
+      <arg choice='req'>
+        <arg choice='plain'><option>--copy</option></arg>
+        <arg choice='plain'><replaceable>archives-dir</replaceable></arg>
+        <arg choice='plain'><replaceable>manifest-file</replaceable></arg>
+      </arg>
+    </group>
     <arg choice='plain' rep='repeat'><replaceable>paths</replaceable></arg>
   </cmdsynopsis>
 </refsynopsisdiv>
 
-  <refsection>
-    <title>Description</title>
 
-    <para>
+<refsection><title>Description</title>
-      The command <command>nix-push</command> builds a set of store
-      expressions (if necessary), and then packages and uploads all
-      store paths in the resulting closures to a server.  A network
-      cache thus populated can subsequently be used to speed up
-      software deployment on other machines using the
-      <command>nix-pull</command> command.
-    </para>
 
-    <para>
+<para>The command <command>nix-push</command> builds a set of store
-      <command>nix-push</command> performs the following actions.
+paths (if necessary), and then packages and uploads all store paths in
+the resulting closures to a server.  A network cache thus populated
+can subsequently be used to speed up software deployment on other
+machines using the <command>nix-pull</command> command.</para>
+
+<para><command>nix-push</command> performs the following actions.
       
 <orderedlist>
 
-        <listitem>
+  <listitem><para>Each path in <replaceable>paths</replaceable> is
-          <para>
+  realised (using <link
-            The store expressions stored in
+  linkend='rsec-nix-store-realise'><literal>nix-store
-            <replaceable>paths</replaceable> are realised (using
+  --realise</literal></link>).</para></listitem>
-            <literal>nix-store --realise</literal>).
-          </para>
-        </listitem>
 
-        <listitem>
+  <listitem><para>All paths in the closure of the store expressions
-          <para>
+  stored in <replaceable>paths</replaceable> are determined (using
-            All paths in the closure of the store expressions stored
-            in <replaceable>paths</replaceable> are determined (using
   <literal>nix-store --query --requisites
-            --include-successors</literal>).  It should be noted that
+  --include-outputs</literal>).  It should be noted that since the
-            since the <option>--include-successors</option> flag is
+  <option>--include-outputs</option> flag is used, you get a combined
-            used, if you specify a derivation store expression, you
+  source/binary distribution.</para></listitem>
-            get a combined source/binary distribution.  If you only
-            want a binary distribution, you should specify the closure
-            store expression that result from realising these (see
-            below).
-          </para>
-        </listitem>
 
-        <listitem>
+  <listitem><para>All store paths determined in the previous step are
-          <para>
+  packaged and compressed into a <command>bzip</command>ped NAR
-            All store paths determined in the previous step are
+  archive (extension <filename>.nar.bz2</filename>).</para></listitem>
-            packaged and compressed into a <command>bzip</command>ped
-            NAR archive (extension <filename>.nar.bz2</filename>).
-          </para>
-        </listitem>
 
-        <listitem>
+  <listitem><para>A <emphasis>manifest</emphasis> is created that
-          <para>
+  contains information on the store paths, their eventual URLs in the
-            A <emphasis>manifest</emphasis> is created that contains
-            information on the store paths, their eventual URLs in the
   cache, and cryptographic hashes of the contents of the NAR
-            archives.
+  archives.</para></listitem>
-          </para>
-        </listitem>
 
-        <listitem>
+  <listitem><para>Each store path is uploaded to the remote directory
-          <para>
+  specified by <replaceable>archives-put-url</replaceable>.  HTTP PUT
-            Each store path is uploaded to the remote directory
+  requests are used to do this.  However, before a file
-            specified by <replaceable>archives-put-url</replaceable>.
+  <varname>x</varname> is uploaded to
-            HTTP PUT requests are used to do this.  However, before a
-            file <varname>x</varname> is uploaded to
   <literal><replaceable>archives-put-url</replaceable>/<varname>x</varname></literal>,
-            <command>nix-push</command> first determines whether this
+  <command>nix-push</command> first determines whether this upload is
-            upload is unnecessary by issuing a HTTP HEAD request on
+  unnecessary by issuing a HTTP HEAD request on
   <literal><replaceable>archives-get-url</replaceable>/<varname>x</varname></literal>.
-            This allows a cache to be shared between many partially
+  This allows a cache to be shared between many partially overlapping
-            overlapping <command>nix-push</command> invocations.
+  <command>nix-push</command> invocations.  (We use two URLs because
-            (We use two URLs because the upload URL typically
+  the upload URL typically refers to a CGI script, while the download
-            refers to a CGI script, while the download URL just refers
+  URL just refers to a file system directory on the server.)</para></listitem>
-            to a file system directory on the server.)
-          </para>
-        </listitem>
 
-        <listitem>
+  <listitem><para>The manifest is uploaded using an HTTP PUT request
-          <para>
+  to <replaceable>manifest-put-url</replaceable>.  The corresponding
-            The manifest is uploaded using an HTTP PUT request to
+  URL to download the manifest can then be used by
-            <replaceable>manifest-put-url</replaceable>.  The
+  <command>nix-pull</command>.</para></listitem>
-            corresponding URL to download the manifest can then be
-            used by <command>nix-pull</command>.
-          </para>
-        </listitem>
         
 </orderedlist>
+
 </para>
 
+<para>TODO: <option>--copy</option></para>
+            
 </refsection>
 
-  <refsection>
-    <title>Examples</title>
 
-    <para>
+<refsection><title>Examples</title>
-      To upload files there typically is some CGI script on the server
+
+<para>To upload files there typically is some CGI script on the server
 side.  This script should be be protected with a password.  The
-      following example uploads the store paths resulting from
+following example uploads the store paths resulting from building the
-      building the Nix expressions in <filename>foo.nix</filename>,
+Nix expressions in <filename>foo.nix</filename>, passing appropriate
-      passing appropriate authentication information:
+authentication information:
     
 <screen>
 $ nix-push \
@@ -121,11 +101,9 @@ $ nix-push \
     $(nix-instantiate foo.nix)</screen>
 
 This will push both sources and binaries (and any build-time
-    dependencies used in the build, such as compilers).
+dependencies used in the build, such as compilers).</para>
-    </para>
 
-    <para>
+<para>If we just want to push binaries, not sources and build-time
-      If we just want to push binaries, not sources and build-time
 dependencies, we can do:
       
 <screen>

doc/manual/nix-store.xml

@@ -86,7 +86,7 @@
 
   <!--######################################################################-->
 
-  <refsection>
+  <refsection id='rsec-nix-store-realise'>
     <title>Operation <option>--realise</option></title>
 
     <refsection>