* More doc updates.

doc/manual/nix-prefetch-url.xml

@@ -1,54 +1,69 @@
 <refentry>
-  <refnamediv>
+  
-    <refname>nix-prefetch-url</refname>
+<refnamediv>
-    <refpurpose>copy a file from a URL into the store and print its MD5 hash</refpurpose>
+  <refname>nix-prefetch-url</refname>
-  </refnamediv>
+  <refpurpose>copy a file from a URL into the store and print its MD5 hash</refpurpose>
+</refnamediv>
 
-  <refsynopsisdiv>
+<refsynopsisdiv>
-    <cmdsynopsis>
+  <cmdsynopsis>
-      <command>nix-prefetch-url</command>
+    <command>nix-prefetch-url</command>
-      <arg choice='plain'><replaceable>url</replaceable></arg>
+    <arg choice='plain'><replaceable>url</replaceable></arg>
-    </cmdsynopsis>
+    <arg><replaceable>hash</replaceable></arg>
-  </refsynopsisdiv>
+  </cmdsynopsis>
+</refsynopsisdiv>
 
-  <refsection>
-    <title>Description</title>
 
-    <para>
+<refsection><title>Description</title>
-      The command <command>nix-prefetch-url</command> downloads the
-      file referenced by the URL <replaceable>url</replaceable>,
-      prints its MD5 cryptographic hash code, and copies it into the
-      Nix store.  The file name in the store is
-      <filename><replaceable>hash</replaceable>-<replaceable>basename</replaceable></filename>,
-      where <replaceable>basename</replaceable> is everything
-      following the final slash in <replaceable>url</replaceable>.
-    </para>
 
-    <para>
+<para>The command <command>nix-prefetch-url</command> downloads the
-      This command is just a convenience to Nix expression writers.
+file referenced by the URL <replaceable>url</replaceable>, prints its
-      Often a Nix expressions fetch some source distribution from the
+cryptographic hash, and copies it into the Nix store.  The file name
-      network using the <literal>fetchurl</literal> expression
+in the store is
-      contained in <literal>nixpkgs</literal>.  However,
+<filename><replaceable>hash</replaceable>-<replaceable>baseName</replaceable></filename>,
-      <literal>fetchurl</literal> requires an MD5 hash.  If you don't
+where <replaceable>baseName</replaceable> is everything following the
-      know the hash, you would have to download the file first, and
+final slash in <replaceable>url</replaceable>.</para>
-      then <literal>fetchurl</literal> would download it again when
-      you build your Nix expression.  Since
-      <literal>fetchurl</literal> uses the same name for the
-      downloaded file as <command>nix-prefetch-url</command>, the
-      redundant download can be avoided.
-    </para>
 
-  </refsection>
+<para>This command is just a convenience for Nix expression writers.
+Often a Nix expression fetches some source distribution from the
+network using the <literal>fetchurl</literal> expression contained in
+Nixpkgs.  However, <literal>fetchurl</literal> requires a
+cryptographic hash.  If you don't know the hash, you would have to
+download the file first, and then <literal>fetchurl</literal> would
+download it again when you build your Nix expression.  Since
+<literal>fetchurl</literal> uses the same name for the downloaded file
+as <command>nix-prefetch-url</command>, the redundant download can be
+avoided.</para>
 
-  <refsection>
+<para>The environment variable <envar>NIX_HASH_ALGO</envar> specifies
-    <title>Examples</title>
+which hash algorithm to use.  It can be either <literal>md5</literal>,
+<literal>sha1</literal>, or <literal>sha256</literal>.  The default is
+<literal>md5</literal>.</para>
 
-    <screen>
+<para>If <replaceable>hash</replaceable> is specified, then a download
+is not performed if the Nix store already contains a file with the
+same hash and base name.  Otherwise, the file is downloaded, and an
+error if signaled if the actual hash of the file does not match the
+specified hash.</para>
+
+<para>This command prints the hash on standard output.  Additionally,
+if the environment variable <envar>PRINT_PATH</envar> is set, the path
+of the downloaded file in the Nix store is also printed.</para>
+
+</refsection>
+
+
+<refsection><title>Examples</title>
+
+<screen>
 $ nix-prefetch-url ftp://ftp.nluug.nl/pub/gnu/make/make-3.80.tar.bz2
-...
+0bbd1df101bc0294d440471e50feca71
-file has hash 0bbd1df101bc0294d440471e50feca71
+
-...</screen>
+$ PRINT_PATH=1 nix-prefetch-url ftp://ftp.nluug.nl/pub/gnu/make/make-3.80.tar.bz2
+0bbd1df101bc0294d440471e50feca71
+/nix/store/wvyz8ifdn7wyz1p3pqyn0ra45ka2l492-make-3.80.tar.bz2</screen>
+
+</refsection>
 
-  </refsection>
     
 </refentry>

doc/manual/nix-store.xml

@@ -189,7 +189,7 @@ linkend="sec-nix-build"><command>nix-build</command></link> does.</para>
 <cmdsynopsis>
   <command>nix-store</command>
   <arg choice='plain'><option>--gc</option></arg>
-  <group choice='req'>
+  <group>
     <arg choice='plain'><option>--print-roots</option></arg>
     <arg choice='plain'><option>--print-live</option></arg>
     <arg choice='plain'><option>--print-dead</option></arg>
@@ -451,7 +451,7 @@ most one query can be specified.  The default query is
 
 <cmdsynopsis>
   <command>nix-store</command>
-  <arg choice='req'><option>--register-validity</option></arg>
+  <arg choice='plain'><option>--register-validity</option></arg>
 </cmdsynopsis>
 </refsection>
 
@@ -473,7 +473,7 @@ most one query can be specified.  The default query is
 
 <cmdsynopsis>
   <command>nix-store</command>
-  <arg choice='req'><option>--substitute</option></arg>
+  <arg choice='plain'><option>--substitute</option></arg>
   <arg choice='plain'
        rep='repeat'><replaceable>srcpath</replaceable> <replaceable>subpath</replaceable></arg>
 </cmdsynopsis>
@@ -501,7 +501,8 @@ deployment.</para>
   <title>Synopsis</title>
   <cmdsynopsis>
     <command>nix-store</command>
-    <arg choice='req'><option>--verify</option></arg>
+    <arg choice='plain'><option>--verify</option></arg>
+    <arg><option>--check-contents</option></arg>
   </cmdsynopsis>
 </refsection>
 
@@ -514,6 +515,25 @@ automatically repaired.  Inconsistencies are generally the result of
 the Nix store or database being modified by non-Nix tools, or of bugs
 in Nix itself.</para>
 
+<para>There is one option:
+
+<variablelist>
+
+  <varlistentry><term><option>--check-contents</option></term>
+  
+    <listitem><para>Checks that the contents of every valid store path
+    has not been altered by computing a SHA-256 hash of the contents
+    and comparing it with the hash stored in the Nix database at build
+    time.  Paths that have been modified are printed out.  For large
+    stores, <option>--check-contents</option> is obviously quite
+    slow.</para></listitem>
+    
+  </varlistentry>
+  
+</variablelist>
+
+</para>
+
 </refsection>
             
 </refsection>