Generate the nix.conf docs from the source code

This means we don't have two (divergent) sets of option descriptions
anymore.

10 files changed, 817 insertions, 849 deletions

diff --git a/.gitignore b/.gitignore
index b8028e665..44dbaa5d7 100644
--- a/.gitignore
+++ b/.gitignore
@@ -26,7 +26,9 @@ perl/Makefile.config
 /doc/manual/*.5
 /doc/manual/*.8
 /doc/manual/nix.json
+/doc/manual/conf-file.json
 /doc/manual/src/command-ref/nix.md
+/doc/manual/src/command-ref/conf-file.md
 
 # /scripts/
 /scripts/nix-profile.sh
diff --git a/doc/manual/generate-options.jq b/doc/manual/generate-options.jq
new file mode 100644
index 000000000..3ee51ddea
--- /dev/null
+++ b/doc/manual/generate-options.jq
@@ -0,0 +1,11 @@
+. | to_entries | sort_by(.key) | map(
+  "  - `" + .key + "`  \n"
+  + (.value.description | split("\n") | map("    " + . + "\n") | join("")) + "\n\n"
+  + "    **Default**: " + (
+      if .value.value == "" or .value.value == []
+      then "*empty*"
+      elif (.value.value | type) == "array"
+      then "`" + (.value.value | join(" ")) + "`"
+      else "`" + (.value.value | tostring) + "`" end)
+  + "\n\n"
+) | join("")
diff --git a/doc/manual/local.mk b/doc/manual/local.mk
index 04c57b23b..dcc02d538 100644
--- a/doc/manual/local.mk
+++ b/doc/manual/local.mk
@@ -27,9 +27,16 @@ $(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md
 $(d)/src/command-ref/nix.md: $(d)/nix.json $(d)/generate-manpage.jq
 	jq -r -f doc/manual/generate-manpage.jq $< > $@
 
+$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/generate-options.jq $(d)/src/command-ref/conf-file-prefix.md
+	cat doc/manual/src/command-ref/conf-file-prefix.md > $@
+	jq -r -f doc/manual/generate-options.jq $< >> $@
+
 $(d)/nix.json: $(bindir)/nix
 	$(trace-gen) $(bindir)/nix dump-args > $@
 
+$(d)/conf-file.json: $(bindir)/nix
+	$(trace-gen) env -i NIX_CONF_DIR=/dummy HOME=/dummy $(bindir)/nix show-config --json --experimental-features nix-command > $@
+
 # Generate the HTML manual.
 install: $(docdir)/manual/index.html
 
diff --git a/doc/manual/src/command-ref/conf-file-prefix.md b/doc/manual/src/command-ref/conf-file-prefix.md
new file mode 100644
index 000000000..04c6cd859
--- /dev/null
+++ b/doc/manual/src/command-ref/conf-file-prefix.md
@@ -0,0 +1,39 @@
+Title: nix.conf
+
+# Name
+
+`nix.conf` - Nix configuration file
+
+# Description
+
+By default Nix reads settings from the following places:
+
+  - The system-wide configuration file `sysconfdir/nix/nix.conf` (i.e.
+    `/etc/nix/nix.conf` on most systems), or `$NIX_CONF_DIR/nix.conf` if
+    `NIX_CONF_DIR` is set. Values loaded in this file are not forwarded
+    to the Nix daemon. The client assumes that the daemon has already
+    loaded them.
+
+  - 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`.
+
+The configuration files consist of `name =
+value` pairs, one per line. Other files can be included with a line like
+`include
+path`, where *path* is interpreted relative to the current conf file and
+a missing file is an error unless `!include` is used instead. Comments
+start with a `#` character. Here is an example configuration file:
+
+    keep-outputs = true       # Nice for developers
+    keep-derivations = true   # Idem
+
+You can override settings on the command line using the `--option` flag,
+e.g. `--option keep-outputs
+false`.
+
+The following settings are currently available:
+
diff --git a/doc/manual/src/command-ref/conf-file.md b/doc/manual/src/command-ref/conf-file.md
deleted file mode 100644
index fdc8f5265..000000000
--- a/doc/manual/src/command-ref/conf-file.md
+++ /dev/null
@@ -1,691 +0,0 @@
-Title: nix.conf
-
-# Name
-
-`nix.conf` - Nix configuration file
-
-# Description
-
-By default Nix reads settings from the following places:
-
-  - The system-wide configuration file `sysconfdir/nix/nix.conf` (i.e.
-    `/etc/nix/nix.conf` on most systems), or `$NIX_CONF_DIR/nix.conf` if
-    `NIX_CONF_DIR` is set. Values loaded in this file are not forwarded
-    to the Nix daemon. The client assumes that the daemon has already
-    loaded them.
-
-  - 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`.
-
-The configuration files consist of `name =
-value` pairs, one per line. Other files can be included with a line like
-`include
-path`, where *path* is interpreted relative to the current conf file and
-a missing file is an error unless `!include` is used instead. Comments
-start with a `#` character. Here is an example configuration file:
-
-    keep-outputs = true       # Nice for developers
-    keep-derivations = true   # Idem
-
-You can override settings on the command line using the `--option` flag,
-e.g. `--option keep-outputs
-false`.
-
-The following settings are currently available:
-
-  - `allowed-uris`  
-    A list of URI prefixes to which access is allowed in restricted
-    evaluation mode. For example, when set to
-    `https://github.com/NixOS`, builtin functions such as `fetchGit` are
-    allowed to access `https://github.com/NixOS/patchelf.git`.
-
-  - `allow-import-from-derivation`  
-    By default, Nix allows you to `import` from a derivation, allowing
-    building at evaluation time. With this option set to false, Nix will
-    throw an error when evaluating an expression that uses this feature,
-    allowing users to ensure their evaluation will not require any
-    builds to take place.
-
-  - `allow-new-privileges`  
-    (Linux-specific.) By default, builders on Linux cannot acquire new
-    privileges by calling setuid/setgid programs or programs that have
-    file capabilities. For example, programs such as `sudo` or `ping`
-    will fail. (Note that in sandbox builds, no such programs are
-    available unless you bind-mount them into the sandbox via the
-    `sandbox-paths` option.) You can allow the use of such programs by
-    enabling this option. This is impure and usually undesirable, but
-    may be useful in certain scenarios (e.g. to spin up containers or
-    set up userspace network interfaces in tests).
-
-  - `allowed-users`  
-    A list of names of users (separated by whitespace) that are allowed
-    to connect to the Nix daemon. As with the `trusted-users` option,
-    you can specify groups by prefixing them with `@`. Also, you can
-    allow all users by specifying `*`. The default is `*`.
-    
-    Note that trusted users are always allowed to connect.
-
-  - `auto-optimise-store`  
-    If set to `true`, Nix automatically detects files in the store
-    that have identical contents, and replaces them with hard links to
-    a single copy. This saves disk space. If set to `false` (the
-    default), you can still run `nix-store --optimise` to get rid of
-    duplicate files.
-
-  - `builders`  
-    A list of machines on which to perform builds.
-
-  - `builders-use-substitutes`  
-    If set to `true`, Nix will instruct remote build machines to use
-    their own binary substitutes if available. In practical terms, this
-    means that remote hosts will fetch as many build dependencies as
-    possible from their own substitutes (e.g, from `cache.nixos.org`),
-    instead of waiting for this host to upload them all. This can
-    drastically reduce build times if the network connection between
-    this computer and the remote build host is slow. Defaults to
-    `false`.
-
-  - `build-users-group`  
-    This options specifies the Unix group containing the Nix build user
-    accounts. In multi-user Nix installations, builds should not be
-    performed by the Nix account since that would allow users to
-    arbitrarily modify the Nix store and database by supplying specially
-    crafted builders; and they cannot be performed by the calling user
-    since that would allow him/her to influence the build result.
-    
-    Therefore, if this option is non-empty and specifies a valid group,
-    builds will be performed under the user accounts that are a member
-    of the group specified here (as listed in `/etc/group`). Those user
-    accounts should not be used for any other purpose\!
-    
-    Nix will never run two builds under the same user account at the
-    same time. This is to prevent an obvious security hole: a malicious
-    user writing a Nix expression that modifies the build result of a
-    legitimate Nix expression being built by another user. Therefore it
-    is good to have as many Nix build user accounts as you can spare.
-    (Remember: uids are cheap.)
-    
-    The build users should have permission to create files in the Nix
-    store, but not delete them. Therefore, `/nix/store` should be owned
-    by the Nix account, its group should be the group specified here,
-    and its mode should be `1775`.
-    
-    If the build users group is empty, builds will be performed under
-    the uid of the Nix process (that is, the uid of the caller if
-    `NIX_REMOTE` is empty, the uid under which the Nix daemon runs if
-    `NIX_REMOTE` is `daemon`). Obviously, this should not be used in
-    multi-user settings with untrusted users.
-
-  - `compress-build-log`  
-    If set to `true` (the default), build logs written to
-    `/nix/var/log/nix/drvs` will be compressed on the fly using bzip2.
-    Otherwise, they will not be compressed.
-
-  - `connect-timeout`  
-    The timeout (in seconds) for establishing connections in the binary
-    cache substituter. It corresponds to `curl`’s `--connect-timeout`
-    option.
-
-  - `cores`  
-    Sets the value of the `NIX_BUILD_CORES` environment variable in the
-    invocation of builders. Builders can use this variable at their
-    discretion to control the maximum amount of parallelism. For
-    instance, in Nixpkgs, if the derivation attribute
-    `enableParallelBuilding` is set to `true`, the builder passes the
-    `-jN` flag to GNU Make. It can be overridden using the `--cores`
-    command line switch and defaults to `1`. The value `0` means that
-    the builder should use all available CPU cores in the system.
-
-  - `diff-hook`  
-    Absolute path to an executable capable of diffing build
-    results. The hook is executed if `run-diff-hook` is true, and the
-    output of a build is known to not be the same. This program is not
-    executed to determine if two results are the same.
-    
-    The diff hook is executed by the same user and group who ran the
-    build. However, the diff hook does not have write access to the
-    store path just built.
-    
-    The diff hook program receives three parameters:
-    
-    1.  A path to the previous build's results
-    
-    2.  A path to the current build's results
-    
-    3.  The path to the build's derivation
-    
-    4.  The path to the build's scratch directory. This directory will
-        exist only if the build was run with `--keep-failed`.
-    
-    The stderr and stdout output from the diff hook will not be
-    displayed to the user. Instead, it will print to the nix-daemon's
-    log.
-    
-    When using the Nix daemon, `diff-hook` must be set in the `nix.conf`
-    configuration file, and cannot be passed at the command line.
-
-  - `enforce-determinism`  
-    See `repeat`.
-
-  - `extra-sandbox-paths`  
-    A list of additional paths appended to `sandbox-paths`. Useful if
-    you want to extend its default value.
-
-  - `extra-platforms`  
-    Platforms other than the native one which this machine is capable of
-    building for. This can be useful for supporting additional
-    architectures on compatible machines: i686-linux can be built on
-    x86\_64-linux machines (and the default for this setting reflects
-    this); armv7 is backwards-compatible with armv6 and armv5tel; some
-    aarch64 machines can also natively run 32-bit ARM code; and
-    qemu-user may be used to support non-native platforms (though this
-    may be slow and buggy). Most values for this are not enabled by
-    default because build systems will often misdetect the target
-    platform and generate incompatible code, so you may wish to
-    cross-check the results of using this option against proper
-    natively-built versions of your derivations.
-
-  - `extra-substituters`  
-    Additional binary caches appended to those specified in
-    `substituters`. When used by unprivileged users, untrusted
-    substituters (i.e. those not listed in `trusted-substituters`) are
-    silently ignored.
-
-  - `fallback`  
-    If set to `true`, Nix will fall back to building from source if a
-    binary substitute fails. This is equivalent to the `--fallback`
-    flag. The default is `false`.
-
-  - `fsync-metadata`  
-    If set to `true`, changes to the Nix store metadata (in
-    `/nix/var/nix/db`) are synchronously flushed to disk. This improves
-    robustness in case of system crashes, but reduces performance. The
-    default is `true`.
-
-  - `hashed-mirrors`  
-    A list of web servers used by `builtins.fetchurl` to obtain files by
-    hash. The default is `http://tarballs.nixos.org/`. Given a hash type
-    *ht* and a base-16 hash *h*, Nix will try to download the file from
-    *hashed-mirror*/*ht*/*h*. This allows files to be downloaded even if
-    they have disappeared from their original URI. For example, given
-    the default mirror `http://tarballs.nixos.org/`, when building the
-    derivation
-
-    ```nix
-    builtins.fetchurl {
-      url = "https://example.org/foo-1.2.3.tar.xz";
-      sha256 = "2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae";
-    }
-    ```
-    
-    Nix will attempt to download this file from
-    `http://tarballs.nixos.org/sha256/2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae`
-    first. If it is not available there, if will try the original URI.
-
-  - `http-connections`  
-    The maximum number of parallel TCP connections used to fetch files
-    from binary caches and by other downloads. It defaults to 25. 0
-    means no limit.
-
-  - `keep-build-log`  
-    If set to `true` (the default), Nix will write the build log of a
-    derivation (i.e. the standard output and error of its builder) to
-    the directory `/nix/var/log/nix/drvs`. The build log can be
-    retrieved using the command `nix-store -l path`.
-
-  - `keep-derivations`  
-    If `true` (default), the garbage collector will keep the derivations
-    from which non-garbage store paths were built. If `false`, they will
-    be deleted unless explicitly registered as a root (or reachable from
-    other roots).
-    
-    Keeping derivation around is useful for querying and traceability
-    (e.g., it allows you to ask with what dependencies or options a
-    store path was built), so by default this option is on. Turn it off
-    to save a bit of disk space (or a lot if `keep-outputs` is also
-    turned on).
-
-  - `keep-env-derivations`  
-    If `false` (default), derivations are not stored in Nix user
-    environments. That is, the derivations of any build-time-only
-    dependencies may be garbage-collected.
-    
-    If `true`, when you add a Nix derivation to a user environment, the
-    path of the derivation is stored in the user environment. Thus, the
-    derivation will not be garbage-collected until the user environment
-    generation is deleted (`nix-env --delete-generations`). To prevent
-    build-time-only dependencies from being collected, you should also
-    turn on `keep-outputs`.
-    
-    The difference between this option and `keep-derivations` is that
-    this one is “sticky”: it applies to any user environment created
-    while this option was enabled, while `keep-derivations` only applies
-    at the moment the garbage collector is run.
-
-  - `keep-outputs`  
-    If `true`, the garbage collector will keep the outputs of
-    non-garbage derivations. If `false` (default), outputs will be
-    deleted unless they are GC roots themselves (or reachable from other
-    roots).
-    
-    In general, outputs must be registered as roots separately. However,
-    even if the output of a derivation is registered as a root, the
-    collector will still delete store paths that are used only at build
-    time (e.g., the C compiler, or source tarballs downloaded from the
-    network). To prevent it from doing so, set this option to `true`.
-
-  - `max-build-log-size`  
-    This option defines the maximum number of bytes that a builder can
-    write to its stdout/stderr. If the builder exceeds this limit, it’s
-    killed. A value of `0` (the default) means that there is no limit.
-
-  - `max-free`  
-    When a garbage collection is triggered by the `min-free` option, it
-    stops as soon as `max-free` bytes are available. The default is
-    infinity (i.e. delete all garbage).
-
-  - `max-jobs`  
-    This option defines the maximum number of jobs that Nix will try to
-    build in parallel. The default is `1`. The special value `auto`
-    causes Nix to use the number of CPUs in your system. `0` is useful
-    when using remote builders to prevent any local builds (except for
-    `preferLocalBuild` derivation attribute which executes locally
-    regardless). It can be overridden using the `--max-jobs` (`-j`)
-    command line switch.
-
-  - `max-silent-time`  
-    This option defines the maximum number of seconds that a builder can
-    go without producing any data on standard output or standard error.
-    This is useful (for instance in an automated build system) to catch
-    builds that are stuck in an infinite loop, or to catch remote builds
-    that are hanging due to network problems. It can be overridden using
-    the `--max-silent-time` command line switch.
-    
-    The value `0` means that there is no timeout. This is also the
-    default.
-
-  - `min-free`  
-    When free disk space in `/nix/store` drops below `min-free` during a
-    build, Nix performs a garbage-collection until `max-free` bytes are
-    available or there is no more garbage. A value of `0` (the default)
-    disables this feature.
-
-  - `narinfo-cache-negative-ttl`  
-    The TTL in seconds for negative lookups. If a store path is queried
-    from a substituter but was not found, there will be a negative
-    lookup cached in the local disk cache database for the specified
-    duration.
-
-  - `narinfo-cache-positive-ttl`  
-    The TTL in seconds for positive lookups. If a store path is queried
-    from a substituter, the result of the query will be cached in the
-    local disk cache database including some of the NAR metadata. The
-    default TTL is a month, setting a shorter TTL for positive lookups
-    can be useful for binary caches that have frequent garbage
-    collection, in which case having a more frequent cache invalidation
-    would prevent trying to pull the path again and failing with a hash
-    mismatch if the build isn't reproducible.
-
-  - `netrc-file`  
-    If set to an absolute path to a `netrc` file, Nix will use the HTTP
-    authentication credentials in this file when trying to download from
-    a remote host through HTTP or HTTPS. Defaults to
-    `$NIX_CONF_DIR/netrc`.
-    
-    The `netrc` file consists of a list of accounts in the following
-    format:
-    
-        machine my-machine
-        login my-username
-        password my-password
-    
-    For the exact syntax, see [the `curl`
-    documentation](https://ec.haxx.se/usingcurl-netrc.html).
-    
-    > **Note**
-    > 
-    > This must be an absolute path, and `~` is not resolved. For
-    > example, `~/.netrc` won't resolve to your home directory's
-    > `.netrc`.
-
-  - `plugin-files`  
-    A list of plugin files to be loaded by Nix. Each of these files will
-    be dlopened by Nix, allowing them to affect execution through static
-    initialization. In particular, these plugins may construct static
-    instances of RegisterPrimOp to add new primops or constants to the
-    expression language, RegisterStoreImplementation to add new store
-    implementations, RegisterCommand to add new subcommands to the `nix`
-    command, and RegisterSetting to add new nix config settings. See the
-    constructors for those types for more details.
-    
-    Since these files are loaded into the same address space as Nix
-    itself, they must be DSOs compatible with the instance of Nix
-    running at the time (i.e. compiled against the same headers, not
-    linked to any incompatible libraries). They should not be linked to
-    any Nix libs directly, as those will be available already at load
-    time.
-    
-    If an entry in the list is a directory, all files in the directory
-    are loaded as plugins (non-recursively).
-
-  - `pre-build-hook`  
-    If set, the path to a program that can set extra derivation-specific
-    settings for this system. This is used for settings that can't be
-    captured by the derivation model itself and are too variable between
-    different versions of the same system to be hard-coded into nix.
-    
-    The hook is passed the derivation path and, if sandboxes are
-    enabled, the sandbox directory. It can then modify the sandbox and
-    send a series of commands to modify various settings to stdout. The
-    currently recognized commands are:
-    
-      - `extra-sandbox-paths`  
-        Pass a list of files and directories to be included in the
-        sandbox for this build. One entry per line, terminated by an
-        empty line. Entries have the same format as `sandbox-paths`.
-
-  - `post-build-hook`  
-    Optional. The path to a program to execute after each build.
-    
-    This option is only settable in the global `nix.conf`, or on the
-    command line by trusted users.
-    
-    When using the nix-daemon, the daemon executes the hook as `root`.
-    If the nix-daemon is not involved, the hook runs as the user
-    executing the nix-build.
-    
-      - The hook executes after an evaluation-time build.
-    
-      - The hook does not execute on substituted paths.
-    
-      - The hook's output always goes to the user's terminal.
-    
-      - If the hook fails, the build succeeds but no further builds
-        execute.
-    
-      - The hook executes synchronously, and blocks other builds from
-        progressing while it runs.
-    
-    The program executes with no arguments. The program's environment
-    contains the following environment variables:
-    
-      - `DRV_PATH`  
-        The derivation for the built paths.
-        
-        Example:
-        `/nix/store/5nihn1a7pa8b25l9zafqaqibznlvvp3f-bash-4.4-p23.drv`
-    
-      - `OUT_PATHS`  
-        Output paths of the built derivation, separated by a space
-        character.
-        
-        Example:
-        `/nix/store/zf5lbh336mnzf1nlswdn11g4n2m8zh3g-bash-4.4-p23-dev
-        /nix/store/rjxwxwv1fpn9wa2x5ssk5phzwlcv4mna-bash-4.4-p23-doc
-        /nix/store/6bqvbzjkcp9695dq0dpl5y43nvy37pq1-bash-4.4-p23-info
-        /nix/store/r7fng3kk3vlpdlh2idnrbn37vh4imlj2-bash-4.4-p23-man
-        /nix/store/xfghy8ixrhz3kyy6p724iv3cxji088dx-bash-4.4-p23`.
-
-  - `repeat`  
-    How many times to repeat builds to check whether they are
-    deterministic. The default value is 0. If the value is non-zero,
-    every build is repeated the specified number of times. If the
-    contents of any of the runs differs from the previous ones and
-    `enforce-determinism` is true, the build is rejected and the
-    resulting store paths are not registered as “valid” in Nix’s
-    database.
-
-  - `require-sigs`  
-    If set to `true` (the default), any non-content-addressed path added
-    or copied to the Nix store (e.g. when substituting from a binary
-    cache) must have a valid signature, that is, be signed using one of
-    the keys listed in `trusted-public-keys` or `secret-key-files`. Set
-    to `false` to disable signature checking.
-
-  - `restrict-eval`  
-    If set to `true`, the Nix evaluator will not allow access to any
-    files outside of the Nix search path (as set via the `NIX_PATH`
-    environment variable or the `-I` option), or to URIs outside of
-    `allowed-uri`. The default is `false`.
-
-  - `run-diff-hook`  
-    If true, enable the execution of the `diff-hook` program.
-    
-    When using the Nix daemon, `run-diff-hook` must be set in the
-    `nix.conf` configuration file, and cannot be passed at the command
-    line.
-
-  - `sandbox`  
-    If set to `true`, builds will be performed in a *sandboxed
-    environment*, i.e., they’re isolated from the normal file system
-    hierarchy and will only see their dependencies in the Nix store,
-    the temporary build directory, private versions of `/proc`,
-    `/dev`, `/dev/shm` and `/dev/pts` (on Linux), and the paths
-    configured with the `sandbox-paths` option. This is useful to
-    prevent undeclared dependencies on files in directories such as
-    `/usr/bin`. In addition, on Linux, builds run in private PID,
-    mount, network, IPC and UTS namespaces to isolate them from other
-    processes in the system (except that fixed-output derivations do
-    not run in private network namespace to ensure they can access the
-    network).
-    
-    Currently, sandboxing only work on Linux and macOS. The use of a
-    sandbox requires that Nix is run as root (so you should use the
-    “build users” feature to perform the actual builds under different
-    users than root).
-    
-    If this option is set to `relaxed`, then fixed-output derivations
-    and derivations that have the `__noChroot` attribute set to `true`
-    do not run in sandboxes.
-    
-    The default is `true` on Linux and `false` on all other platforms.
-
-  - `sandbox-dev-shm-size`  
-    This option determines the maximum size of the `tmpfs` filesystem
-    mounted on `/dev/shm` in Linux sandboxes. For the format, see the
-    description of the `size` option of `tmpfs` in mount8. The default
-    is `50%`.
-
-  - `sandbox-paths`  
-    A list of paths bind-mounted into Nix sandbox environments. You can
-    use the syntax `target=source` to mount a path in a different
-    location in the sandbox; for instance, `/bin=/nix-bin` will mount
-    the path `/nix-bin` as `/bin` inside the sandbox. If *source* is
-    followed by `?`, then it is not an error if *source* does not exist;
-    for example, `/dev/nvidiactl?` specifies that `/dev/nvidiactl` will
-    only be mounted in the sandbox if it exists in the host filesystem.
-    
-    Depending on how Nix was built, the default value for this option
-    may be empty or provide `/bin/sh` as a bind-mount of `bash`.
-
-  - `secret-key-files`  
-    A whitespace-separated list of files containing secret (private)
-    keys. These are used to sign locally-built paths. They can be
-    generated using `nix-store --generate-binary-cache-key`. The
-    corresponding public key can be distributed to other users, who
-    can add it to `trusted-public-keys` in their `nix.conf`.
-
-  - `show-trace`  
-    Causes Nix to print out a stack trace in case of Nix expression
-    evaluation errors.
-
-  - `substitute`  
-    If set to `true` (default), Nix will use binary substitutes if
-    available. This option can be disabled to force building from
-    source.
-
-  - `stalled-download-timeout`  
-    The timeout (in seconds) for receiving data from servers during
-    download. Nix cancels idle downloads after this timeout's duration.
-
-  - `substituters`  
-    A list of URLs of substituters, separated by whitespace. The default
-    is `https://cache.nixos.org`.
-
-  - `system`  
-    This option specifies the canonical Nix system name of the current
-    installation, such as `i686-linux` or `x86_64-darwin`. Nix can only
-    build derivations whose `system` attribute equals the value
-    specified here. In general, it never makes sense to modify this
-    value from its default, since you can use it to ‘lie’ about the
-    platform you are building on (e.g., perform a Mac OS build on a
-    Linux machine; the result would obviously be wrong). It only makes
-    sense if the Nix binaries can run on multiple platforms, e.g.,
-    ‘universal binaries’ that run on `x86_64-linux` and `i686-linux`.
-    
-    It defaults to the canonical Nix system name detected by `configure`
-    at build time.
-
-  - `system-features`  
-    A set of system “features” supported by this machine, e.g. `kvm`.
-    Derivations can express a dependency on such features through the
-    derivation attribute `requiredSystemFeatures`. For example, the
-    attribute
-    
-        requiredSystemFeatures = [ "kvm" ];
-    
-    ensures that the derivation can only be built on a machine with the
-    `kvm` feature.
-    
-    This setting by default includes `kvm` if `/dev/kvm` is accessible,
-    and the pseudo-features `nixos-test`, `benchmark` and `big-parallel`
-    that are used in Nixpkgs to route builds to specific machines.
-
-  - `tarball-ttl`  
-    Default: `3600` seconds.
-    
-    The number of seconds a downloaded tarball is considered fresh. If
-    the cached tarball is stale, Nix will check whether it is still up
-    to date using the ETag header. Nix will download a new version if
-    the ETag header is unsupported, or the cached ETag doesn't match.
-    
-    Setting the TTL to `0` forces Nix to always check if the tarball is
-    up to date.
-    
-    Nix caches tarballs in `$XDG_CACHE_HOME/nix/tarballs`.
-    
-    Files fetched via `NIX_PATH`, `fetchGit`, `fetchMercurial`,
-    `fetchTarball`, and `fetchurl` respect this TTL.
-
-  - `timeout`  
-    This option defines the maximum number of seconds that a builder can
-    run. This is useful (for instance in an automated build system) to
-    catch builds that are stuck in an infinite loop but keep writing to
-    their standard output or standard error. It can be overridden using
-    the `--timeout` command line switch.
-    
-    The value `0` means that there is no timeout. This is also the
-    default.
-
-  - `trace-function-calls`  
-    Default: `false`.
-    
-    If set to `true`, the Nix evaluator will trace every function call.
-    Nix will print a log message at the "vomit" level for every function
-    entrance and function exit.
-    
-        function-trace entered undefined position at 1565795816999559622
-        function-trace exited undefined position at 1565795816999581277
-        function-trace entered /nix/store/.../example.nix:226:41 at 1565795253249935150
-        function-trace exited /nix/store/.../example.nix:226:41 at 1565795253249941684
-    
-    The `undefined position` means the function call is a builtin.
-    
-    Use the `contrib/stack-collapse.py` script distributed with the Nix
-    source code to convert the trace logs in to a format suitable for
-    `flamegraph.pl`.
-
-  - `trusted-public-keys`  
-    A whitespace-separated list of public keys. When paths are copied
-    from another Nix store (such as a binary cache), they must be
-    signed with one of these keys. For example:
-    `cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
-    hydra.nixos.org-1:CNHJZBh9K4tP3EKF6FkkgeVYsS3ohTl+oS0Qa8bezVs=`.
-
-  - `trusted-substituters`  
-    A list of URLs of substituters, separated by whitespace. These are
-    not used by default, but can be enabled by users of the Nix daemon
-    by specifying `--option substituters urls` on the command
-    line. Unprivileged users are only allowed to pass a subset of the
-    URLs listed in `substituters` and `trusted-substituters`.
-
-  - `trusted-users`  
-    A list of names of users (separated by whitespace) that have
-    additional rights when connecting to the Nix daemon, such as the
-    ability to specify additional binary caches, or to import unsigned
-    NARs. You can also specify groups by prefixing them with `@`; for
-    instance, `@wheel` means all users in the `wheel` group. The default
-    is `root`.
-    
-    > **Warning**
-    > 
-    > Adding a user to `trusted-users` is essentially equivalent to
-    > giving that user root access to the system. For example, the user
-    > can set `sandbox-paths` and thereby obtain read access to
-    > directories that are otherwise inacessible to them.
-
-## Deprecated Settings
-
-  - `binary-caches`  
-    *Deprecated:* `binary-caches` is now an alias to `substituters`.
-
-  - `binary-cache-public-keys`  
-    *Deprecated:* `binary-cache-public-keys` is now an alias `trusted-public-keys`.
-
-  - `build-compress-log`  
-    *Deprecated:* `build-compress-log` is now an alias to `compress-build-log`.
-
-  - `build-cores`  
-    *Deprecated:* `build-cores` is now an alias to `cores`.
-
-  - `build-extra-chroot-dirs`  
-    *Deprecated:* `build-extra-chroot-dirs` is now an alias to `extra-sandbox-paths`.
-
-  - `build-extra-sandbox-paths`  
-    *Deprecated:* `build-extra-sandbox-paths` is now an alias to `extra-sandbox-paths`.
-
-  - `build-fallback`  
-    *Deprecated:* `build-fallback` is now an alias to `fallback`.
-
-  - `build-max-jobs`  
-    *Deprecated:* `build-max-jobs` is now an alias to `max-jobs`.
-
-  - `build-max-log-size`  
-    *Deprecated:* `build-max-log-size` is now an alias to `max-build-log-size`.
-
-  - `build-max-silent-time`  
-    *Deprecated:* `build-max-silent-time` is now an alias to `max-silent-time`.
-
-  - `build-repeat`  
-    *Deprecated:* `build-repeat` is now an alias to `repeat`.
-
-  - `build-timeout`  
-    *Deprecated:* `build-timeout` is now an alias to `timeout`.
-
-  - `build-use-chroot`  
-    *Deprecated:* `build-use-chroot` is now an alias to `sandbox`.
-
-  - `build-use-sandbox`  
-    *Deprecated:* `build-use-sandbox` is now an alias to `sandbox`.
-
-  - `build-use-substitutes`  
-    *Deprecated:* `build-use-substitutes` is now an alias to `substitute`.
-
-  - `gc-keep-derivations`  
-    *Deprecated:* `gc-keep-derivations` is now an alias to `keep-derivations`.
-
-  - `gc-keep-outputs`  
-    *Deprecated:* `gc-keep-outputs` is now an alias to `keep-outputs`.
-
-  - `env-keep-derivations`  
-    *Deprecated:* `env-keep-derivations` is now an alias to `keep-env-derivations`.
-
-  - `extra-binary-caches`  
-    *Deprecated:* `extra-binary-caches` is now an alias to `extra-substituters`.
-
-  - `trusted-binary-caches`  
-    *Deprecated:* `trusted-binary-caches` is now an alias to `trusted-substituters`.
diff --git a/src/libexpr/eval.hh b/src/libexpr/eval.hh
index 5855b4ef2..1db3aa766 100644
--- a/src/libexpr/eval.hh
+++ b/src/libexpr/eval.hh
@@ -357,24 +357,57 @@ struct EvalSettings : Config
     Setting<bool> enableNativeCode{this, false, "allow-unsafe-native-code-during-evaluation",
         "Whether builtin functions that allow executing native code should be enabled."};
 
-    Setting<Strings> nixPath{this, getDefaultNixPath(), "nix-path",
-        "List of directories to be searched for <...> file references."};
-
-    Setting<bool> restrictEval{this, false, "restrict-eval",
-        "Whether to restrict file system access to paths in $NIX_PATH, "
-        "and network access to the URI prefixes listed in 'allowed-uris'."};
+    Setting<Strings> nixPath{
+        this, getDefaultNixPath(), "nix-path",
+        "List of directories to be searched for `<...>` file references."};
+
+    Setting<bool> restrictEval{
+        this, false, "restrict-eval",
+        R"(
+          If set to `true`, the Nix evaluator will not allow access to any
+          files outside of the Nix search path (as set via the `NIX_PATH`
+          environment variable or the `-I` option), or to URIs outside of
+          `allowed-uri`. The default is `false`.
+        )"};
 
     Setting<bool> pureEval{this, false, "pure-eval",
         "Whether to restrict file system and network access to files specified by cryptographic hash."};
 
-    Setting<bool> enableImportFromDerivation{this, true, "allow-import-from-derivation",
-        "Whether the evaluator allows importing the result of a derivation."};
+    Setting<bool> enableImportFromDerivation{
+        this, true, "allow-import-from-derivation",
+        R"(
+          By default, Nix allows you to `import` from a derivation, allowing
+          building at evaluation time. With this option set to false, Nix will
+          throw an error when evaluating an expression that uses this feature,
+          allowing users to ensure their evaluation will not require any
+          builds to take place.
+        )"};
 
     Setting<Strings> allowedUris{this, {}, "allowed-uris",
-        "Prefixes of URIs that builtin functions such as fetchurl and fetchGit are allowed to fetch."};
+        R"(
+          A list of URI prefixes to which access is allowed in restricted
+          evaluation mode. For example, when set to
+