diff --git a/doc/manual/command-ref/nix-copy-closure.xml b/doc/manual/command-ref/nix-copy-closure.xml
index 97e261ae9..800e1db6a 100644
--- a/doc/manual/command-ref/nix-copy-closure.xml
+++ b/doc/manual/command-ref/nix-copy-closure.xml
@@ -27,8 +27,10 @@
     <arg><option>- -show-progress</option></arg>
     -->
     <arg><option>--include-outputs</option></arg>
-    <arg><option>--use-substitutes</option></arg>
-    <arg><option>-s</option></arg>
+    <group>
+      <arg choice='plain'><option>--use-substitutes</option></arg>
+      <arg choice='plain'><option>-s</option></arg>
+    </group>
     <arg><option>-v</option></arg>
     <arg choice='plain'>
       <replaceable>user@</replaceable><replaceable>machine</replaceable>
diff --git a/doc/manual/command-ref/nix-env.xml b/doc/manual/command-ref/nix-env.xml
index 8462cf8a0..d4563ac47 100644
--- a/doc/manual/command-ref/nix-env.xml
+++ b/doc/manual/command-ref/nix-env.xml
@@ -146,8 +146,7 @@ also <xref linkend="sec-common-options" />.</phrase></para>
 
 <variablelist>
 
-  <varlistentry><term><option>--file</option></term>
-    <term><option>-f</option></term>
+  <varlistentry><term><option>--file</option> / <option>-f</option> <replaceable>path</replaceable></term>
 
     <listitem><para>Specifies the Nix expression (designated below as
     the <emphasis>active Nix expression</emphasis>) used by the
@@ -166,8 +165,7 @@ also <xref linkend="sec-common-options" />.</phrase></para>
 
   </varlistentry>
 
-  <varlistentry><term><option>--profile</option></term>
-    <term><option>-p</option></term>
+  <varlistentry><term><option>--profile</option> / <option>-p</option> <replaceable>path</replaceable></term>
 
     <listitem><para>Specifies the profile to be used by those
     operations that operate on a profile (designated below as the
diff --git a/doc/manual/command-ref/nix-instantiate.xml b/doc/manual/command-ref/nix-instantiate.xml
index fe077ff65..39c1282fc 100644
--- a/doc/manual/command-ref/nix-instantiate.xml
+++ b/doc/manual/command-ref/nix-instantiate.xml
@@ -24,6 +24,7 @@
       <arg choice='plain'>
         <option>--eval</option>
         <arg><option>--strict</option></arg>
+        <arg><option>--json</option></arg>
         <arg><option>--xml</option></arg>
       </arg>
     </group>
@@ -38,7 +39,7 @@
     </arg>
     <arg><option>--add-root</option> <replaceable>path</replaceable></arg>
     <arg><option>--indirect</option></arg>
-    <group choice='req'>
+    <group>
       <arg choice='plain'><option>--expr</option></arg>
       <arg choice='plain'><option>-E</option></arg>
     </group>
@@ -116,24 +117,6 @@ input.</para>
 
   </varlistentry>
 
-  <varlistentry><term><option>--xml</option></term>
-
-    <listitem><para>When used with <option>--eval</option>, print the resulting
-    value as an XML representation of the abstract syntax tree rather than as
-    an ATerm. The schema is the same as that used by the <link
-    linkend="builtin-toXML"><function>toXML</function> built-in</link>.
-    </para></listitem>
-
-  </varlistentry>
-
-  <varlistentry><term><option>--json</option></term>
-
-    <listitem><para>When used with <option>--eval</option>, print the resulting
-    value as an JSON representation of the abstract syntax tree rather
-    than as an ATerm.</para></listitem>
-
-  </varlistentry>
-
   <varlistentry><term><option>--strict</option></term>
 
     <listitem><para>When used with <option>--eval</option>,
@@ -148,6 +131,24 @@ input.</para>
 
   </varlistentry>
 
+  <varlistentry><term><option>--json</option></term>
+
+    <listitem><para>When used with <option>--eval</option>, print the resulting
+    value as an JSON representation of the abstract syntax tree rather
+    than as an ATerm.</para></listitem>
+
+  </varlistentry>
+
+  <varlistentry><term><option>--xml</option></term>
+
+    <listitem><para>When used with <option>--eval</option>, print the resulting
+    value as an XML representation of the abstract syntax tree rather than as
+    an ATerm. The schema is the same as that used by the <link
+    linkend="builtin-toXML"><function>toXML</function> built-in</link>.
+    </para></listitem>
+
+  </varlistentry>
+
   <varlistentry><term><option>--read-write-mode</option></term>
 
     <listitem><para>When used with <option>--eval</option>, perform
diff --git a/doc/manual/command-ref/nix-prefetch-url.xml b/doc/manual/command-ref/nix-prefetch-url.xml
index 016d8863a..8ef748c74 100644
--- a/doc/manual/command-ref/nix-prefetch-url.xml
+++ b/doc/manual/command-ref/nix-prefetch-url.xml
@@ -19,14 +19,16 @@
 <refsynopsisdiv>
   <cmdsynopsis>
     <command>nix-prefetch-url</command>
+    <arg><option>--version</option></arg>
     <arg><option>--type</option> <replaceable>hashAlgo</replaceable></arg>
     <arg><option>--print-path</option></arg>
+    <arg><option>--unpack</option></arg>
+    <arg><option>--name</option> <replaceable>name</replaceable></arg>
     <arg choice='plain'><replaceable>url</replaceable></arg>
     <arg><replaceable>hash</replaceable></arg>
   </cmdsynopsis>
 </refsynopsisdiv>
 
-
 <refsection><title>Description</title>
 
 <para>The command <command>nix-prefetch-url</command> downloads the
@@ -91,7 +93,7 @@ downloaded file in the Nix store is also printed.</para>
 
   </varlistentry>
 
-  <varlistentry><term><option>--name</option></term>
+  <varlistentry><term><option>--name</option> <replaceable>name</replaceable></term>
 
     <listitem><para>Override the name of the file in the Nix store. By
     default, this is
diff --git a/doc/manual/command-ref/nix-shell.xml b/doc/manual/command-ref/nix-shell.xml
index c64c93ec3..62d026ac2 100644
--- a/doc/manual/command-ref/nix-shell.xml
+++ b/doc/manual/command-ref/nix-shell.xml
@@ -33,13 +33,13 @@
     <arg><option>--exclude</option> <replaceable>regexp</replaceable></arg>
     <arg><option>--pure</option></arg>
     <group choice='req'>
-      <group choice='plain'>
-        <group>
+      <arg choice='plain'>
+        <group choice='req'>
           <arg choice='plain'><option>--packages</option></arg>
           <arg choice='plain'><option>-p</option></arg>
         </group>
-        <replaceable>packages</replaceable>
-      </group>
+        <arg choice='plain' rep='repeat'><replaceable>packages</replaceable></arg>
+      </arg>
       <arg><replaceable>path</replaceable></arg>
     </group>
   </cmdsynopsis>
@@ -144,7 +144,7 @@ also <xref linkend="sec-common-options" />.</phrase></para>
 
   </varlistentry>
 
-  <varlistentry><term><option>--packages</option> / <option>-p</option></term>
+  <varlistentry><term><option>--packages</option> / <option>-p</option> <replaceable>packages</replaceable>…</term>
 
     <listitem><para>Set up an environment in which the specified
     packages are present.  The command line arguments are interpreted
diff --git a/doc/manual/command-ref/nix-store.xml b/doc/manual/command-ref/nix-store.xml
index fb017b741..19c99841a 100644
--- a/doc/manual/command-ref/nix-store.xml
+++ b/doc/manual/command-ref/nix-store.xml
@@ -234,7 +234,7 @@ linkend="sec-nix-build"><command>nix-build</command></link> does.</para>
 <para>To test whether a previously-built derivation is deterministic:
 
 <screen>
-$ nix-build -r '&lt;nixpkgs>' -A hello --check -K
+$ nix-build '&lt;nixpkgs>' -A hello --check -K
 </screen>
 
 </para>
diff --git a/doc/manual/command-ref/opt-common-syn.xml b/doc/manual/command-ref/opt-common-syn.xml
index 5b7936393..3aff4e1b6 100644
--- a/doc/manual/command-ref/opt-common-syn.xml
+++ b/doc/manual/command-ref/opt-common-syn.xml
@@ -2,10 +2,18 @@
   
 <arg><option>--help</option></arg>
 <arg><option>--version</option></arg>
-<arg rep='repeat'><option>--verbose</option></arg>
-<arg rep='repeat'><option>-v</option></arg>
-<arg><option>--no-build-output</option></arg>
-<arg><option>-Q</option></arg>
+<arg rep='repeat'>
+  <group choice='req'>
+    <arg choice='plain'><option>--verbose</option></arg>
+    <arg choice='plain'><option>-v</option></arg>
+  </group>
+</arg>
+<arg>
+  <group choice='plain'>
+    <arg choice='plain'><option>--no-build-output</option></arg>
+    <arg choice='plain'><option>-Q</option></arg>
+  </group>
+</arg>
 <arg>
   <group choice='req'>
     <arg choice='plain'><option>--max-jobs</option></arg>
@@ -25,10 +33,18 @@
   <option>--timeout</option>
   <replaceable>number</replaceable>
 </arg>
-<arg><option>--keep-going</option></arg>
-<arg><option>-k</option></arg>
-<arg><option>--keep-failed</option></arg>
-<arg><option>-K</option></arg>
+<arg>
+  <group choice='plain'>
+    <arg choice='plain'><option>--keep-going</option></arg>
+    <arg choice='plain'><option>-k</option></arg>
+  </group>
+</arg>
+<arg>
+  <group choice='plain'>
+    <arg choice='plain'><option>--keep-failed</option></arg>
+    <arg choice='plain'><option>-K</option></arg>
+  </group>
+</arg>
 <arg><option>--fallback</option></arg>
 <arg><option>--readonly-mode</option></arg>
 <arg><option>--show-trace</option></arg>
diff --git a/doc/manual/command-ref/opt-common.xml b/doc/manual/command-ref/opt-common.xml
index 2aa41c4d4..a930b4a0d 100644
--- a/doc/manual/command-ref/opt-common.xml
+++ b/doc/manual/command-ref/opt-common.xml
@@ -22,8 +22,7 @@
 </varlistentry>
 
 
-<varlistentry><term><option>--verbose</option></term>
-  <term><option>-v</option></term>
+<varlistentry><term><option>--verbose</option> / <option>-v</option></term>
 
   <listitem>
 
@@ -76,8 +75,7 @@
 </varlistentry>
 
 
-<varlistentry><term><option>--no-build-output</option></term>
-  <term><option>-Q</option></term>
+<varlistentry><term><option>--no-build-output</option> / <option>-Q</option></term>
 
   <listitem><para>By default, output written by builders to standard
   output and standard error is echoed to the Nix command's standard
@@ -89,8 +87,8 @@
 </varlistentry>
 
 
-<varlistentry xml:id="opt-max-jobs"><term><option>--max-jobs</option></term>
-  <term><option>-j</option></term>
+<varlistentry xml:id="opt-max-jobs"><term><option>--max-jobs</option> / <option>-j</option>
+<replaceable>number</replaceable></term>
 
   <listitem><para>Sets the maximum number of build jobs that Nix will
   perform in parallel to the specified number.  Specify
@@ -143,8 +141,7 @@
 
 </varlistentry>
 
-<varlistentry><term><option>--keep-going</option></term>
-  <term><option>-k</option></term>
+<varlistentry><term><option>--keep-going</option> / <option>-k</option></term>
 
   <listitem><para>Keep going in case of failed builds, to the
   greatest extent possible.  That is, if building an input of some
@@ -156,8 +153,7 @@
 </varlistentry>
 
 
-<varlistentry><term><option>--keep-failed</option></term>
-  <term><option>-K</option></term>
+<varlistentry><term><option>--keep-failed</option> / <option>-K</option></term>
 
   <listitem><para>Specifies that in case of a build failure, the
   temporary directory (usually in <filename>/tmp</filename>) in which
diff --git a/doc/manual/glossary/glossary.xml b/doc/manual/glossary/glossary.xml
index d74940c90..e0636044c 100644
--- a/doc/manual/glossary/glossary.xml
+++ b/doc/manual/glossary/glossary.xml
@@ -54,7 +54,7 @@
 
   <glossdef><para>A substitute is a command invocation stored in the
   Nix database that describes how to build a store object, bypassing
-  normal the build mechanism (i.e., derivations).  Typically, the
+  the normal build mechanism (i.e., derivations).  Typically, the
   substitute builds the store object by downloading a pre-built
   version of the store object from some server.</para></glossdef>