diff --git a/doc/manual/nix-store.xml b/doc/manual/nix-store.xml
index 719bfe0975..22bcb41e87 100644
--- a/doc/manual/nix-store.xml
+++ b/doc/manual/nix-store.xml
@@ -174,10 +174,19 @@ the specified store paths.  Realisation is a somewhat overloaded term:
 output.  (For non-derivations argument, the argument itself is
 printed.)</para>
 
-<para>If the <option>--dry-run</option> option is used, then
-<command>nix-store</command> will print on standard error a
-description of what packages would be built or downloaded, and then
-quit.</para>
+<para>The following flags are available:</para>
+
+<variablelist>
+
+  <varlistentry><term><option>--dry-run</option></term>
+
+    <listitem><para>Print on standard error a description of what
+    packages would be built or downloaded, without actually performing
+    the operation</para></listitem>
+
+  </varlistentry>
+
+</variablelist>
 
 </refsection>
             
diff --git a/doc/manual/opt-common.xml b/doc/manual/opt-common.xml
index 0b57517670..72971bd6a7 100644
--- a/doc/manual/opt-common.xml
+++ b/doc/manual/opt-common.xml
@@ -361,6 +361,17 @@
 </varlistentry>
 
 
+<varlistentry><term><option>--repair</option></term>
+
+  <listitem><para>Fix corrupted or missing store paths by
+  redownloading or rebuilding them.  Note that this is slow because it
+  requires computing a cryptographic hash of the contents of every
+  path in the closure of the build.  Also note the warning under
+  <command>nix-store --repair-path</command>.</para></listitem>
+
+</varlistentry>
+
+
 </variablelist>
 
 
diff --git a/doc/manual/release-notes.xml b/doc/manual/release-notes.xml
index af196344c4..43d5080afa 100644
--- a/doc/manual/release-notes.xml
+++ b/doc/manual/release-notes.xml
@@ -21,8 +21,14 @@
 
   <listitem>
     <para>The new operation <command>nix-store --repair-path</command>
-    allows corrupted or deleted store paths to be repaired by
-    redownloading them.</para>
+    allows corrupted or missing store paths to be repaired by
+    redownloading them.  <command>nix-store --verify --check-contents
+    --repair</command> will scan and repair all paths in the Nix
+    store.  Similarly, <command>nix-env</command>,
+    <command>nix-build</command>, <command>nix-instantiate</command>
+    and <command>nix-store --realise</command> have a
+    <option>--repair</option> flag to detect and fix bad paths by
+    rebuilding or redownloading them.</para>
   </listitem>
 
   <listitem>