Convert commands

15 files changed, 2960 insertions, 4 deletions

diff --git a/doc/manual/src/SUMMARY.md b/doc/manual/src/SUMMARY.md
index e8baf489b..80a41f8d7 100644
--- a/doc/manual/src/SUMMARY.md
+++ b/doc/manual/src/SUMMARY.md
@@ -47,8 +47,19 @@
 - [Command Reference](command-ref/command-ref.md)
   - [Common Options](command-ref/opt-common.md)
   - [Common Environment Variables](command-ref/env-common.md)
+  - [Main Commands](command-ref/main-commands.md)
+    - [nix-env](command-ref/nix-env.md)
+    - [nix-build](command-ref/nix-build.md)
+    - [nix-shell](command-ref/nix-shell.md)
+    - [nix-store](command-ref/nix-store.md)
   - [Utilities](command-ref/utilities.md)
+    - [nix-channel](command-ref/nix-channel.md)
+    - [nix-collect-garbage](command-ref/nix-collect-garbage.md)
     - [nix-copy-closure](command-ref/nix-copy-closure.md)
+    - [nix-daemon](command-ref/nix-daemon.md)
+    - [nix-hash](command-ref/nix-hash.md)
+    - [nix-instantiate](command-ref/nix-instantiate.md)
+    - [nix-prefetch-url](command-ref/nix-prefetch-url.md)
   - [Files](command-ref/files.md)
     - [nix.conf](command-ref/conf-file.md)
 - [Glossary](glossary.md)
diff --git a/doc/manual/src/command-ref/command-ref.md b/doc/manual/src/command-ref/command-ref.md
index 2c7dbf22e..6a78075db 100644
--- a/doc/manual/src/command-ref/command-ref.md
+++ b/doc/manual/src/command-ref/command-ref.md
@@ -1,4 +1,2 @@
-# Command Reference
-
-This section lists commands and options that you can use when you
-work with Nix.
+This section lists commands and options that you can use when you work
+with Nix.
diff --git a/doc/manual/src/command-ref/main-commands.md b/doc/manual/src/command-ref/main-commands.md
new file mode 100644
index 000000000..e4f1f1d0e
--- /dev/null
+++ b/doc/manual/src/command-ref/main-commands.md
@@ -0,0 +1,4 @@
+# Main Commands
+
+This section lists commands and options that you can use when you work
+with Nix.
diff --git a/doc/manual/src/command-ref/nix-build.md b/doc/manual/src/command-ref/nix-build.md
new file mode 100644
index 000000000..7d0567760
--- /dev/null
+++ b/doc/manual/src/command-ref/nix-build.md
@@ -0,0 +1,130 @@
+nix-build
+
+1
+
+Nix
+
+nix-build
+
+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
+
+# Description
+
+The `nix-build` command builds the derivations described by the Nix
+expressions in paths. If the build succeeds, it places a symlink to the
+result in the current directory. The symlink is called `result`. If
+there are multiple Nix expressions, or the Nix expressions evaluate to
+multiple derivations, multiple sequentially numbered symlinks are
+created (`result`, `result-2`, and so on).
+
+If no paths are specified, then `nix-build` will use `default.nix` in
+the current directory, if it exists.
+
+If an element of paths 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 top-level
+directory containing at least a file named `default.nix`.
+
+`nix-build` is essentially a wrapper around
+[`nix-instantiate`](#sec-nix-instantiate) (to translate a high-level Nix
+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.
+
+# Options
+
+All options not listed here are passed to `nix-store
+--realise`, except for `--arg` and `--attr` / `-A` which are passed to
+`nix-instantiate`. See also [???](#sec-common-options).
+
+  - `--no-out-link`  
+    Do not create a symlink to the output path. Note that as a result
+    the output does not become a root of the garbage collector, and so
+    might be deleted by `nix-store
+                    --gc`.
+
+  - `--dry-run`  
+    Show what store paths would be built or downloaded.
+
+  - `--out-link` / `-o` outlink  
+    Change the name of the symlink to the output path created from
+    `result` to outlink.
+
+The following common options are supported:
+
+# Examples
+
+    $ 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
+
+If a derivation has multiple outputs, `nix-build` will build the default
+(first) output. You can also build all outputs:
+
+    $ nix-build '<nixpkgs>' -A openssl.all
+
+This will create a symlink for each output named `result-outputname`.
+The suffix is omitted if the output name is `out`. So if `openssl` has
+outputs `out`, `bin` and `man`, `nix-build` will create symlinks
+`result`, `result-bin` and `result-man`. It’s also possible to build a
+specific output:
+
+    $ nix-build '<nixpkgs>' -A openssl.man
+
+This will create a symlink `result-man`.
+
+Build a Nix expression given on the command line:
+
+    $ nix-build -E 'with import <nixpkgs> { }; runCommand "foo" { } "echo bar > $out"'
+    $ cat ./result
+    bar
+
+Build the GNU Hello package from the latest revision of the master
+branch of Nixpkgs:
+
+    $ nix-build https://github.com/NixOS/nixpkgs/archive/master.tar.gz -A hello
+
+# Environment variables
diff --git a/doc/manual/src/command-ref/nix-channel.md b/doc/manual/src/command-ref/nix-channel.md
new file mode 100644
index 000000000..d427151a0
--- /dev/null
+++ b/doc/manual/src/command-ref/nix-channel.md
@@ -0,0 +1,116 @@
+nix-channel
+
+1
+
+Nix
+
+nix-channel
+
+manage Nix channels
+
+nix-channel
+
+\--add
+
+url
+
+name
+
+\--remove
+
+name
+
+\--list
+
+\--update
+
+names
+
+\--rollback
+
+generation
+
+# Description
+
+A Nix channel is a mechanism that allows you to automatically stay
+up-to-date with a set of pre-built Nix expressions. A Nix channel is
+just a URL that points to a place containing a set of Nix expressions.
+See also [???](#sec-channels).
+
+To see the list of official NixOS channels, visit
+<https://nixos.org/channels>.
+
+This command has the following operations:
+
+  - `--add` url \[name\]  
+    Adds a channel named name with URL url to the list of subscribed
+    channels. If name is omitted, it defaults to the last component of
+    url, with the suffixes `-stable` or `-unstable` removed.
+
+  - `--remove` name  
+    Removes the channel named name from the list of subscribed channels.
+
+  - `--list`  
+    Prints the names and URLs of all subscribed channels on standard
+    output.
+
+  - `--update` \[names…\]  
+    Downloads the Nix expressions of all subscribed channels (or only
+    those included in names if specified) and makes them the default for
+    `nix-env` operations (by symlinking them from the directory
+    `~/.nix-defexpr`).
+
+  - `--rollback` \[generation\]  
+    Reverts the previous call to `nix-channel
+                    --update`. Optionally, you can specify a specific channel generation
+    number to restore.
+
+Note that `--add` does not automatically perform an update.
+
+The list of subscribed channels is stored in `~/.nix-channels`.
+
+# Examples
+
+To subscribe to the Nixpkgs channel and install the GNU Hello package:
+
+    $ nix-channel --add https://nixos.org/channels/nixpkgs-unstable
+    $ nix-channel --update
+    $ nix-env -iA nixpkgs.hello
+
+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"
+
+# Files
+
+  - `/nix/var/nix/profiles/per-user/username/channels`  
+    `nix-channel` uses a `nix-env` profile to keep track of previous
+    versions of the subscribed channels. Every time you run `nix-channel
+    --update`, a new channel generation (that is, a symlink to the
+    channel Nix expressions in the Nix store) is created. This enables
+    `nix-channel --rollback` to revert to previous versions.
+
+  - `~/.nix-defexpr/channels`  
+    This is a symlink to
+    `/nix/var/nix/profiles/per-user/username/channels`. It ensures that
+    `nix-env` can find your channels. In a multi-user installation, you
+    may also have `~/.nix-defexpr/channels_root`, which links to the
+    channels of the root user.
+
+# Channel format
+
+A channel URL should point to a directory containing the following
+files:
+
+  - `nixexprs.tar.xz`  
+    A tarball containing Nix expressions and files referenced by them
+    (such as build scripts and patches). At the top level, the tarball
+    should contain a single directory. That directory must contain a
+    file `default.nix` that serves as the channel’s “entry point”.
diff --git a/doc/manual/src/command-ref/nix-collect-garbage.md b/doc/manual/src/command-ref/nix-collect-garbage.md
new file mode 100644
index 000000000..7946dc875
--- /dev/null
+++ b/doc/manual/src/command-ref/nix-collect-garbage.md
@@ -0,0 +1,46 @@
+nix-collect-garbage
+
+1
+
+Nix
+
+nix-collect-garbage
+
+delete unreachable store paths
+
+nix-collect-garbage
+
+\--delete-old
+
+\-d
+
+\--delete-older-than
+
+period
+
+\--max-freed
+
+bytes
+
+\--dry-run
+
+# Description
+
+The command `nix-collect-garbage` is mostly an alias of [`nix-store
+--gc`](#rsec-nix-store-gc), that is, it deletes all unreachable paths in
+the Nix store to clean up your system. However, it provides two
+additional options: `-d` (`--delete-old`), which deletes all old
+generations of all profiles in `/nix/var/nix/profiles` by invoking
+`nix-env --delete-generations old` on all profiles (of course, this
+makes rollbacks to previous configurations impossible); and
+`--delete-older-than` period, where period is a value such as `30d`,
+which deletes all generations older than the specified number of days in
+all profiles in `/nix/var/nix/profiles` (except for the generations that
+were active at that point in time).
+
+# Example
+
+To delete from the Nix store everything that is not used by the current
+generations of each profile, do
+
+    $ nix-collect-garbage -d
diff --git a/doc/manual/src/command-ref/nix-daemon.md b/doc/manual/src/command-ref/nix-daemon.md
new file mode 100644
index 000000000..b0570789c
--- /dev/null
+++ b/doc/manual/src/command-ref/nix-daemon.md
@@ -0,0 +1,17 @@
+nix-daemon
+
+8
+
+Nix
+
+nix-daemon
+
+Nix multi-user support daemon
+
+nix-daemon
+
+# Description
+
+The Nix daemon is necessary in multi-user Nix installations. It performs
+build actions and other operations on the Nix store on behalf of
+unprivileged users.
diff --git a/doc/manual/src/command-ref/nix-env.md b/doc/manual/src/command-ref/nix-env.md
new file mode 100644
index 000000000..90bf6ea08
--- /dev/null
+++ b/doc/manual/src/command-ref/nix-env.md
@@ -0,0 +1,926 @@
+nix-env
+
+1
+
+Nix
+
+nix-env
+
+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
+
+# Description
+
+The command `nix-env` is used to manipulate Nix user environments. User
+environments are sets of software packages available to a user at some
+point in time. In other words, they are a synthesised view of the
+programs available in the Nix store. There may be many user
+environments: different users can have different environments, and
+individual users can switch between different environments.
+
+`nix-env` takes exactly one *operation* flag which indicates the
+subcommand to be performed. These are documented below.
+
+# Selectors
+
+Several commands, such as `nix-env -q` and `nix-env -i`, take a list of
+arguments that specify the packages on which to operate. These are
+extended regular expressions that must match the entire name of the
+package. (For details on regular expressions, see regex7.) The match is
+case-sensitive. The regular expression can optionally be followed by a
+dash and a version number; if omitted, any version of the package will
+match. Here are some examples:
+
+  - `firefox`  
+    Matches the package name `firefox` and any version.
+
+  - `firefox-32.0`  
+    Matches the package name `firefox` and version `32.0`.
+
+  - `gtk\\+`  
+    Matches the package name `gtk+`. The `+` character must be escaped
+    using a backslash to prevent it from being interpreted as a
+    quantifier, and the backslash must be escaped in turn with another
+    backslash to ensure that the shell passes it on.
+
+  - `.\*`  
+    Matches any package name. This is the default for most commands.
+
+  - `'.*zip.*'`  
+    Matches any package name containing the string `zip`. Note the dots:
+    `'*zip*'` does not work, because in a regular expression, the
+    character `*` is interpreted as a quantifier.
+
+  - `'.*(firefox|chromium).*'`  
+    Matches any package name containing the strings `firefox` or
+    `chromium`.
+
+# Common options
+
+This section lists the options that are common to all operations. These
+options are allowed for every subcommand, though they may not always
+have an effect. See also [???](#sec-common-options).
+
+  - `--file` / `-f` path  
+    Specifies the Nix expression (designated below as the *active Nix
+    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
+    top-level directory containing at least a file named `default.nix`.
+
+  - `--profile` / `-p` path  
+    Specifies the profile to be used by those operations that operate on
+    a profile (designated below as the *active profile*). A profile is a
+    sequence of user environments called *generations*, one of which is
+    the *current generation*.
+
+  - `--dry-run`  
+    For the `--install`, `--upgrade`, `--uninstall`,
+    `--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).
+
+  - `--system-filter` system  
+    By default, operations such as `--query
+                    --available` show derivations matching any platform. This option
+    allows you to use derivations for the specified platform system.
+
+<!-- end list -->
+
+# 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.
+    
+    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.
+
+  - `~/.nix-profile`  
+    A symbolic link to the user's current profile. By default, this
+    symlink points to `prefix/var/nix/profiles/default`. The `PATH`
+    environment variable should include `~/.nix-profile/bin` for the
+    user environment to be visible to the user.
+
+# Operation `--install`
+
+## Synopsis
+
+nix-env
+
+\--install
+
+\-i
+
+\--preserve-installed
+
+\-P
+
+\--remove-all
+
+\-r
+
+args
+
+## Description
+
+The install operation creates a new user environment, based on the
+current generation of the active profile, to which a set of store paths
+described by args is added. The arguments args map to store paths in a
+number of possible ways:
+
+  - By default, args is a set of derivation names denoting derivations
+    in the active Nix expression. These are realised, and the resulting
+    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
+    probably cause a user environment conflict\!).
+
+  - If [`--attr`](#opt-attr) (`-A`) is specified, the arguments are
+    *attribute paths* that select attributes from the top-level Nix
+    expression. This is faster than using derivation names and
+    unambiguous. To find out the attribute paths of available packages,
+    use `nix-env -qaP`.
+
+  - If `--from-profile` path is given, args is a set of names denoting
+    installed store paths in the profile path. This is an easy way to
+    copy user environment elements from one profile to another.
+
+  - If `--from-expression` is given, args are Nix
+    [functions](#ss-functions) that are called with the active Nix
+    expression as their single argument. The derivations returned by
+    those function calls are installed. This allows derivations to be
+    specified in an unambiguous way, which is necessary if there are
+    multiple derivations with the same name.
+
+  - If args are store derivations, then these are
+    [realised](#rsec-nix-store-realise), and the resulting output paths
+    are installed.
+
+  - If args are store paths that are not store derivations, then these
+    are [realised](#rsec-nix-store-realise) and installed.
+
+  - By default all outputs are installed for each derivation. That can
+    be reduced by setting `meta.outputsToInstall`.
+
+## Flags
+
+  - `--prebuilt-only` / `-b`  
+    Use only derivations for which a substitute is registered, i.e.,
+    there is a pre-built binary available that can be downloaded in lieu
+    of building the derivation. Thus, no packages will be built from
+    source.
+
+  - `--preserve-installed`; `-P`  
+    Do not remove derivations with a name matching one of the
+    derivations being installed. Usually, trying to have two versions of
+    the same package installed in the same generation of a profile will
+    lead to an error in building the generation, due to file name
+    clashes between the two versions. However, this is not the case for
+    all packages.
+
+  - `--remove-all`; `-r`  
+    Remove all previously installed packages first. This is equivalent
+    to running `nix-env -e '.*'` first, except that everything happens
+    in a single transaction.
+
+## Examples
+
+To install a specific version of `gcc` from the active Nix expression:
+
+    $ nix-env --install gcc-3.3.2
+    installing `gcc-3.3.2'
+    uninstalling `gcc-3.1'
+
+Note the previously installed version is removed, since
+`--preserve-installed` was not specified.
+
+To install an arbitrary version:
+
+    $ nix-env --install gcc
+    installing `gcc-3.3.2'
+
+To install using a specific attribute:
+
+    $ nix-env -i -A gcc40mips
+    $ nix-env -i -A xorg.xorgserver
+
+To install all derivations in the Nix expression `foo.nix`:
+
+    $ nix-env -f ~/foo.nix -i '.*'
+
+To copy the store path with symbolic name `gcc` from another profile:
+
+    $ nix-env -i --from-profile /nix/var/nix/profiles/foo gcc
+
+To install a specific store derivation (typically created by
+`nix-instantiate`):
+
+    $ nix-env -i /nix/store/fibjb1bfbpm5mrsxc4mh2d8n37sxh91i-gcc-3.4.3.drv
+
+To install a specific output path:
+
+    $ nix-env -i /nix/store/y3cgx0xj1p4iv9x0pnnmdhr8iyg741vk-gcc-3.4.3
+
+To install from a Nix expression specified on the command-line:
+
+    $ nix-env -f ./foo.nix -i -E \
+        'f: (f {system = "i686-linux";}).subversionWithJava'
+
+I.e., this evaluates to `(f: (f {system =
+"i686-linux";}).subversionWithJava) (import ./foo.nix)`, thus selecting
+the `subversionWithJava` attribute from the set returned by calling the
+function defined in `./foo.nix`.
+
+A dry-run tells you which paths will be downloaded or built from source:
+
+    $ nix-env -f '<nixpkgs>' -iA hello --dry-run
+    (dry run; not doing anything)
+    installing ‘hello-2.10’
+    this path will be fetched (0.04 MiB download, 0.19 MiB unpacked):
+      /nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10
+      ...
+
+To install Firefox from the latest revision in the Nixpkgs/NixOS 14.12
+channel:
+
+    $ nix-env -f https://github.com/NixOS/nixpkgs/archive/nixos-14.12.tar.gz -iA firefox
+
+# Operation `--upgrade`
+
+## Synopsis
+
+nix-env
+
+\--upgrade
+
+\-u
+
+\--lt
+
+\--leq
+
+\--eq
+
+\--always
+
+args
+
+## Description
+
+The upgrade operation creates a new user environment, based on the
+current generation of the active profile, in which all store paths are
+replaced for which there are newer versions in the set of paths
+described by args. Paths for which there are no newer versions are left
+untouched; this is not an error. It is also not an error if an element
+of args matches no installed derivations.
+
+For a description of how args is mapped to a set of store paths, see
+[`--install`](#rsec-nix-env-install). If args describes multiple store
+paths with the same symbolic name, only the one with the highest version
+is installed.
+
+## Flags
+
+  - `--lt`  
+    Only upgrade a derivation to newer versions. This is the default.
+
+  - `--leq`  
+    In addition to upgrading to newer versions, also “upgrade” to
+    derivations that have the same version. Version are not a unique
+    identification of a derivation, so there may be many derivations
+    that have the same version. This flag may be useful to force
+    “synchronisation” between the installed and available derivations.
+
+  - `--eq`  
+    *Only* “upgrade” to derivations that have the same version. This may
+    not seem very useful, but it actually is, e.g., when there is a new
+    release of Nixpkgs and you want to replace installed applications
+    with the same versions built against newer dependencies (to reduce
+    the number of dependencies floating around on your system).
+
+  - `--always`  
+    In addition to upgrading to newer versions, also “upgrade” to
+    derivations that have the same or a lower version. I.e., derivations
+    may actually be downgraded depending on what is available in the
+    active Nix expression.
+
+For the other flags, see `--install`.
+
+## Examples
+
+    $ 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'
+
+## Versions
+
+The upgrade operation determines whether a derivation `y` is an upgrade
+of a derivation `x` by looking at their respective `name` attributes.
+The names (e.g., `gcc-3.3.1` are split into two parts: the package name
+(`gcc`), and the version (`3.3.1`). The version part starts after the
+first dash not followed by a letter. `x` is considered an upgrade of `y`
+if their package names match, and the version of `y` is higher that that
+of `x`.
+
+The versions are compared by splitting them into contiguous components
+of numbers and letters. E.g., `3.3.1pre5` is split into `[3, 3, 1,
+"pre", 5]`. These lists are then compared lexicographically (from left
+to right). Corresponding components `a` and `b` are compared as follows.
+If they are both numbers, integer comparison is used. If `a` is an empty
+string and `b` is a number, `a` is considered less than `b`. The special
+string component `pre` (for *pre-release*) is considered to be less than
+other components. String components are considered less than number
+components. Otherwise, they are compared lexicographically (i.e., using
+case-sensitive string comparison).
+
+This is illustrated by the following examples:
+
+    1.0 < 2.3
+    2.1 < 2.3
+    2.3 = 2.3
+    2.5 > 2.3
+    3.1 > 2.3
+    2.3.1 > 2.3
+    2.3.1 > 2.3a
+    2.3pre1 < 2.3
+    2.3pre3 < 2.3pre12
+    2.3a < 2.3c
+    2.3pre1 < 2.3c
+    2.3pre1 < 2.3q
+
+# Operation `--uninstall`
+
+## Synopsis
+
+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.
+
+## Examples
+
+    $ nix-env --uninstall gcc
+    $ nix-env -e '.*' (remove everything)
+
+# Operation `--set`
+
+## Synopsis
+
+nix-env
+
+\--set
+
+drvname
+
+## Description
+
+The `--set` operation modifies the current generation of a profile so
+that it contains exactly the specified derivation, and nothing else.
+
+## Examples
+
+The following updates a profile such that its current generation will
+contain just Firefox:
+
+    $ nix-env -p /nix/var/nix/profiles/browser --set firefox
+
+# Operation `--set-flag`
+
+## Synopsis
+
+nix-env
+
+\--set-flag
+
+name
+
+value
+
+drvnames
+
+## Description
+
+The `--set-flag` operation allows meta attributes of installed packages
+to be modified. There are several attributes that can be usefully
+modified, because they affect the behaviour of `nix-env` or the user
+environment build script:
+
+  - `priority` can be changed to resolve filename clashes. The user
+    environment build script uses the `meta.priority` attribute of
+    derivations to resolve filename collisions between packages. Lower
+    priority values denote a higher priority. For instance, the GCC
+    wrapper package and the Binutils package in Nixpkgs both have a file
+    `bin/ld`, so previously if you tried to install both you would get a
+    collision. Now, on the other hand, the GCC wrapper declares a higher
+    priority than Binutils, so the former’s `bin/ld` is symlinked in the
+    user environment.
+
+  - `keep` can be set to `true` to prevent the package from being
+    upgraded or replaced. This is useful if you want to hang on to an
+    older version of a package.
+
+  - `active` can be set to `false` to “disable” the package. That is, no
+    symlinks will be generated to the files of the package, but it
+    remains part of the profile (so it won’t be garbage-collected). It
+    can be set back to `true` to re-enable the package.
+
+## Examples
+
+To prevent the currently installed Firefox from being upgraded:
+
+    $ nix-env --set-flag keep true firefox
+
+After this, `nix-env -u` will ignore Firefox.
+
+To disable the currently installed Firefox, then install a new Firefox
+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)
+
+To make files from `binutils` take precedence over files from `gcc`:
+
+    $ nix-env --set-flag priority 5 binutils
+    $ nix-env --set-flag priority 10 gcc
+
+# Operation `--query`
+
+## 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
+
+## Description
+
+The query operation displays information about either the store paths
+that are installed in the current generation of the active profile
+(`--installed`), or the derivations that are available for installation
+in the active Nix expression (`--available`). It only prints information
+about derivations whose symbolic name matches one of names.
+
+The derivations are sorted by their `name` attributes.
+
+## Source selection
+
+The following flags specify the set of things on which the query
+operates.
+
+  - `--installed`  
+    The query operates on the store paths that are installed in the
+    current generation of the active profile. This is the default.
+
+  - `--available`; `-a`  
+    The query operates on the derivations that are available in the
+    active Nix expression.
+
+## Queries
+
+The following flags specify what information to display about the
+selected derivations. Multiple flags may be specified, in which case the
+information is shown in the order given here. Note that the name of the
+derivation is shown unless `--no-name` is specified.
+
+  - `--xml`  
+    Print the result in an XML representation suitable for automatic
+    processing by other tools. The root element is called `items`, which
+    contains a `item` element for each available or installed
+    derivation. The fields discussed below are all stored in attributes
+    of the `item` elements.
+
+  - `--json`  
+    Print the result in a JSON representation suitable for automatic
+    processing by other tools.
+
+  - `--prebuilt-only` / `-b`  
+    Show only derivations for which a substitute is registered, i.e.,
+    there is a pre-built binary available that can be downloaded in lieu
+    of building the derivation. Thus, this shows all packages that
+    probably can be installed quickly.
+
+  - `--status`; `-s`  
+    Print the *status* of the derivation. The status consists of three
+    characters. The first is `I` or `-`, indicating whether the
+    derivation is currently installed in the current generation of the
+    active profile. This is by definition the case for `--installed`,
+    but not for `--available`. The second is `P` or `-`, indicating
+    whether the derivation is present on the system. This indicates
+    whether installation of an available derivation will require the
+    derivation to be built. The third is `S` or `-`, indicating whether
+    a substitute is available for the derivation.
+
+  - `--attr-path`; `-P`  
+    Print the *attribute path* of the derivation, which can be used to
+    unambiguously select it using the [`--attr` option](#opt-attr)
+    available in commands that install derivations like `nix-env
+    --install`. This option only works together with `--available`
+
+  - `--no-name`  
+    Suppress printing of the `name` attribute of each derivation.
+
+  - `--compare-versions` / `-c`  
+    Compare installed versions to available versions, or vice versa (if
+    `--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.
+
+  - `--system`  
+    Print the `system` attribute of the derivation.
+
+  - `--drv-path`  
+    Print the path of the store derivation.
+
+  - `--out-path`  
+    Print the output path of the derivation.
+
+  - `--description`  
+    Print a short (one-line) description of the derivation, if
+    available. The description is taken from the `meta.description`
+    attribute of the derivation.
+
+  - `--meta`  
+    Print all of the meta-attributes of the derivation. This option is
+    only available with `--xml` or `--json`.
+
+## Examples
+
+To show installed packages:
+
+    $ nix-env -q
+    bison-1.875c
+    docbook-xml-4.2
+    firefox-1.0.4
+    MPlayer-1.0pre7
+    ORBit2-2.8.3
+    …
+
+To show available packages:
+
+    $ nix-env -qa
+    firefox-1.0.7
+    GConf-2.4.0.1
+    MPlayer-1.0pre7
+    ORBit2-2.8.3
+    …
+
+To show the status of available packages:
+
+    $ nix-env -qas
+    -P- firefox-1.0.7   (not installed but present)
+    --S GConf-2.4.0.1   (not present, but there is a substitute for fast installation)
+    --S MPlayer-1.0pre3 (i.e., this is not the installed MPlayer, even though the version is the same!)
+    IP- ORBit2-2.8.3    (installed and by definition present)
+    …
+
+To show available packages in the Nix expression `foo.nix`:
+
+    $ nix-env -f ./foo.nix -qa
+    foo-1.2.3
+
+To compare installed versions to what’s available:
+
+    $ nix-env -qc
+    ...
+    acrobat-reader-7.0 - ?      (package is not available at all)
+    autoconf-2.59      = 2.59   (same version)
+    firefox-1.0.4      < 1.0.7  (a more recent version is available)
+    ...
+
+To show all packages with “`zip`” in the name:
+
+    $ nix-env -qa '.*zip.*'
+    bzip2-1.0.6
+    gzip-1.6
+    zip-3.0
+    …
+
+To show all packages with “`firefox`” or “`chromium`” in the name:
+
+    $ nix-env -qa '.*(firefox|chromium).*'
+    chromium-37.0.2062.94
+    chromium-beta-38.0.2125.24
+    firefox-32.0.3
+    firefox-with-plugins-13.0.1
+    …
+
+To show all packages in the latest revision of the Nixpkgs repository:
+
+    $ nix-env -f https://github.com/NixOS/nixpkgs/archive/master.tar.gz -qa
+
+# Operation `--switch-profile`
+
+## Synopsis
+
+nix-env
+
+\--switch-profile
+
+\-S
+
+path
+
+## Description
+
+This operation makes path the current profile for the user. That is, the
+symlink `~/.nix-profile` is made to point to path.
+
+## Examples
+
+    $ nix-env -S ~/my-profile
+
+# Operation `--list-generations`
+
+## Synopsis
+
+nix-env
+
+\--list-generations
+
+## Description
+
+This operation print a list of all the currently existing generations
+for the active profile. These may be switched to using the
+`--switch-generation` operation. It also prints the creation date of the
+generation, and indicates the current generation.
+
+## Examples
+
+    $ nix-env --list-generations
+      95   2004-02-06 11:48:24
+      96   2004-02-06 11:49:01
+      97   2004-02-06 16:22:45
+      98   2004-02-06 16:24:33   (current)
+
+# Operation `--delete-generations`
+
+## Synopsis
+
+nix-env
+
+\--delete-generations
+
+generations
+
+## Description
+
+This operation deletes the specified generations of the current profile.
+The generations can be a list of generation numbers, the special value
+`old` to delete all non-current generations, a value such as `30d` to
+delete all generations older than the specified number of days (except
+for the generation that was active at that point in time), or a value
+such as `+5` to keep the last `5` generations ignoring any newer than
+current, e.g., if `30` is the current generation `+5` will delete
+generation `25` and all older generations. Periodically deleting old
+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
+
+## Description
+
+This operation makes generation number generation the current generation
+of the active profile. That is, if the `profile` is the path to the
+active profile, then the symlink `profile` is made to point to
+`profile-generation-link`, which is in turn a symlink to the actual user
+environment in the Nix store.
+
+Switching will fail if the specified generation does not exist.
+
+## Examples
+
+    $ nix-env -G 42
+    switching from generation 50 to 42
+
+# Operation `--rollback`
+
+## Synopsis
+
+nix-env
+
+\--rollback
+
+## Description
+
+This operation switches to the “previous” generation of the active
+profile, that is, the highest numbered generation lower than the current
+generation, if it exists. It is just a convenience wrapper around
+`--list-generations` and `--switch-generation`.
+
+## Examples
+
+    $ nix-env --rollback
+    switching from generation 92 to 91
+    
+    $ nix-env --rollback
+    error: no generation older than the current (91) exists
+
+# Environment variables
+
+  - `NIX_PROFILE`  
+    Location of the Nix profile. Defaults to the target of the symlink
+    `~/.nix-profile`, if it exists, or `/nix/var/nix/profiles/default`
+    otherwise.
diff --git a/doc/manual/src/command-ref/nix-hash.md b/doc/manual/src/command-ref/nix-hash.md
new file mode 100644
index 000000000..d433cbc5b
--- /dev/null
+++ b/doc/manual/src/command-ref/nix-hash.md
@@ -0,0 +1,120 @@
+nix-hash
+
+1
+
+Nix
+
+nix-hash
+
+compute the cryptographic hash of a path
+
+nix-hash
+
+\--flat
+
+\--base32
+
+\--truncate
+
+\--type
+
+hashAlgo
+
+path
+
+nix-hash
+
+\--to-base16
+
+hash
+
+nix-hash
+
+\--to-base32
+
+hash
+
+# Description
+
+The command `nix-hash` computes the cryptographic hash of the contents
+of each path and prints it on standard output. By default, it computes
+an MD5 hash, but other hash algorithms are available as well. The hash
+is printed in hexadecimal. To generate the same hash as
+`nix-prefetch-url` you have to specify multiple arguments, see below for
+an example.
+
+The hash is computed over a *serialisation* of each path: a dump of the
+file system tree rooted at the path. This allows directories and
+symlinks to be hashed as well as regular files. The dump is in the *NAR
+format* produced by [`nix-store` `--dump`](#refsec-nix-store-dump).
+Thus, `nix-hash
+path` yields the same cryptographic hash as `nix-store --dump
+path | md5sum`.
+
+# Options
+
+  - `--flat`  
+    Print the cryptographic hash of the contents of each regular file
+    path. That is, do not compute the hash over the dump of path. The
+    result is identical to that produced by the GNU commands `md5sum`
+    and `sha1sum`.
+
+  - `--base32`  
+    Print the hash in a base-32 representation rather than hexadecimal.
+    This base-32 representation is more compact and can be used in Nix
+    expressions (such as in calls to `fetchurl`).
+
+  - `--truncate`  
+    Truncate hashes longer than 160 bits (such as SHA-256) to 160 bits.
+
+  - `--type` hashAlgo  
+    Use the specified cryptographic hash algorithm, which can be one of
+    `md5`, `sha1`, and `sha256`.
+
+  - `--to-base16`  
+    Don’t hash anything, but convert the base-32 hash representation
+    hash to hexadecimal.
+
+  - `--to-base32`  
+    Don’t hash anything, but convert the hexadecimal hash representation
+    hash to base-32.
+
+# Examples
+
+Computing the same hash as `nix-prefetch-url`:
+
+    $ nix-prefetch-url file://<(echo test)
+    1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj
+    $ nix-hash --type sha256 --flat --base32 <(echo test)
+    1lkgqb6fclns49861dwk9rzb6xnfkxbpws74mxnx01z9qyv1pjpj
+
+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
+
+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
new file mode 100644
index 000000000..449f5f70f
--- /dev/null
+++ b/doc/manual/src/command-ref/nix-instantiate.md
@@ -0,0 +1,184 @@
+nix-instantiate
+
+1
+
+Nix
+
+nix-instantiate
+
+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
+
+\--find-file
+
+files
+
+# Description
+
+The command `nix-instantiate` generates [store
+derivations](#gloss-derivation) from (high-level) Nix expressions. It
+evaluates the Nix expressions in each of files (which defaults to
+./default.nix). Each top-level expression should evaluate to a
+derivation, a list of derivations, or a set of derivations. The paths of
+the resulting store derivations are printed on standard output.
+
+If files is the character `-`, then a Nix expression will be read from
+standard input.
+
+See also [???](#sec-common-options) for a list of common options.
+
+# Options
+
+  - `--add-root` path; `--indirect`  
+    See the [corresponding options](#opt-add-root) in `nix-store`.
+
+  - `--parse`  
+    Just parse the input files, and print their abstract syntax trees on
+    standard output in ATerm format.
+
+  - `--eval`  
+    Just parse and evaluate the input files, and print the resulting
+    values on standard output. No instantiation of store derivations
+    takes place.
+
+  - `--find-file`  
+    Look up the given files in Nix’s search path (as specified by the
+    NIX\_PATH\</literal\> environment variable). If found, print the
+    corresponding absolute paths on standard output. For instance, if
+    `NIX_PATH` is `nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate
+    --find-file nixpkgs/default.nix` will print
+    `/home/alice/nixpkgs/default.nix`.
+
+  - `--strict`  
+    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.
+
+  - `--json`  
+    When used with `--eval`, print the resulting value as an JSON
+    representation of the abstract syntax tree rather than as an ATerm.
+
+  - `--xml`  
+    When used with `--eval`, 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 [`toXML`
+    built-in](#builtin-toXML).
+
+  - `--read-write-mode`  
+    When used with `--eval`, perform evaluation in read/write mode so
+    nix language features that require it will still work (at the cost
+    of needing to do instantiation of every evaluated derivation). If
+    this option is not enabled, there may be uninstantiated store paths
+    in the final output.
+
+<!-- end list -->
+
+# Examples
+
+Instantiating store derivations from a Nix expression, and building them
+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
+    ...
+
+You can also give a Nix expression on the command line:
+
+    $ nix-instantiate -E 'with import <nixpkgs> { }; hello'
+    /nix/store/j8s4zyv75a724q38cb0r87rlczaiag4y-hello-2.8.drv
+
+This is equivalent to:
+
+    $ nix-instantiate '<nixpkgs>' -A hello
+
+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>
+      <int value="3" />
+    </expr>
+
+The difference between non-strict and strict evaluation:
+
+    $ nix-instantiate --eval --xml -E 'rec { x = "foo"; y = x; }'
+    ...
+      <attr name="x">
+        <string value="foo" />
+      </attr>
+      <attr name="y">
+        <unevaluated />
+      </attr>
+    ...
+
+Note that `y` is left unevaluated (the XML representation doesn’t
+attempt to show non-normal forms).
+
+    $ nix-instantiate --eval --xml --strict -E 'rec { x = "foo"; y = x; }'
+    ...
+      <attr name="x">
+        <string value="foo" />
+      </attr>
+      <attr name="y">
+        <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
new file mode 100644
index 000000000..bf8084e45
--- /dev/null
+++ b/doc/manual/src/command-ref/nix-prefetch-url.md
@@ -0,0 +1,87 @@
+nix-prefetch-url
+
+1
+
+Nix
+
+nix-prefetch-url
+
+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
+
+# Description
+
+The command `nix-prefetch-url` downloads the file referenced by the URL
+url, prints its cryptographic hash, and copies it into the Nix store.
+The file name in the store is `hash-baseName`, where baseName is
+everything following the final slash in url.
+
+This command is just a convenience for Nix expression writers. Often a
+Nix expression fetches some source distribution from the network using
+the `fetchurl` expression contained in Nixpkgs. However, `fetchurl`
+requires a cryptographic hash. If you don't know the hash, you would
+have to download the file first, and then `fetchurl` would download it
+again when you build your Nix expression. Since `fetchurl` uses the same
+name for the downloaded file as `nix-prefetch-url`, the redundant
+download can be avoided.
+
+If hash 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 is signaled if the actual hash of the
+file does not match the specified hash.
+
+This command prints the hash on standard output. Additionally, if the
+option `--print-path` is used, the path of the downloaded file in the
+Nix store is also printed.
+
+# Options
+
+  - `--type` hashAlgo  
+    Use the specified cryptographic hash algorithm, which can be one of
+    `md5`, `sha1`, and `sha256`.
+
+  - `--print-path`  
+    Print the store path of the downloaded file on standard output.
+
+  - `--unpack`  
+    Unpack the archive (which must be a tarball or zip file) and add the
+    result to the Nix store. The resulting hash can be used with
+    functions such as Nixpkgs’s `fetchzip` or `fetchFromGitHub`.
+
+  - `--name` name  
+    Override the name of the file in the Nix store. By default, this is
+    `hash-basename`, where basename is the last component of url.
+    Overriding the name is necessary when basename contains characters
+    that are not allowed in Nix store paths.
+
+# Examples
+
+    $ 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
new file mode 100644
index 000000000..c6910e3f5
--- /dev/null
+++ b/doc/manual/src/command-ref/nix-shell.md
@@ -0,0 +1,291 @@
+nix-shell
+
+1
+
+Nix
+
+nix-shell
+
+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
+
+# Description
+
+The command `nix-shell` will build the dependencies of the specified
+derivation, but not the derivation itself. It will then start an
+interactive shell in which all environment variables defined by the
+derivation path have been set to their corresponding values, and the
+script `$stdenv/setup` has been sourced. This is useful for reproducing
+the environment of a derivation for development.
+
+If path is not given, `nix-shell` defaults to `shell.nix` if it exists,
+and `default.nix` otherwise.
+
+If path 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 top-level directory
+containing at least a file named `default.nix`.
+
+If the derivation defines the variable `shellHook`, it will be evaluated
+after `$stdenv/setup` has been sourced. Since this hook is not executed
+by regular Nix builds, it allows you to perform initialisation specific
+to `nix-shell`. For example, the derivation attribute
+
+    shellHook =
+      ''
+        echo "Hello shell"
+      '';
+
+will cause `nix-shell` to print `Hello shell`.
+
+# Options
+
+All options not listed here are passed to `nix-store
+--realise`, except for `--arg` and `--attr` / `-A` which are passed to
+`nix-instantiate`. See also [???](#sec-common-options).
+
+  - `--command` cmd  
+    In the environment of the derivation, run the shell command cmd.
+    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.
+
+  - `--run` cmd  
+    Like `--command`, but executes the command in a non-interactive
+    shell. This means (among other things) that if you hit Ctrl-C while
+    the command is running, the shell exits.
+
+  - `--exclude` regexp  
+    Do not build any dependencies whose store path matches the regular
+    expression regexp. This option may be specified multiple times.
+
+  - `--pure`  
+    If this flag is specified, the environment is almost entirely
+    cleared before the interactive shell is started, so you get an
+    environment that more closely corresponds to the “real” Nix build. A
+    few variables, in particular `HOME`, `USER` and `DISPLAY`, are
+    retained. Note that `~/.bashrc` and (depending on your Bash
+    installation) `/etc/bashrc` are still sourced, so any variables set
+    there will affect the interactive shell.
+
+  - `--packages` / `-p` packages…  
+    Set up an environment in which the specified packages are present.
+    The command line arguments are interpreted as attribute names inside
+    the Nix Packages collection. Thus, `nix-shell -p libjpeg openjdk`
+    will start a shell in which the packages denoted by the attribute
+    names `libjpeg` and `openjdk` are present.
+
+  - `-i` interpreter  
+    The chained script interpreter to be invoked by `nix-shell`. Only
+    applicable in `#!`-scripts (described
+    [below](#ssec-nix-shell-shebang)).
+
+  - `--keep` name  
+    When a `--pure` shell is started, keep the listed environment
+    variables.
+
+The following common options are supported:
+
+# Environment variables
+
+  - `NIX_BUILD_SHELL`  
+    Shell used to start the interactive environment. Defaults to the
+    `bash` found in `PATH`.
+
+# Examples
+
+To build the dependencies of the package Pan, and start an interactive
+shell in which to build it:
+
+    $ nix-shell '<nixpkgs>' -A pan
+    [nix-shell]$ unpackPhase
+    [nix-shell]$ cd pan-*
+    [nix-shell]$ configurePhase
+    [nix-shell]$ buildPhase
+    [nix-shell]$ ./pan/gui/pan
+
+To clear the environment first, and do some additional automatic
+initialisation of the interactive shell:
+
+    $ nix-shell '<nixpkgs>' -A pan --pure \
+        --command 'export NIX_DEBUG=1; export NIX_CORES=8; return'
+
+Nix expressions can also be given on the command line using the `-E` and
+`-p` flags. For instance, the following starts a shell containing the
+packages `sqlite` and `libX11`:
+
+    $ nix-shell -E 'with import <nixpkgs> { }; runCommand "dummy" { buildInputs = [ sqlite xorg.libX11 ]; } ""'
+
+A shorter way to do the same is:
+
+    $ nix-shell -p sqlite xorg.libX11
+    [nix-shell]$ echo $NIX_LDFLAGS
+    … -L/nix/store/j1zg5v…-sqlite-3.8.0.2/lib -L/nix/store/0gmcz9…-libX11-1.6.1/lib …
+
+Note that `-p` accepts multiple full nix expressions that are valid in
+the `buildInputs = [ ... ]` shown above, not only package names. So the
+following is also legal:
+
+    $ nix-shell -p sqlite 'git.override { withManual = false; }'
+
+The `-p` flag looks up Nixpkgs in the Nix search path. You can override
+it by passing `-I` or setting `NIX_PATH`. For example, the following
+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
+
+# Use as a `#!`-interpreter
+
+You can use `nix-shell` as a script interpreter to allow scripts written
+in arbitrary languages to obtain their own dependencies via Nix. This is
+done by starting the script with the following lines:
+
+    #! /usr/bin/env nix-shell
+    #! nix-shell -i real-interpreter -p packages
+
+where real-interpreter is the “real” script interpreter that will be
+invoked by `nix-shell` after it has obtained the dependencies and
+initialised the environment, and packages are the attribute names of the
+dependencies in Nixpkgs.
+
+The lines starting with `#! nix-shell` specify `nix-shell` options (see
+above). Note that you cannot write `#! /usr/bin/env nix-shell -i ...`
+because many operating systems only allow one argument in `#!` lines.
+
+For example, here is a Python script that depends on Python and the
+`prettytable` package:
+
+    #! /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])
+    print t
+
+Similarly, the following is a Perl script that specifies that it
+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;
+    }
+
+Sometimes you need to pass a simple Nix expression to customize a
+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.
+
+Finally, using the merging of multiple nix-shell shebangs the following
+Haskell script uses a specific branch of Nixpkgs/NixOS (the 18.03 stable
+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/")
+      body <- getResponseBody resp
+      let tags = filter (isTagOpenName "a") $ parseTags body
+      let tags' = map (fromAttrib "href") tags
+      mapM_ putStrLn $ filter (/= "") tags'
+
+If you want to be even more precise, you can specify a specific revision
+of Nixpkgs:
+
+    #! nix-shell -I nixpkgs=https://github.com/NixOS/nixpkgs/archive/0672315759b3e15e2121365f067c1c8c56bb4722.tar.gz
+
+The examples above all used `-p` to get dependencies from Nixpkgs. You
+can also use a Nix expression to build your own dependencies. For
+example, the Python example could have been written as:
+
+    #! /usr/bin/env nix-shell
+    #! nix-shell deps.nix -i python
+
+where the file `deps.nix` in the same directory as the `#!`-script
+contains:
+
+    with import <nixpkgs> {};
+    
+    runCommand "dummy" { buildInputs = [ python pythonPackages.prettytable ]; } ""
+
+# Environment variables
diff --git a/doc/manual/src/command-ref/nix-store.md b/doc/manual/src/command-ref/nix-store.md
new file mode 100644
index 000000000..703e71076
--- /dev/null
+++ b/doc/manual/src/command-ref/nix-store.md
@@ -0,0 +1,954 @@
+nix-store
+
+1
+
+Nix
+
+nix-store
+
+manipulate or query the Nix store
+
+nix-store
+
+\--add-root
+
+path
+
+\--indirect
+
+operation
+
+options
+
+arguments
+
+# Description
+
+The command `nix-store` performs primitive operations on the Nix store.
+You generally do not need to run this command manually.
+
+`nix-store` takes exactly one *operation* flag which indicates the
+subcommand to be performed. These are documented below.
+
+# Common options
+
+This section lists the options that are common to all operations. These
+options are allowed for every subcommand, though they may not always
+have an effect. See also [???](#sec-common-options) for a list of common
+options.
+
+  - `--add-root` path  
+    Causes the result of a realisation (`--realise` and
+    `--force-realise`) to be registered as a root of the garbage
+    collector(see [???](#ssec-gc-roots)). The root is stored in path,
+    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).
+
+  - `--indirect`  
+    In conjunction with `--add-root`, this option allows roots to be
+    stored *outside* of the GC roots directory. This is useful for
+    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.
+
+<!-- end list -->
+
+# Operation `--realise`
+
+## Synopsis
+
+nix-store
+
+\--realise
+
+\-r
+
+paths
+
+\--dry-run
+
+## Description
+
+The operation `--realise` essentially “builds” the specified store
+paths. Realisation is a somewhat overloaded term:
+
+  - If the store path is a *derivation*, realisation ensures that the
+    output paths of the derivation are [valid](#gloss-validity) (i.e.,
+    the output path and its closure exist in the file system). This can
+    be done in several ways. First, it is possible that the outputs are
+    already valid, in which case we are done immediately. Otherwise,
+    there may be [substitutes](#gloss-substitute) that produce the
+    outputs (e.g., by downloading them). Finally, the outputs can be
+    produced by performing the build action described by the derivation.
+
+  - If the store path is not a derivation, realisation ensures that the
+    specified path is valid (i.e., it and its closure exist in the file
+    system). If the path is already valid, we are done immediately.
+    Otherwise, the path and any missing paths in its closure may be
+    produced through substitutes. If there are no (successful)
+    subsitutes, realisation fails.
+
+The output path of each derivation is printed on standard output. (For
+non-derivations argument, the argument itself is printed.)
+
+The following flags are available:
+
+  - `--dry-run`  
+    Print on standard error a description of what packages would be
+    built or downloaded, without actually performing the operation.
+
+  - `--ignore-unknown`  
+    If a non-derivation path does not have a substitute, then silently
+    ignore it.
+
+  - `--check`  
+    This option allows you to check whether a derivation is
+    deterministic. It rebuilds the specified derivation and checks
+    whether the result is bitwise-identical with the existing outputs,
+    printing an error if that’s not the case. The outputs of the
+    specified derivation must already exist. When used with `-K`, if an
+    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.
+
+Special exit codes:
+
+  - `100`  
+    Generic build failure, the builder process returned with a non-zero
+    exit code.
+
+  - `101`  
+    Build timeout, the build was aborted because it did not complete
+    within the specified [`timeout`](#conf-timeout).
+
+  - `102`  
+    Hash mismatch, the build output was rejected because it does not
+    match the specified [`outputHash`](#fixed-output-drvs).
+
+  - `104`  
+    Not deterministic, the build succeeded in check mode but the
+    resulting output is not binary reproducable.
+
+With the `--keep-going` flag it's possible for multiple failures to
+occur, in this case the 1xx status codes are or combined using binary
+or.
+
+    1100100
+       ^^^^
+       |||`- timeout
+       ||`-- output hash mismatch
+       |`--- build failure
+       `---- not deterministic
+
+## Examples
+
+This operation is typically used to build store derivations produced by
+[`nix-instantiate`](#sec-nix-instantiate):
+
+    $ nix-store -r $(nix-instantiate ./test.nix)
+    /nix/store/31axcgrlbfsxzmfff1gyj1bf62hvkby2-aterm-2.3.1
+
+This is essentially what [`nix-build`](#sec-nix-build) does.
+
+To test whether a previously-built derivation is deterministic:
+
+    $ nix-build '<nixpkgs>' -A hello --check -K
+
+# Operation `--serve`
+
+## Synopsis
+
+nix-store
+
+\--serve
+
+\--write
+
+## Description
+
+The operation `--serve` provides access to the Nix store over stdin and
+stdout, and is intended to be used as a means of providing Nix store
+access to a restricted ssh user.
+
+The following flags are available:
+
+  - `--write`  
+    Allow the connected client to request the realization of
+    derivations. In effect, this can be used to make the host act as a
+    remote builder.
+
+## Examples
+
+To turn a host into a build server, the `authorized_keys` file can be
+used to provide build access to a given SSH public key:
+
+    $ cat <<EOF >>/root/.ssh/authorized_keys
+    command="nice -n20 nix-store --serve --write" ssh-rsa AAAAB3NzaC1yc2EAAAA...
+    EOF
+
+# Operation `--gc`
+
+## Synopsis
+
+nix-store
+
+\--gc
+
+\--print-roots
+
+\--print-live
+
+\--print-dead
+
+\--max-freed
+
+bytes
+
+## Description
+
+Without additional flags, the operation `--gc` performs a garbage
+collection on the Nix store. That is, all paths in the Nix store not
+reachable via file system references from a set of “roots”, are deleted.
+
+The following suboperations may be specified:
+
+  - `--print-roots`  
+    This operation prints on standard output the set of roots used by
+    the garbage collector. What constitutes a root is described in
+    [???](#ssec-gc-roots).
+
+  - `--print-live`  
+    This operation prints on standard output the set of “live” store
+    paths, which are all the store paths reachable from the roots. Live
+    paths should never be deleted, since that would break consistency —
+    it would become possible that applications are installed that
+    reference things that are no longer present in the store.
+
+  - `--print-dead`  
+    This operation prints out on standard output the set of “dead” store
+    paths, which is just the opposite of the set of live paths: any path
+    in the store that is not live (with respect to the roots) is dead.
+
+By default, all unreachable paths are deleted. The following options
+control what gets deleted and in what order:
+
+  - `--max-freed` bytes  
+    Keep deleting paths until at least bytes bytes have been deleted,
+    then stop. The argument bytes can be followed by the multiplicative
+    suffix `K`, `M`, `G` or `T`, denoting KiB, MiB, GiB or TiB units.
+
+The behaviour of the collector is also influenced by the
+[`keep-outputs`](#conf-keep-outputs) and
+[`keep-derivations`](#conf-keep-derivations) variables in the Nix
+configuration file.
+
+By default, the collector prints the total number of freed bytes when it
+finishes (or when it is interrupted). With `--print-dead`, it prints the
+number of bytes that would be freed.
+
+## Examples
+
+To delete all unreachable paths, just do:
+
+    $ nix-store --gc
+    deleting `/nix/store/kq82idx6g0nyzsp2s14gfsc38npai7lf-cairo-1.0.4.tar.gz.drv'
+    ...
+    8825586 bytes freed (8.42 MiB)
+
+To delete at least 100 MiBs of unreachable paths:
+
+    $ nix-store --gc --max-freed $((100 * 1024 * 1024))
+
+# Operation `--delete`
+
+## Synopsis
+
+nix-store
+
+\--delete
+
+\--ignore-liveness
+
+paths
+
+## Description
+
+The operation `--delete` deletes the store paths paths from the Nix
+store, but only if it is safe to do so; that is, when the path is not
+reachable from a root of the garbage collector. This means that you can
+only delete paths that would also be deleted by `nix-store --gc`. Thus,
+`--delete` is a more targeted version of `--gc`.
+
+With the option `--ignore-liveness`, reachability from the roots is
+ignored. However, the path still won’t be deleted if there are other
+paths in the store that refer to it (i.e., depend on it).
+
+## Example
+
+    $ nix-store --delete /nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4
+    0 bytes freed (0.00 MiB)
+    error: cannot delete path `/nix/store/zq0h41l75vlb4z45kzgjjmsjxvcv1qk7-mesa-6.4' since it is still alive
+
+# Operation `--query`
+
+## 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
+
+## Description
+
+The operation `--query` displays various bits of information about the
+store paths . The queries are described below. At most one query can be
+specified. The default query is `--outputs`.
+
+The paths paths may also be symlinks from outside of the Nix store, to
+the Nix store. In that case, the query is applied to the target of the
+symlink.
+
+## Common query options
+
+  - `--use-output`; `-u`  
+    For each argument to the query that is a store derivation, apply the
+    query to the output path of the derivation instead.
+
+  - `--force-realise`; `-f`  
+    Realise each argument to the query first (see [`nix-store
+                    --realise`](#rsec-nix-store-realise)).
+
+## Queries
+
+  - `--outputs`  
+    Prints out the [output paths](#gloss-output-path) of the store
+    derivations paths. These are the paths that will be produced when
+    the derivation is built.
+
+  - `--requisites`; `-R`  
+    Prints out the [closure](#gloss-closure) of the store path paths.
+    
+    This query has one option:
+    
+      - `--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
+    the closure of an output path. A *cache deployment* (combined
+    source/binary deployment, including binaries of build-time-only
+    dependencies) is obtained by distributing the closure of a store
+    derivation and specifying the option `--include-outputs`.
+
+  - `--references`  
+    Prints the set of [references](#gloss-reference) of the store paths
+    paths, that is, their immediate dependencies. (For *all*
+    dependencies, use `--requisites`.)
+
+  - `--referrers`  
+    Prints the set of *referrers* of the store paths paths, that is, the
+    store paths currently existing in the Nix store that refer to one of
+    paths. Note that contrary to the references, the set of referrers is
+    not constant; it can change as store paths are added or removed.
+
+  - `--referrers-closure`  
+    Prints the closure of the set of store paths paths under the
+    referrers relation; that is, all store paths that directly or
+    indirectly refer to one of paths. These are all the path currently
+    in the Nix store that are dependent on paths.
+
+  - `--deriver`; `-d`  
+    Prints the [deriver](#gloss-deriver) of the store paths paths. If
+    the path has no deriver (e.g., if it is a source file), or if the
+    deriver is not known (e.g., in the case of a binary-only
+    deployment), the string `unknown-deriver` is printed.
+
+  - `--graph`  
+    Prints the references graph of the store paths paths in the format
+    of the `dot` tool of AT\&T's [Graphviz
+    package](http://www.graphviz.org/). This can be used to visualise
+    dependency graphs. To obtain a build-time dependency graph, apply
+    this to a store derivation. To obtain a runtime dependency graph,
+    apply it to an output path.
+
+  - `--tree`  
+    Prints the references graph of the store paths paths as a nested
+    ASCII tree. References are ordered by descending closure size; this
+    tends to flatten the tree, making it more readable. The query only
+    recurses into a store path when it is first encountered; this
+    prevents a blowup of the tree representation of the graph.
+
+  - `--graphml`  
+    Prints the references graph of the store paths paths in the
+    [GraphML](http://graphml.graphdrawing.org/) file format. This can be
+    used to visualise dependency graphs. To obtain a build-time
+    dependency graph, apply this to a store derivation. To obtain a
+    runtime dependency graph, apply it to an output path.
+
+  - `--binding` name; `-b` name  
+    Prints the value of the attribute name (i.e., environment variable)
+    of the store derivations paths. It is an error for a derivation to
+    not have the specified attribute.
+
+  - `--hash`  
+    Prints the SHA-256 hash of the contents of the store paths paths
+    (that is, the hash of the output of `nix-store --dump` on the given
+    paths). Since the hash is stored in the Nix database, this is a fast
+    operation.
+
+  - `--size`  
+    Prints the size in bytes of the contents of the store paths paths —
+    to be precise, the size of the output of `nix-store --dump` on the
+    given paths. Note that the actual disk space required by the store
+    paths may be higher, especially on filesystems with large cluster
+    sizes.
+
+  - `--roots`  
+    Prints the garbage collector roots that point, directly or
+    indirectly, at the store paths paths.
+
+## Examples
+
+Print the closure (runtime dependencies) of the `svn` program in the
+current user environment:
+
+    $ nix-store -qR $(which svn)
+    /nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
+    /nix/store/9lz9yc6zgmc0vlqmn2ipcpkjlmbi51vv-glibc-2.3.4
+    ...
+
+Print the build-time dependencies of `svn`:
+
+    $ nix-store -qR $(nix-store -qd $(which svn))
+    /nix/store/02iizgn86m42q905rddvg4ja975bk2i4-grep-2.5.1.tar.bz2.drv
+    /nix/store/07a2bzxmzwz5hp58nf03pahrv2ygwgs3-gcc-wrapper.sh
+    /nix/store/0ma7c9wsbaxahwwl04gbw3fcd806ski4-glibc-2.3.4.drv
+    ... lots of other paths ...
+
+The difference with the previous example is that we ask the closure of
+the derivation (`-qd`), not the closure of the output path that contains
+`svn`.
+
+Show the build-time dependencies as a tree:
+
+    $ nix-store -q --tree $(nix-store -qd $(which svn))
+    /nix/store/7i5082kfb6yjbqdbiwdhhza0am2xvh6c-subversion-1.1.4.drv
+    +---/nix/store/d8afh10z72n8l1cr5w42366abiblgn54-builder.sh
+    +---/nix/store/fmzxmpjx2lh849ph0l36snfj9zdibw67-bash-3.0.drv
+    |   +---/nix/store/570hmhmx3v57605cqg9yfvvyh0nnb8k8-bash
+    |   +---/nix/store/p3srsbd8dx44v2pg6nbnszab5mcwx03v-builder.sh
+    ...
+
+Show all paths that depend on the same OpenSSL library as `svn`:
+
+    $ nix-store -q --referrers $(nix-store -q --binding openssl $(nix-store -qd $(which svn)))
+    /nix/store/23ny9l9wixx21632y2wi4p585qhva1q8-sylpheed-1.0.0
+    /nix/store/5mbglq5ldqld8sj57273aljwkfvj22mc-subversion-1.1.4
+    /nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3
+    /nix/store/l51240xqsgg8a7yrbqdx1rfzyv6l26fx-lynx-2.8.5
+
+Show all paths that directly or indirectly depend on the Glibc (C
+library) used by `svn`:
+
+    $ nix-store -q --referrers-closure $(ldd $(which svn) | grep /libc.so | awk '{print $3}')
+    /nix/store/034a6h4vpz9kds5r6kzb9lhh81mscw43-libgnomeprintui-2.8.2
+    /nix/store/15l3yi0d45prm7a82pcrknxdh6nzmxza-gawk-3.1.4
+    ...
+
+Note that `ldd` is a command that prints out the dynamic libraries used
+by an ELF executable.
+
+Make a picture of the runtime dependency graph of the current user
+environment:
+
+    $ nix-store -q --graph ~/.nix-profile | dot -Tps > graph.ps
+    $ gv graph.ps
+
+Show every garbage collector root that points to a store path that
+depends on `svn`:
+
+    $ nix-store -q --roots $(which svn)
+    /nix/var/nix/profiles/default-81-link
+    /nix/var/nix/profiles/default-82-link
+    /nix/var/nix/profiles/per-user/eelco/profile-97-link
+
+# Operation `--add`
+
+## Synopsis
+
+nix-store
+
+\--add
+
+paths
+
+## Description
+
+The operation `--add` adds the specified paths to the Nix store. It
+prints the resulting paths in the Nix store on standard output.
+
+## Example
+
+    $ nix-store --add ./foo.c
+    /nix/store/m7lrha58ph6rcnv109yzx1nk1cj7k7zf-foo.c
+
+# Operation `--add-fixed`
+
+## Synopsis
+
+nix-store
+
+\--recursive
+
+\--add-fixed
+
+algorithm
+
+paths
+
+## Description
+
+The operation `--add-fixed` adds the specified paths to the Nix store.
+Unlike `--add` paths are registered using the specified hashing
+algorithm, resulting in the same output path as a fixed-output
+derivation. This can be used for sources that are not available from a
+public url or broke since the download expression was written.
+
+This operation has the following options:
+
+  - `--recursive`  
+    Use recursive instead of flat hashing mode, used when adding
+    directories to the store.
+
+## Example
+
+    $ nix-store --add-fixed sha256 ./hello-2.10.tar.gz
+    /nix/store/3x7dwzq014bblazs7kq20p9hyzz0qh8g-hello-2.10.tar.gz
+
+# Operation `--verify`
+
+## Synopsis
+
+nix-store
+
+\--verify
+
+\--check-contents
+
+\--repair
+
+## Description
+
+The operation `--verify` verifies the internal consistency of the Nix
+database, and the consistency between the Nix database and the Nix
+store. Any inconsistencies encountered are 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.
+
+This operation has the following options:
+
+  - `--check-contents`  
+    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,
+    `--check-contents` is obviously quite slow.
+
+  - `--repair`  
+    If any valid path is missing from the store, or (if
+    `--check-contents` is given) the contents of a valid path has been
+    modified, then try to repair the path by redownloading it. See
+    `nix-store --repair-path` for details.
+
+# Operation `--verify-path`
+
+## Synopsis
+
+nix-store
+
+\--verify-path
+
+paths
+
+## Description
+
+The operation `--verify-path` compares the contents of the given store
+paths to their cryptographic hashes stored in Nix’s database. For every
+changed path, it prints a warning message. The exit status is 0 if no
+path has changed, and 1 otherwise.
+
+## Example
+
+To verify the integrity of the `svn` command and all its dependencies:
+
+    $ nix-store --verify-path $(nix-store -qR $(which svn))
+
+# Operation `--repair-path`
+
+## Synopsis
+
+nix-store
+
+\--repair-path
+
+paths
+
+## Description
+
+The operation `--repair-path` attempts to “repair” the specified paths
+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
+> in a broken state (e.g., if the path contains a critical system
+> component like the GNU C Library).
+
+## Example
+
+    $ nix-store --verify-path /nix/store/dj7a81wsm1ijwwpkks3725661h3263p5-glibc-2.13
+    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'...
+    …
+
+# Operation `--dump`
+
+## Synopsis
+
+nix-store
+
+\--dump
+
+path
+
+## Description
+
+The operation `--dump` produces a NAR (Nix ARchive) file containing the
+contents of the file system tree rooted at path. The archive is written
+to standard output.
+
+A NAR archive is like a TAR or Zip archive, but it contains only the
+information that Nix considers important. For instance, timestamps are
+elided because all files in the Nix store have their timestamp set to 0
+anyway. Likewise, all permissions are left out except for the execute
+bit, because all files in the Nix store have 444 or 555 permission.
+
+Also, a NAR archive is *canonical*, meaning that “equal” paths always
+produce the same NAR archive. For instance, directory entries are always
+sorted so that the actual on-disk order doesn’t influence the result.
+This means that the cryptographic hash of a NAR dump of a path is usable
+as a fingerprint of the contents of the path. Indeed, the hashes of
+store paths stored in Nix’s database (see [`nix-store -q
+--hash`](#refsec-nix-store-query)) are SHA-256 hashes of the NAR dump of
+each store path.
+
+NAR archives support filenames of unlimited length and 64-bit file
+sizes. They can contain regular files, directories, and symbolic links,
+but not other types of files (such as device nodes).
+
+A Nix archive can be unpacked using `nix-store
+--restore`.
+
+# Operation `--restore`
+
+## Synopsis
+
+nix-store
+
+\--restore
+
+path
+
+## Description
+
+The operation `--restore` unpacks a NAR archive to path, which must not
+already exist. The archive is read from standard input.
+
+# Operation `--export`
+
+## Synopsis
+
+nix-store
+
+\--export
+
+paths
+
+## Description
+
+The operation `--export` writes a serialisation of the specified store
+paths to standard output in a format that can be imported into another
+Nix store with `nix-store --import`. This is like `nix-store
+--dump`, except that the NAR archive produced by that command doesn’t
+contain the necessary meta-information to allow it to be imported into
+another Nix store (namely, the set of references of the path).
+
+This command does not produce a *closure* of the specified paths, so if
+a store path references other store paths that are missing in the target
+Nix store, the import will fail. To copy a whole closure, do something
+like:
+
+    $ nix-store --export $(nix-store -qR paths) > out
+
+To import the whole closure again, run:
+
+    $ nix-store --import < out
+
+# Operation `--import`
+
+## Synopsis
+
+nix-store
+
+\--import
+
+## Description
+
+The operation `--import` reads a serialisation of a set of store paths
+produced by `nix-store --export` from standard input and adds those
+store paths to the Nix store. Paths that already exist in the Nix store
+are ignored. If a path refers to another path that doesn’t exist in the
+Nix store, the import fails.
+
+# Operation `--optimise`
+
+## Synopsis
+
+nix-store
+
+\--optimise
+
+## Description
+
+The operation `--optimise` reduces Nix store disk space usage by finding
+identical files in the store and hard-linking them to each other. It
+typically reduces the size of the store by something like 25-35%. Only
+regular files and symlinks are hard-linked in this manner. Files are
+considered identical when they have the same NAR archive serialisation:
+that is, regular files must have the same contents and permission
+(executable or non-executable), and symlinks must have the same
+contents.
+
+After completion, or when the command is interrupted, a report on the
+achieved savings is printed on standard error.
+
+Use `-vv` or `-vvv` to get some progress indication.
+
+## Example
+
+    $ nix-store --optimise
+    hashing files in `/nix/store/qhqx7l2f1kmwihc9bnxs7rc159hsxnf3-gcc-4.1.1'
+    ...
+    541838819 bytes (516.74 MiB) freed by hard-linking 54143 files;
+    there are 114486 files with equal contents out of 215894 files in total
+
+# Operation `--read-log`
+
+## Synopsis
+
+nix-store
+
+\--read-log
+
+\-l
+
+paths
+
+## Description
+
+The operation `--read-log` prints the build log of the specified store
+paths on standard output. The build log is whatever the builder of a
+derivation wrote to standard output and standard error. If a store path
+is not a derivation, the deriver of the store path is used.
+
+Build logs are kept in `/nix/var/log/nix/drvs`. However, there is no
+guarantee that a build log is available for any particular store path.
+For instance, if the path was downloaded as a pre-built binary through a
+substitute, then the log is unavailable.
+
+## Example
+
+    $ nix-store -l $(which ktorrent)
+    building /nix/store/dhc73pvzpnzxhdgpimsd9sw39di66ph1-ktorrent-2.2.1
+    unpacking sources
+    unpacking source archive /nix/store/p8n1jpqs27mgkjw07pb5269717nzf5f8-ktorrent-2.2.1.tar.gz
+    ktorrent-2.2.1/
+    ktorrent-2.2.1/NEWS
+    ...
+
+# Operation `--dump-db`
+
+## Synopsis
+
+nix-store
+
+\--dump-db
+
+paths
+
+## Description
+
+The operation `--dump-db` writes a dump of the Nix database to standard
+output. It can be loaded into an empty Nix store using `--load-db`. This
+is useful for making backups and when migrating to different database
+schemas.
+
+By default, `--dump-db` will dump the entire Nix database. When one or
+more store paths is passed, only the subset of the Nix database for
+those store paths is dumped. As with `--export`, the user is responsible
+for passing all the store paths for a closure. See `--export` for an
+example.
+
+# Operation `--load-db`
+
+## Synopsis
+
+nix-store
+
+\--load-db
+
+## Description
+
+The operation `--load-db` reads a dump of the Nix database created by
+`--dump-db` from standard input and loads it into the Nix database.
+
+# Operation `--print-env`
+
+## Synopsis
+
+nix-store
+
+\--print-env
+
+drvpath
+
+## Description
+
+The operation `--print-env` prints out the environment of a derivation
+in a format that can be evaluated by a shell. The command line arguments
+of the builder are placed in the variable `_args`.
+
+## Example
+
+    $ nix-store --print-env $(nix-instantiate '<nixpkgs>' -A firefox)
+    …
+    export src; src='/nix/store/plpj7qrwcz94z2psh6fchsi7s8yihc7k-firefox-12.0.source.tar.bz2'
+    export stdenv; stdenv='/nix/store/7c8asx3yfrg5dg1gzhzyq2236zfgibnn-stdenv'
+    export system; system='x86_64-linux'
+    export _args; _args='-e /nix/store/9krlzvny65gdc8s7kpb6lkx8cd02c25c-default-builder.sh'
+
+# Operation `--generate-binary-cache-key`
+
+## Synopsis
+
+nix-store
+
+\--generate-binary-cache-key
+
+key-name
+
+secret-key-file
+
+public-key-file
+
+## Description
+
+This command generates an [Ed25519 key pair](http://ed25519.cr.yp.to/)
+that can be used to create a signed binary cache. It takes three
+mandatory parameters:
+
+1.  A key name, such as `cache.example.org-1`, that is used to look up
+    keys on the client when it verifies signatures. It can be anything,
+    but it’s suggested to use the host name of your cache (e.g.
+    `cache.example.org`) with a suffix denoting the number of the key
+    (to be incremented every time you need to revoke a key).
+
+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
diff --git a/doc/manual/src/command-ref/opt-common-syn.md b/doc/manual/src/command-ref/opt-common-syn.md
new file mode 100644
index 000000000..b66d318c2
--- /dev/null
+++ b/doc/manual/src/command-ref/opt-common-syn.md
@@ -0,0 +1,57 @@
+\--help
+
+\--version
+
+\--verbose
+
+\-v
+
+\--quiet
+
+\--log-format
+
+format
+
+\--no-build-output
+
+\-Q
+
+\--max-jobs
+
+\-j
+
+number
+
+\--cores
+
+number
+
+\--max-silent-time
+
+number
+
+\--timeout
+
+number
+
+\--keep-going
+
+\-k
+
+\--keep-failed
+
+\-K
+
+\--fallback
+
+\--readonly-mode
+
+\-I
+
+path
+
+\--option
+
+name
+
+value
diff --git a/doc/manual/src/command-ref/opt-inst-syn.md b/doc/manual/src/command-ref/opt-inst-syn.md
new file mode 100644
index 000000000..1703c40e3
--- /dev/null
+++ b/doc/manual/src/command-ref/opt-inst-syn.md
@@ -0,0 +1,15 @@
+\--prebuilt-only
+
+\-b
+
+\--attr
+
+\-A
+
+\--from-expression
+
+\-E
+
+\--from-profile
+
+path