Clean up the manpages

12 files changed, 248 insertions, 701 deletions

diff --git a/doc/manual/src/command-ref/conf-file.md b/doc/manual/src/command-ref/conf-file.md
index 92abeb73e..4fa9cedfc 100644
--- a/doc/manual/src/command-ref/conf-file.md
+++ b/doc/manual/src/command-ref/conf-file.md
@@ -1,12 +1,8 @@
-nix.conf
+Title: nix.conf
 
-5
+# Name
 
-Nix
-
-nix.conf
-
-Nix configuration file
+`nix.conf` - Nix configuration file
 
 # Description
 
@@ -20,7 +16,7 @@ By default Nix reads settings from the following places:
 
   - If `NIX_USER_CONF_FILES` is set, then each path separated by `:`
     will be loaded in reverse order.
-    
+
     Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS`
     and `XDG_CONFIG_HOME`. If these are unset, it will look in
     `$HOME/.config/nix.conf`.
diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md
index ddebc4b1b..a65f53b4b 100644
--- a/doc/manual/src/command-ref/nix-build.md
+++ b/doc/manual/src/command-ref/nix-build.md
@@ -1,44 +1,18 @@
-nix-build
+Title: nix-build
 
-1
+# Name
 
-Nix
+`nix-build` - build a Nix expression
 
-nix-build
+# Synopsis
 
-build a Nix expression
-
-nix-build
-
-\--arg
-
-name
-
-value
-
-\--argstr
-
-name
-
-value
-
-\--attr
-
-\-A
-
-attrPath
-
-\--no-out-link
-
-\--dry-run
-
-\--out-link
-
-\-o
-
-outlink
-
-paths
+`nix-build` [*paths…*]
+  [`--arg` *name* *value*]
+  [`--argstr` *name* *value*]
+  [{`--attr` | `-A`} *attrPath*]
+  [`--no-out-link`]
+  [`--dry-run`]
+  [{`--out-link` | `-o`} *outlink*]
 
 # Description
 
@@ -63,7 +37,7 @@ expression to a low-level store derivation) and [`nix-store
 --realise`](#rsec-nix-store-realise) (to build the store derivation).
 
 > **Warning**
-> 
+>
 > The result of the build is automatically registered as a root of the
 > Nix garbage collector. This root disappears automatically when the
 > `result` symlink is deleted or renamed. So don’t rename the symlink.
@@ -94,10 +68,10 @@ The following common options are supported:
     $ nix-build '<nixpkgs>' -A firefox
     store derivation is /nix/store/qybprl8sz2lc...-firefox-1.5.0.7.drv
     /nix/store/d18hyl92g30l...-firefox-1.5.0.7
-    
+
     $ ls -l result
     lrwxrwxrwx  ...  result -> /nix/store/d18hyl92g30l...-firefox-1.5.0.7
-    
+
     $ ls ./result/bin/
     firefox  firefox-config
 
diff --git a/doc/manual/src/command-ref/nix-channel.md b/doc/manual/src/command-ref/nix-channel.md
index 0c20788f0..6b4bd2459 100644
--- a/doc/manual/src/command-ref/nix-channel.md
+++ b/doc/manual/src/command-ref/nix-channel.md
@@ -1,34 +1,12 @@
-nix-channel
+Title: nix-channel
 
-1
+# Name
 
-Nix
+`nix-channel` - manage Nix channels
 
-nix-channel
+# Synopsis
 
-manage Nix channels
-
-nix-channel
-
-\--add
-
-url
-
-name
-
-\--remove
-
-name
-
-\--list
-
-\--update
-
-names
-
-\--rollback
-
-generation
+`nix-channel` {`--add` url [*name*] | `--remove` *name* | `--list` | `--update` [*names…*] | `--rollback` [*generation*] }
 
 # Description
 
@@ -82,10 +60,10 @@ You can revert channel updates using `--rollback`:
 
     $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'
     "14.04.527.0e935f1"
-    
+
     $ nix-channel --rollback
     switching from generation 483 to 482
-    
+
     $ nix-instantiate --eval -E '(import <nixpkgs> {}).lib.version'
     "14.04.526.dbadfad"
 
diff --git a/doc/manual/src/command-ref/nix-collect-garbage.md b/doc/manual/src/command-ref/nix-collect-garbage.md
index 77b5d42d3..7b246f3b3 100644
--- a/doc/manual/src/command-ref/nix-collect-garbage.md
+++ b/doc/manual/src/command-ref/nix-collect-garbage.md
@@ -1,28 +1,12 @@
-nix-collect-garbage
+Title: nix-collect-garbage
 
-1
+# Name
 
-Nix
+`nix-collect-garbage` - delete unreachable store paths
 
-nix-collect-garbage
+# Synopsis
 
-delete unreachable store paths
-
-nix-collect-garbage
-
-\--delete-old
-
-\-d
-
-\--delete-older-than
-
-period
-
-\--max-freed
-
-bytes
-
-\--dry-run
+`nix-collect-garbage` [`--delete-old`] [`-d`] [`--delete-older-than` *period*] [`--max-freed` *bytes*] [`--dry-run`]
 
 # Description
 
diff --git a/doc/manual/src/command-ref/nix-copy-closure.md b/doc/manual/src/command-ref/nix-copy-closure.md
index 037334c4d..4026e50de 100644
--- a/doc/manual/src/command-ref/nix-copy-closure.md
+++ b/doc/manual/src/command-ref/nix-copy-closure.md
@@ -6,7 +6,13 @@ Title: nix-copy-closure
 
 # Synopsis
 
-`nix-copy-closure` [`--to` | `--from`] [`--gzip`] [`--include-outputs`] [`--use-substitutes` | `-s`] [`-v`] _user@machine_ _paths_
+`nix-copy-closure`
+  [`--to` | `--from`]
+  [`--gzip`]
+  [`--include-outputs`]
+  [`--use-substitutes` | `-s`]
+  [`-v`]
+  _user@machine_ _paths_
 
 # Description
 
@@ -75,4 +81,3 @@ environment:
     $ nix-copy-closure --from alice@itchy.labs \
         /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4
     $ nix-env -i /nix/store/0dj0503hjxy5mbwlafv1rsbdiyx1gkdy-subversion-1.4.4
-
diff --git a/doc/manual/src/command-ref/nix-daemon.md b/doc/manual/src/command-ref/nix-daemon.md
index b0570789c..bd5d25026 100644
--- a/doc/manual/src/command-ref/nix-daemon.md
+++ b/doc/manual/src/command-ref/nix-daemon.md
@@ -1,14 +1,12 @@
-nix-daemon
+Title: nix-daemon
 
-8
+# Name
 
-Nix
+`nix-daemon` - Nix multi-user support daemon
 
-nix-daemon
+# Synopsis
 
-Nix multi-user support daemon
-
-nix-daemon
+`nix-daemon`
 
 # Description
 
diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md
index 90a2bd351..cf688100e 100644
--- a/doc/manual/src/command-ref/nix-env.md
+++ b/doc/manual/src/command-ref/nix-env.md
@@ -1,50 +1,20 @@
-nix-env
+Title: nix-env
 
-1
+# Name
 
-Nix
+`nix-env` - manipulate or query Nix user environments
 
-nix-env
+# Synopsis
 
-manipulate or query Nix user environments
-
-nix-env
-
-\--arg
-
-name
-
-value
-
-\--argstr
-
-name
-
-value
-
-\--file
-
-\-f
-
-path
-
-\--profile
-
-\-p
-
-path
-
-\--system-filter
-
-system
-
-\--dry-run
-
-operation
-
-options
-
-arguments
+`nix-env`
+  [`--option` *name* *value*]
+  [`--arg` *name* *value*]
+  [`--argstr` *name* *value*]
+  [{`--file` | `-f`} *path*]
+  [{`--profile` | `-p`} *path(]
+  [`--system-filter` *system*]
+  [`--dry-run`]
+  *operation* [*options…*] [*arguments…*]
 
 # Description
 
@@ -103,7 +73,7 @@ have an effect. See also [???](#sec-common-options).
     expression*) used by the `--install`, `--upgrade`, and `--query
     --available` operations to obtain derivations. The default is
     `~/.nix-defexpr`.
-    
+
     If the argument starts with `http://` or `https://`, it is
     interpreted as the URL of a tarball that will be downloaded and
     unpacked to a temporary location. The tarball must include a single
@@ -120,7 +90,7 @@ have an effect. See also [???](#sec-common-options).
     `--switch-generation`, `--delete-generations` and `--rollback`
     operations, this flag will cause `nix-env` to print what *would* be
     done if this flag had not been specified, without actually doing it.
-    
+
     `--dry-run` also prints out which paths will be
     [substituted](#gloss-substitute) (i.e., downloaded) and which paths
     will be built from source (because no substitute is available).
@@ -135,38 +105,38 @@ have an effect. See also [???](#sec-common-options).
 # Files
 
   - `~/.nix-defexpr`  
-    The source for the default Nix expressions used by the `--install`,
-    `--upgrade`, and `--query
-                    --available` operations to obtain derivations. The `--file` option
-    may be used to override this default.
-    
+    The source for the default Nix expressions used by the
+    `--install`, `--upgrade`, and `--query --available` operations to
+    obtain derivations. The `--file` option may be used to override
+    this default.
+
     If `~/.nix-defexpr` is a file, it is loaded as a Nix expression. If
     the expression is a set, it is used as the default Nix expression.
     If the expression is a function, an empty set is passed as argument
     and the return value is used as the default Nix expression.
-    
+
     If `~/.nix-defexpr` is a directory containing a `default.nix` file,
     that file is loaded as in the above paragraph.
-    
+
     If `~/.nix-defexpr` is a directory without a `default.nix` file,
     then its contents (both files and subdirectories) are loaded as Nix
     expressions. The expressions are combined into a single set, each
     expression under an attribute with the same name as the original
     file or subdirectory.
-    
+
     For example, if `~/.nix-defexpr` contains two files, `foo.nix` and
     `bar.nix`, then the default Nix expression will essentially be
-    
+
         {
           foo = import ~/.nix-defexpr/foo.nix;
           bar = import ~/.nix-defexpr/bar.nix;
         }
-    
+
     The file `manifest.nix` is always ignored. Subdirectories without a
     `default.nix` file are traversed recursively in search of more Nix
     expressions, but the names of these intermediate directories are not
     added to the attribute paths of the default Nix expression.
-    
+
     The command `nix-channel` places symlinks to the downloaded Nix
     expressions from each subscribed channel in this directory.
 
@@ -180,21 +150,13 @@ have an effect. See also [???](#sec-common-options).
 
 ## Synopsis
 
-nix-env
-
-\--install
-
-\-i
-
-\--preserve-installed
-
-\-P
-
-\--remove-all
-
-\-r
-
-args
+`nix-env` {`--install` | `-i`} *args…*
+  [{`--prebuilt-only` | `-b`}]
+  [{`--attr` | `-A`}]
+  [`--from-expression`] [`-E`]
+  [`--from-profile` *path*]
+  [`--preserve-installed` | `-P`]
+  [`--remove-all` | `-r`]
 
 ## Description
 
@@ -208,17 +170,17 @@ a number of possible ways:
     output paths are installed. Currently installed derivations with a
     name equal to the name of a derivation being added are removed
     unless the option `--preserve-installed` is specified.
-    
+
     If there are multiple derivations matching a name in *args* that
     have the same name (e.g., `gcc-3.3.6` and `gcc-4.1.1`), then the
     derivation with the highest *priority* is used. A derivation can
     define a priority by declaring the `meta.priority` attribute. This
     attribute should be a number, with a higher value denoting a lower
     priority. The default priority is `0`.
-    
+
     If there are multiple matching derivations with the same priority,
     then the derivation with the highest version will be installed.
-    
+
     You can force the installation of multiple derivations with the same
     name by being specific about the versions. For instance, `nix-env -i
     gcc-3.3.6 gcc-4.1.1` will install both version of GCC (and will
@@ -339,21 +301,13 @@ channel:
 
 ## Synopsis
 
-nix-env
-
-\--upgrade
-
-\-u
-
-\--lt
-
-\--leq
-
-\--eq
-
-\--always
-
-args
+`nix-env` {`--upgrade` | `-u`} *args*
+  [`--lt` | `--leq` | `--eq` | `--always`]
+  [{`--prebuilt-only` | `-b`}]
+  [{`--attr` | `-A`}]
+  [`--from-expression`] [`-E`]
+  [`--from-profile` *path*]
+  [`--preserve-installed` | `-P`]
 
 ## Description
 
@@ -400,13 +354,13 @@ For the other flags, see `--install`.
 
     $ nix-env --upgrade gcc
     upgrading `gcc-3.3.1' to `gcc-3.4'
-    
+
     $ nix-env -u gcc-3.3.2 --always (switch to a specific version)
     upgrading `gcc-3.4' to `gcc-3.3.2'
-    
+
     $ nix-env --upgrade pan
     (no upgrades available, so nothing happens)
-    
+
     $ nix-env -u (try to upgrade everything)
     upgrading `hello-2.1.2' to `hello-2.1.3'
     upgrading `mozilla-1.2' to `mozilla-1.4'
@@ -451,19 +405,13 @@ This is illustrated by the following examples:
 
 ## Synopsis
 
-nix-env
-
-\--uninstall
-
-\-e
-
-drvnames
+`nix-env` {`--uninstall` | `-e`} *drvnames…*
 
 ## Description
 
 The uninstall operation creates a new user environment, based on the
 current generation of the active profile, from which the store paths
-designated by the symbolic names *names* are removed.
+designated by the symbolic names *drvnames* are removed.
 
 ## Examples
 
@@ -474,11 +422,7 @@ designated by the symbolic names *names* are removed.
 
 ## Synopsis
 
-nix-env
-
-\--set
-
-drvname
+`nix-env` `--set` *drvname*
 
 ## Description
 
@@ -496,15 +440,7 @@ contain just Firefox:
 
 ## Synopsis
 
-nix-env
-
-\--set-flag
-
-name
-
-value
-
-drvnames
+`nix-env` `--set-flag` *name* *value* *drvnames*
 
 ## Description
 
@@ -545,20 +481,20 @@ while the old remains part of the profile:
 
     $ nix-env -q
     firefox-2.0.0.9 (the current one)
-    
+
     $ nix-env --preserve-installed -i firefox-2.0.0.11
     installing `firefox-2.0.0.11'
     building path(s) `/nix/store/myy0y59q3ig70dgq37jqwg1j0rsapzsl-user-environment'
     collision between `/nix/store/...-firefox-2.0.0.11/bin/firefox'
       and `/nix/store/...-firefox-2.0.0.9/bin/firefox'.
     (i.e., can’t have two active at the same time)
-    
+
     $ nix-env --set-flag active false firefox
     setting flag on `firefox-2.0.0.9'
-    
+
     $ nix-env --preserve-installed -i firefox-2.0.0.11
     installing `firefox-2.0.0.11'
-    
+
     $ nix-env -q
     firefox-2.0.0.11 (the enabled one)
     firefox-2.0.0.9 (the disabled one)
@@ -572,57 +508,21 @@ To make files from `binutils` take precedence over files from `gcc`:
 
 ## Synopsis
 
-nix-env
-
-\--query
-
-\-q
-
-\--installed
-
-\--available
-
-\-a
-
-\--status
-
-\-s
-
-\--attr-path
-
-\-P
-
-\--no-name
-
-\--compare-versions
-
-\-c
-
-\--system
-
-\--drv-path
-
-\--out-path
-
-\--description
-
-\--meta
-
-\--xml
-
-\--json
-
-\--prebuilt-only
-
-\-b
-
-\--attr
-
-\-A
-
-attribute-path
-
-names
+`nix-env` {`--query` | `-q`} *names…*
+  [`--installed` | `--available` | `-a`]
+  [{`--status` | `-s`}]
+  [{`--attr-path` | `-P`}]
+  [`--no-name`]
+  [{`--compare-versions` | `-c`}]
+  [`--system`]
+  [`--drv-path`]
+  [`--out-path`]
+  [`--description`]
+  [`--meta`]
+  [`--xml`]
+  [`--json`]
+  [{`--prebuilt-only` | `-b`}]
+  [{`--attr` | `-A`} *attribute-path*]
 
 ## Description
 
@@ -696,17 +596,17 @@ derivation is shown unless `--no-name` is specified.
     `--available` is given). This is useful for quickly seeing whether
     upgrades for installed packages are available in a Nix expression. A
     column is added with the following meaning:
-    
+
       - `<` *version*  
         A newer version of the package is available or installed.
-    
+
       - `=` *version*  
         At most the same version of the package is available or
         installed.
-    
+
       - `>` *version*  
         Only older versions of the package are available or installed.
-    
+
       - `- ?`  
         No version of the package is available or installed.
 
@@ -797,13 +697,7 @@ To show all packages in the latest revision of the Nixpkgs repository:
 
 ## Synopsis
 
-nix-env
-
-\--switch-profile
-
-\-S
-
-path
+`nix-env` {`--switch-profile` | `-S`} *path*
 
 ## Description
 
@@ -818,9 +712,7 @@ the symlink `~/.nix-profile` is made to point to *path*.
 
 ## Synopsis
 
-nix-env
-
-\--list-generations
+`nix-env` `--list-generations`
 
 ## Description
 
@@ -841,11 +733,7 @@ generation, and indicates the current generation.
 
 ## Synopsis
 
-nix-env
-
-\--delete-generations
-
-generations
+`nix-env` `--delete-generations` *generations*
 
 ## Description
 
@@ -862,24 +750,18 @@ generations is important to make garbage collection effective.
 ## Examples
 
     $ nix-env --delete-generations 3 4 8
-    
+
     $ nix-env --delete-generations +5
-    
+
     $ nix-env --delete-generations 30d
-    
+
     $ nix-env -p other_profile --delete-generations old
 
 # Operation `--switch-generation`
 
 ## Synopsis
 
-nix-env
-
-\--switch-generation
-
-\-G
-
-generation
+`nix-env` {`--switch-generation` | `-G`} *generation*
 
 ## Description
 
@@ -900,9 +782,7 @@ Switching will fail if the specified generation does not exist.
 
 ## Synopsis
 
-nix-env
-
-\--rollback
+`nix-env` `--rollback`
 
 ## Description
 
@@ -915,7 +795,7 @@ generation, if it exists. It is just a convenience wrapper around
 
     $ nix-env --rollback
     switching from generation 92 to 91
-    
+
     $ nix-env --rollback
     error: no generation older than the current (91) exists
 
diff --git a/doc/manual/src/command-ref/nix-hash.md b/doc/manual/src/command-ref/nix-hash.md
index 3b8bbf740..38c9e0f67 100644
--- a/doc/manual/src/command-ref/nix-hash.md
+++ b/doc/manual/src/command-ref/nix-hash.md
@@ -1,38 +1,16 @@
-nix-hash
+Title: nix-hash
 
-1
+# Name
 
-Nix
+`nix-hash` - compute the cryptographic hash of a path
 
-nix-hash
+# Synopsis
 
-compute the cryptographic hash of a path
+`nix-hash` [`--flat`] [`--base32`] [`--truncate`] [`--type` *hashAlgo*] *path…*
 
-nix-hash
+`nix-hash` `--to-base16` *hash…*
 
-\--flat
-
-\--base32
-
-\--truncate
-
-\--type
-
-hashAlgo
-
-path
-
-nix-hash
-
-\--to-base16
-
-hash
-
-nix-hash
-
-\--to-base32
-
-hash
+`nix-hash` `--to-base32` *hash…*
 
 # Description
 
@@ -92,22 +70,22 @@ Computing hashes:
 
     $ mkdir test
     $ echo "hello" > test/world
-    
+
     $ nix-hash test/ (MD5 hash; default)
     8179d3caeff1869b5ba1744e5a245c04
-    
+
     $ nix-store --dump test/ | md5sum (for comparison)
     8179d3caeff1869b5ba1744e5a245c04  -
-    
+
     $ nix-hash --type sha1 test/
     e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6
-    
+
     $ nix-hash --type sha1 --base32 test/
     nvd61k9nalji1zl9rrdfmsmvyyjqpzg4
-    
+
     $ nix-hash --type sha256 --flat test/
     error: reading file `test/': Is a directory
-    
+
     $ nix-hash --type sha256 --flat test/world
     5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03
 
@@ -115,6 +93,6 @@ Converting between hexadecimal and base-32:
 
     $ nix-hash --type sha1 --to-base32 e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6
     nvd61k9nalji1zl9rrdfmsmvyyjqpzg4
-    
+
     $ nix-hash --type sha1 --to-base16 nvd61k9nalji1zl9rrdfmsmvyyjqpzg4
     e4fd8ba5f7bbeaea5ace89fe10255536cd60dab6
diff --git a/doc/manual/src/command-ref/nix-instantiate.md b/doc/manual/src/command-ref/nix-instantiate.md
index 6c9f2d3e1..b6bbbe80a 100644
--- a/doc/manual/src/command-ref/nix-instantiate.md
+++ b/doc/manual/src/command-ref/nix-instantiate.md
@@ -1,56 +1,22 @@
-nix-instantiate
+Title: nix-instantiate
 
-1
+# Name
 
-Nix
+`nix-instantiate` - instantiate store derivations from Nix expressions
 
-nix-instantiate
+# Synopsis
 
-instantiate store derivations from Nix expressions
+`nix-instantiate`
+  [`--parse` | `--eval` [`--strict`] [`--json`] [`--xml`] ]
+  [`--read-write-mode`]
+  [`--arg` *name* *value*]
+  [{`--attr`| `-A`} *attrPath*]
+  [`--add-root` *path*]
+  [`--indirect`]
+  [`--expr` | `-E`]
+  *files…*
 
-nix-instantiate
-
-\--parse
-
-\--eval
-
-\--strict
-
-\--json
-
-\--xml
-
-\--read-write-mode
-
-\--arg
-
-name
-
-value
-
-\--attr
-
-\-A
-
-attrPath
-
-\--add-root
-
-path
-
-\--indirect
-
-\--expr
-
-\-E
-
-files
-
-nix-instantiate
-
-\--find-file
-
-files
+`nix-instantiate` `--find-file` *files…*
 
 # Description
 
@@ -91,9 +57,9 @@ See also [???](#sec-common-options) for a list of common options.
     When used with `--eval`, recursively evaluate list elements and
     attributes. Normally, such sub-expressions are left unevaluated
     (since the Nix expression language is lazy).
-    
+
     > **Warning**
-    > 
+    >
     > This option can cause non-termination, because lazy data
     > structures can be infinitely large.
 
@@ -123,11 +89,11 @@ using `nix-store`:
 
     $ nix-instantiate test.nix (instantiate)
     /nix/store/cigxbmvy6dzix98dxxh9b6shg7ar5bvs-perl-BerkeleyDB-0.26.drv
-    
+
     $ nix-store -r $(nix-instantiate test.nix) (build)
     ...
     /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26 (output path)
-    
+
     $ ls -l /nix/store/qhqk4n8ci095g3sdp93x7rgwyh9rdvgk-perl-BerkeleyDB-0.26
     dr-xr-xr-x    2 eelco    users        4096 1970-01-01 01:00 lib
     ...
@@ -145,10 +111,10 @@ Parsing and evaluating Nix expressions:
 
     $ nix-instantiate --parse -E '1 + 2'
     1 + 2
-    
+
     $ nix-instantiate --eval -E '1 + 2'
     3
-    
+
     $ nix-instantiate --eval --xml -E '1 + 2'
     <?xml version='1.0' encoding='utf-8'?>
     <expr>
@@ -179,5 +145,3 @@ attempt to show non-normal forms).
         <string value="foo" />
       </attr>
     ...
-
-# Environment variables
diff --git a/doc/manual/src/command-ref/nix-prefetch-url.md b/doc/manual/src/command-ref/nix-prefetch-url.md
index f7de27402..688496969 100644
--- a/doc/manual/src/command-ref/nix-prefetch-url.md
+++ b/doc/manual/src/command-ref/nix-prefetch-url.md
@@ -1,32 +1,16 @@
-nix-prefetch-url
+Title: nix-prefetch-url
 
-1
+# Name
 
-Nix
+`nix-prefetch-url` - copy a file from a URL into the store and print its hash
 
-nix-prefetch-url
+# Synopsis
 
-copy a file from a URL into the store and print its hash
-
-nix-prefetch-url
-
-\--version
-
-\--type
-
-hashAlgo
-
-\--print-path
-
-\--unpack
-
-\--name
-
-name
-
-url
-
-hash
+`nix-prefetch-url` *url* [*hash*]
+  [`--type` *hashAlgo*]
+  [`--print-path`]
+  [`--unpack`]
+  [`--name` *name*]
 
 # Description
 
@@ -77,11 +61,11 @@ Nix store is also printed.
 
     $ nix-prefetch-url ftp://ftp.gnu.org/pub/gnu/hello/hello-2.10.tar.gz
     0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
-    
+
     $ nix-prefetch-url --print-path mirror://gnu/hello/hello-2.10.tar.gz
     0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
     /nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz
-    
+
     $ nix-prefetch-url --unpack --print-path https://github.com/NixOS/patchelf/archive/0.8.tar.gz
     079agjlv0hrv7fxnx9ngipx14gyncbkllxrp9cccnh3a50fxcmy7
     /nix/store/19zrmhm3m40xxaw81c8cqm6aljgrnwj2-0.8.tar.gz
diff --git a/doc/manual/src/command-ref/nix-shell.md b/doc/manual/src/command-ref/nix-shell.md
index 9e2b781ab..d6dbb6e26 100644
--- a/doc/manual/src/command-ref/nix-shell.md
+++ b/doc/manual/src/command-ref/nix-shell.md
@@ -1,60 +1,21 @@
-nix-shell
+Title: nix-shell
 
-1
+# Name
 
-Nix
+`nix-shell` - start an interactive shell based on a Nix expression
 
-nix-shell
+# Synopsis
 
-start an interactive shell based on a Nix expression
-
-nix-shell
-
-\--arg
-
-name
-
-value
-
-\--argstr
-
-name
-
-value
-
-\--attr
-
-\-A
-
-attrPath
-
-\--command
-
-cmd
-
-\--run
-
-cmd
-
-\--exclude
-
-regexp
-
-\--pure
-
-\--keep
-
-name
-
-\--packages
-
-\-p
-
-packages
-
-expressions
-
-path
+`nix-shell`
+  [`--arg` *name* *value*]
+  [`--argstr` *name* *value*]
+  [{`--attr` | `-A`} *attrPath*]
+  [`--command` *cmd*]
+  [`--run` *cmd*]
+  [`--exclude` *regexp*]
+  [--pure]
+  [--keep *name*]
+  {{`--packages` | `-p`} {*packages* | *expressions*} … | [*path*]}
 
 # Description
 
@@ -96,11 +57,10 @@ All options not listed here are passed to `nix-store
     This command is executed in an interactive shell. (Use `--run` to
     use a non-interactive shell instead.) However, a call to `exit` is
     implicitly added to the command, so the shell will exit after
-    running the command. To prevent this, add `return` at the end; e.g.
-    `--command
-                    "echo Hello; return"` will print `Hello` and then drop you into the
-    interactive shell. This can be useful for doing any additional
-    initialisation.
+    running the command. To prevent this, add `return` at the end;
+    e.g.  `--command "echo Hello; return"` will print `Hello` and then
+    drop you into the interactive shell. This can be useful for doing
+    any additional initialisation.
 
   - `--run` *cmd*  
     Like `--command`, but executes the command in a non-interactive
@@ -129,8 +89,7 @@ All options not listed here are passed to `nix-store
 
   - `-i` *interpreter*  
     The chained script interpreter to be invoked by `nix-shell`. Only
-    applicable in `#!`-scripts (described
-    [below](#ssec-nix-shell-shebang)).
+    applicable in `#!`-scripts (described below).
 
   - `--keep` *name*  
     When a `--pure` shell is started, keep the listed environment
@@ -186,7 +145,7 @@ gives you a shell containing the Pan package from a specific revision of
 Nixpkgs:
 
     $ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz
-    
+
     [nix-shell:~]$ pan --version
     Pan 0.139
 
@@ -213,9 +172,9 @@ For example, here is a Python script that depends on Python and the
 
     #! /usr/bin/env nix-shell
     #! nix-shell -i python -p python pythonPackages.prettytable
-    
+
     import prettytable
-    
+
     # Print a simple table.
     t = prettytable.PrettyTable(["N", "N^2"])
     for n in range(1, 10): t.add_row([n, n * n])
@@ -226,12 +185,12 @@ requires Perl and the `HTML::TokeParser::Simple` and `LWP` packages:
 
     #! /usr/bin/env nix-shell
     #! nix-shell -i perl -p perl perlPackages.HTMLTokeParserSimple perlPackages.LWP
-    
+
     use HTML::TokeParser::Simple;
-    
+
     # Fetch nixos.org and print all hrefs.
     my $p = HTML::TokeParser::Simple->new(url => 'http://nixos.org/');
-    
+
     while (my $token = $p->get_tag("a")) {
         my $href = $token->get_attr("href");
         print "$href\n" if $href;
@@ -242,11 +201,11 @@ package like Terraform:
 
     #! /usr/bin/env nix-shell
     #! nix-shell -i bash -p "terraform.withPlugins (plugins: [ plugins.openstack ])"
-    
+
     terraform apply
 
 > **Note**
-> 
+>
 > You must use double quotes (`"`) when passing a simple Nix expression
 > in a nix-shell shebang.
 
@@ -257,10 +216,10 @@ branch):
     #! /usr/bin/env nix-shell
     #! nix-shell -i runghc -p "haskellPackages.ghcWithPackages (ps: [ps.HTTP ps.tagsoup])"
     #! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-18.03.tar.gz
-    
+
     import Network.HTTP
     import Text.HTML.TagSoup
-    
+
     -- Fetch nixos.org and print all hrefs.
     main = do
       resp <- Network.HTTP.simpleHTTP (getRequest "http://nixos.org/")
@@ -285,7 +244,5 @@ where the file `deps.nix` in the same directory as the `#!`-script
 contains:
 
     with import <nixpkgs> {};
-    
-    runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
 
-# Environment variables
+    runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md
index a666de49b..a098beb1e 100644
--- a/doc/manual/src/command-ref/nix-store.md
+++ b/doc/manual/src/command-ref/nix-store.md
@@ -1,26 +1,15 @@
-nix-store
+Title: nix-store
 
-1
+# Name
 
-Nix
+`nix-store` - manipulate or query the Nix store
 
-nix-store
+# Synopsis
 
-manipulate or query the Nix store
-
-nix-store
-
-\--add-root
-
-path
-
-\--indirect
-
-operation
-
-options
-
-arguments
+`nix-store` *operation* [*options…*] [*arguments…*]
+  [`--option` *name* *value*]
+  [`--add-root` *path*]
+  [`--indirect`]
 
 # Description
 
@@ -44,7 +33,7 @@ options.
     which must be inside a directory that is scanned for roots by the
     garbage collector (i.e., typically in a subdirectory of
     `/nix/var/nix/gcroots/`) *unless* the `--indirect` flag is used.
-    
+
     If there are multiple results, then multiple symlinks will be
     created by sequentially numbering symlinks beyond the first one
     (e.g., `foo`, `foo-2`, `foo-3`, and so on).
@@ -55,24 +44,24 @@ options.
     commands such as `nix-build` that place a symlink to the build
     result in the current directory; such a build result should not be
     garbage-collected unless the symlink is removed.
-    
+
     The `--indirect` flag causes a uniquely named symlink to *path* to
     be stored in `/nix/var/nix/gcroots/auto/`. For instance,
-    
+
         $ nix-store --add-root /home/eelco/bla/result --indirect -r ...
-        
+
         $ ls -l /nix/var/nix/gcroots/auto
         lrwxrwxrwx    1 ... 2005-03-13 21:10 dn54lcypm8f8... -> /home/eelco/bla/result
-        
+
         $ ls -l /home/eelco/bla/result
         lrwxrwxrwx    1 ... 2005-03-13 21:10 /home/eelco/bla/result -> /nix/store/1r11343n6qd4...-f-spot-0.0.10
-    
+
     Thus, when `/home/eelco/bla/result` is removed, the GC root in the
     `auto` directory becomes a dangling symlink and will be ignored by
     the collector.
-    
+
     > **Warning**
-    > 
+    >
     > Note that it is not possible to move or rename indirect GC roots,
     > since the symlink in the `auto` directory will still point to the
     > old location.
@@ -83,15 +72,7 @@ options.
 
 ## Synopsis
 
-nix-store
-
-\--realise
-
-\-r
-
-paths
-
-\--dry-run
+`nix-store` {`--realise` | `-r`} *paths…* [`--dry-run`]
 
 ## Description
 
@@ -136,7 +117,7 @@ The following flags are available:
     output path is not identical to the corresponding output from the
     previous build, the new output path is left in
     `/nix/store/name.check.`
-    
+
     See also the `build-repeat` configuration option, which repeats a
     derivation a number of times and prevents its outputs from being
     registered as “valid” in the Nix store unless they are identical.
@@ -188,11 +169,7 @@ To test whether a previously-built derivation is deterministic:
 
 ## Synopsis
 
-nix-store
-
-\--serve
-
-\--write
+`nix-store` `--serve` [`--write`]
 
 ## Description
 
@@ -220,19 +197,7 @@ used to provide build access to a given SSH public key:
 
 ## Synopsis
 
-nix-store
-
-\--gc
-
-\--print-roots
-
-\--print-live
-
-\--print-dead
-
-\--max-freed
-
-bytes
+`nix-store` `--gc` [`--print-roots` | `--print-live` | `--print-dead`] [`--max-freed` *bytes*]
 
 ## Description
 
@@ -294,13 +259,7 @@ To delete at least 100 MiBs of unreachable paths:
 
 ## Synopsis
 
-nix-store
-
-\--delete
-
-\--ignore-liveness
-
-paths
+`nix-store` `--delete` [`--ignore-liveness`] *paths…*
 
 ## Description
 
@@ -324,55 +283,13 @@ paths in the store that refer to it (i.e., depend on it).
 
 ## Synopsis
 
-nix-store
-
-\--query
-
-\-q
-
-\--outputs
-
-\--requisites
-
-\-R
-
-\--references
-
-\--referrers
-
-\--referrers-closure
-
-\--deriver
-
-\-d
-
-\--graph
-
-\--tree
-
-\--binding
-
-name
-
-\-b
-
-name
-
-\--hash
-
-\--size
-
-\--roots
-
-\--use-output
-
-\-u
-
-\--force-realise
-
-\-f
-
-paths
+`nix-store` {`--query` | `-q`}
+  {`--outputs` | `--requisites` | `-R` | `--references` |
+  `--referrers` | `--referrers-closure` | `--deriver` | `-d` |
+  `--graph` | `--tree` | `--binding` *name* | `-b` *name* | `--hash` |
+  `--size` | `--roots`}
+  [`--use-output`] [`-u`] [`--force-realise`] [`-f`]
+  *paths…*
 
 ## Description
 
@@ -403,13 +320,13 @@ symlink.
 
   - `--requisites`; `-R`  
     Prints out the [closure](#gloss-closure) of the store path *paths*.
-    
+
     This query has one option:
-    
-      - `--include-outputs`  
+
+      - `--include-outputs`
         Also include the output path of store derivations, and their
         closures.
-    
+
     This query can be used to implement various kinds of deployment. A
     *source deployment* is obtained by distributing the closure of a
     store derivation. A *binary deployment* is obtained by distributing
@@ -555,11 +472,7 @@ depends on `svn`:
 
 ## Synopsis
 
-nix-store
-
-\--add
-
-paths
+`nix-store` `--add` *paths…*
 
 ## Description
 
@@ -575,15 +488,7 @@ prints the resulting paths in the Nix store on standard output.
 
 ## Synopsis
 
-nix-store
-
-\--recursive
-
-\--add-fixed
-
-algorithm
-
-paths
+`nix-store` `--add-fixed` [`--recursive`] *algorithm* *paths…*
 
 ## Description
 
@@ -608,13 +513,7 @@ This operation has the following options:
 
 ## Synopsis
 
-nix-store
-
-\--verify
-
-\--check-contents
-
-\--repair
+`nix-store` `--verify` [`--check-contents`] [`--repair`]
 
 ## Description
 
@@ -643,11 +542,7 @@ This operation has the following options:
 
 ## Synopsis
 
-nix-store
-
-\--verify-path
-
-paths
+`nix-store` `--verify-path` *paths…*
 
 ## Description
 
@@ -666,11 +561,7 @@ To verify the integrity of the `svn` command and all its dependencies:
 
 ## Synopsis
 
-nix-store
-
-\--repair-path
-
-paths
+`nix-store` `--repair-path` *paths…*
 
 ## Description
 
@@ -679,7 +570,7 @@ by redownloading them using the available substituters. If no
 substitutes are available, then repair is not possible.
 
 > **Warning**
-> 
+>
 > During repair, there is a very small time window during which the old
 > path (if it exists) is moved out of the way and replaced with the new
 > path. If repair is interrupted in between, then the system may be left
@@ -692,7 +583,7 @@ substitutes are available, then repair is not possible.
     path `/nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13' was modified!
       expected hash `2db57715ae90b7e31ff1f2ecb8c12ec1cc43da920efcbe3b22763f36a1861588',
       got `481c5aa5483ebc97c20457bb8bca24deea56550d3985cda0027f67fe54b808e4'
-    
+
     $ nix-store --repair-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13
     fetching path `/nix/store/d7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13'...
     …
@@ -701,11 +592,7 @@ substitutes are available, then repair is not possible.
 
 ## Synopsis
 
-nix-store
-
-\--dump
-
-path
+`nix-store` `--dump` *path*
 
 ## Description
 
@@ -739,11 +626,7 @@ A Nix archive can be unpacked using `nix-store
 
 ## Synopsis
 
-nix-store
-
-\--restore
-
-path
+`nix-store` `--restore` *path*
 
 ## Description
 
@@ -754,11 +637,7 @@ not already exist. The archive is read from standard input.
 
 ## Synopsis
 
-nix-store
-
-\--export
-
-paths
+`nix-store` `--export` *paths…*
 
 ## Description
 
@@ -784,9 +663,7 @@ To import the whole closure again, run:
 
 ## Synopsis
 
-nix-store
-
-\--import
+`nix-store` `--import`
 
 ## Description
 
@@ -800,9 +677,7 @@ Nix store, the import fails.
 
 ## Synopsis
 
-nix-store
-
-\--optimise
+`nix-store` `--optimise`
 
 ## Description
 
@@ -832,13 +707,7 @@ Use `-vv` or `-vvv` to get some progress indication.
 
 ## Synopsis
 
-nix-store
-
-\--read-log
-
-\-l
-
-paths
+`nix-store` {`--read-log` | `-l`} *paths…*
 
 ## Description
 
@@ -866,11 +735,7 @@ substitute, then the log is unavailable.
 
 ## Synopsis
 
-nix-store
-
-\--dump-db
-
-paths
+`nix-store` `--dump-db` [*paths…*]
 
 ## Description
 
@@ -889,9 +754,7 @@ example.
 
 ## Synopsis
 
-nix-store
-
-\--load-db
+`nix-store` `--load-db`
 
 ## Description
 
@@ -902,11 +765,7 @@ The operation `--load-db` reads a dump of the Nix database created by
 
 ## Synopsis
 
-nix-store
-
-\--print-env
-
-drvpath
+`nix-store` `--print-env` *drvpath*
 
 ## Description
 
@@ -927,15 +786,7 @@ of the builder are placed in the variable `_args`.
 
 ## Synopsis
 
-nix-store
-
-\--generate-binary-cache-key
-
-key-name
-
-secret-key-file
-
-public-key-file
+`nix-store` `--generate-binary-cache-key` *key-name* *secret-key-file* *public-key-file*
 
 ## Description
 
@@ -952,5 +803,3 @@ mandatory parameters:
 2.  The file name where the secret key is to be stored.
 
 3.  The file name where the public key is to be stored.
-
-# Environment variables