Reconvert

doc/manual/src/SUMMARY.md

@@ -45,6 +45,8 @@
   - [Verifying Build Reproducibility](advanced-topics/diff-hook.md)
   - [Using the `post-build-hook`](advanced-topics/post-build-hook.md)
 - [Command Reference](command-ref/command-ref.md)
+  - [Common Options](command-ref/opt-common.md)
+  - [Common Environment Variables](command-ref/env-common.md)
   - [Utilities](command-ref/utilities.md)
     - [nix-copy-closure](command-ref/nix-copy-closure.md)
 - [Glossary](glossary.md)

doc/manual/src/advanced-topics/cores-vs-jobs.md

@@ -16,18 +16,18 @@ configuration trade-offs.
     -j`.
 
 The [???](#conf-cores) setting determines the value of
-NIX\_BUILD\_CORES. NIX\_BUILD\_CORES is equal to [???](#conf-cores),
+`NIX_BUILD_CORES`. `NIX_BUILD_CORES` is equal to [???](#conf-cores),
-unless [???](#conf-cores) equals `0`, in which case NIX\_BUILD\_CORES
+unless [???](#conf-cores) equals `0`, in which case `NIX_BUILD_CORES`
 will be the total number of cores in the system.
 
 The maximum number of consumed cores is a simple multiplication,
-[???](#conf-max-jobs) \* NIX\_BUILD\_CORES.
+[???](#conf-max-jobs) \* `NIX_BUILD_CORES`.
 
 The balance on how to set these two independent variables depends upon
 each builder's workload and hardware. Here are a few example scenarios
 on a machine with 24 cores:
 
-| [???](#conf-max-jobs) | [???](#conf-cores) | NIX\_BUILD\_CORES | Maximum Processes | Result                                                                                                                                                                                                                                                                                 |
+| [???](#conf-max-jobs) | [???](#conf-cores) | `NIX_BUILD_CORES` | Maximum Processes | Result                                                                                                                                                                                                                                                                                 |
 | --------------------- | ------------------ | ----------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 1                     | 24                 | 24                | 24                | One derivation will be built at a time, each one can use 24 cores. Undersold if a job can’t use 24 cores.                                                                                                                                                                              |
 | 4                     | 6                  | 6                 | 24                | Four derivations will be built at once, each given access to six cores.                                                                                                                                                                                                                |
@@ -38,5 +38,5 @@ on a machine with 24 cores:
 Balancing 24 Build Cores
 
 It is up to the derivations' build script to respect host's requested
-cores-per-build by following the value of the NIX\_BUILD\_CORES
+cores-per-build by following the value of the `NIX_BUILD_CORES`
 environment variable.

doc/manual/src/advanced-topics/distributed-builds.md

@@ -27,7 +27,7 @@ If you get the error
     bash: nix-store: command not found
     error: cannot connect to 'mac'
 
-then you need to ensure that the PATH of non-interactive login shells
+then you need to ensure that the `PATH` of non-interactive login shells
 contains Nix.
 
 > **Warning**

doc/manual/src/command-ref/command-ref.md

@@ -1,2 +1,4 @@
+# Command Reference
+
 This section lists commands and options that you can use when you
 work with Nix.

doc/manual/src/command-ref/env-common.md

@@ -0,0 +1,112 @@
+# Common Environment Variables
+
+Most Nix commands interpret the following environment variables:
+
+  - `IN_NIX_SHELL`  
+    Indicator that tells if the current environment was set up by
+    `nix-shell`. Since Nix 2.0 the values are `"pure"` and `"impure"`
+
+  - `NIX_PATH`  
+    A colon-separated list of directories used to look up Nix
+    expressions enclosed in angle brackets (i.e., `<path>`). For
+    instance, the value
+    
+        /home/eelco/Dev:/etc/nixos
+    
+    will cause Nix to look for paths relative to `/home/eelco/Dev` and
+    `/etc/nixos`, in this order. It is also possible to match paths
+    against a prefix. For example, the value
+    
+        nixpkgs=/home/eelco/Dev/nixpkgs-branch:/etc/nixos
+    
+    will cause Nix to search for `<nixpkgs/path>` in
+    `/home/eelco/Dev/nixpkgs-branch/path` and `/etc/nixos/nixpkgs/path`.
+    
+    If a path in the Nix search 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
+    consist of a single top-level directory. For example, setting
+    `NIX_PATH` to
+    
+        nixpkgs=https://github.com/NixOS/nixpkgs/archive/nixos-15.09.tar.gz
+    
+    tells Nix to download the latest revision in the Nixpkgs/NixOS 15.09
+    channel.
+    
+    A following shorthand can be used to refer to the official channels:
+    
+        nixpkgs=channel:nixos-15.09
+    
+    The search path can be extended using the `-I` option, which takes
+    precedence over `NIX_PATH`.
+
+  - `NIX_IGNORE_SYMLINK_STORE`  
+    Normally, the Nix store directory (typically `/nix/store`) is not
+    allowed to contain any symlink components. This is to prevent
+    “impure” builds. Builders sometimes “canonicalise” paths by
+    resolving all symlink components. Thus, builds on different machines
+    (with `/nix/store` resolving to different locations) could yield
+    different results. This is generally not a problem, except when
+    builds are deployed to machines where `/nix/store` resolves
+    differently. If you are sure that you’re not going to do that, you
+    can set `NIX_IGNORE_SYMLINK_STORE` to `1`.
+    
+    Note that if you’re symlinking the Nix store so that you can put it
+    on another file system than the root file system, on Linux you’re
+    better off using `bind` mount points, e.g.,
+    
+        $ mkdir /nix
+        $ mount -o bind /mnt/otherdisk/nix /nix
+    
+    Consult the mount 8 manual page for details.
+
+  - `NIX_STORE_DIR`  
+    Overrides the location of the Nix store (default `prefix/store`).
+
+  - `NIX_DATA_DIR`  
+    Overrides the location of the Nix static data directory (default
+    `prefix/share`).
+
+  - `NIX_LOG_DIR`  
+    Overrides the location of the Nix log directory (default
+    `prefix/var/log/nix`).
+
+  - `NIX_STATE_DIR`  
+    Overrides the location of the Nix state directory (default
+    `prefix/var/nix`).
+
+  - `NIX_CONF_DIR`  
+    Overrides the location of the system Nix configuration directory
+    (default `prefix/etc/nix`).
+
+  - `NIX_USER_CONF_FILES`  
+    Overrides the location of the user Nix configuration files to load
+    from (defaults to the XDG spec locations). The variable is treated
+    as a list separated by the `:` token.
+
+  - `TMPDIR`  
+    Use the specified directory to store temporary files. In particular,
+    this includes temporary build directories; these can take up
+    substantial amounts of disk space. The default is `/tmp`.
+
+  - `NIX_REMOTE`  
+    This variable should be set to `daemon` if you want to use the Nix
+    daemon to execute Nix operations. This is necessary in [multi-user
+    Nix installations](#ssec-multi-user). If the Nix daemon's Unix
+    socket is at some non-standard path, this variable should be set to
+    `unix://path/to/socket`. Otherwise, it should be left unset.
+
+  - `NIX_SHOW_STATS`  
+    If set to `1`, Nix will print some evaluation statistics, such as
+    the number of values allocated.
+
+  - `NIX_COUNT_CALLS`  
+    If set to `1`, Nix will print how often functions were called during
+    Nix expression evaluation. This is useful for profiling your Nix
+    expressions.
+
+  - `GC_INITIAL_HEAP_SIZE`  
+    If Nix has been configured to use the Boehm garbage collector, this
+    variable sets the initial size of the heap in bytes. It defaults to
+    384 MiB. Setting it to a low value reduces memory consumption, but
+    will increase runtime due to the overhead of garbage collection.

doc/manual/src/command-ref/opt-common.md

@@ -0,0 +1,221 @@
+# Common Options
+
+Most Nix commands accept the following command-line options:
+
+  - `--help`  
+    Prints out a summary of the command syntax and exits.
+
+  - `--version`  
+    Prints out the Nix version number on standard output and exits.
+
+  - `--verbose` / `-v`  
+    Increases the level of verbosity of diagnostic messages printed on
+    standard error. For each Nix operation, the information printed on
+    standard output is well-defined; any diagnostic information is
+    printed on standard error, never on standard output.
+    
+    This option may be specified repeatedly. Currently, the following
+    verbosity levels exist:
+    
+      - 0  
+        “Errors only”: only print messages explaining why the Nix
+        invocation failed.
+    
+      - 1  
+        “Informational”: print *useful* messages about what Nix is
+        doing. This is the default.
+    
+      - 2  
+        “Talkative”: print more informational messages.
+    
+      - 3  
+        “Chatty”: print even more informational messages.
+    
+      - 4  
+        “Debug”: print debug information.
+    
+      - 5  
+        “Vomit”: print vast amounts of debug information.
+
+  - `--quiet`  
+    Decreases the level of verbosity of diagnostic messages printed on
+    standard error. This is the inverse option to `-v` / `--verbose`.
+    
+    This option may be specified repeatedly. See the previous verbosity
+    levels list.
+
+  - `--log-format` format  
+    This option can be used to change the output of the log format, with
+    format being one of:
+    
+      - raw  
+        This is the raw format, as outputted by nix-build.
+    
+      - internal-json  
+        Outputs the logs in a structured manner. NOTE: the json schema
+        is not guarantees to be stable between releases.
+    
+      - bar  
+        Only display a progress bar during the builds.
+    
+      - bar-with-logs  
+        Display the raw logs, with the progress bar at the bottom.
+
+  - `--no-build-output` / `-Q`  
+    By default, output written by builders to standard output and
+    standard error is echoed to the Nix command's standard error. This
+    option suppresses this behaviour. Note that the builder's standard
+    output and error are always written to a log file in
+    `prefix/nix/var/log/nix`.
+
+  - `--max-jobs` / `-j` number  
+    Sets the maximum number of build jobs that Nix will perform in
+    parallel to the specified number. Specify `auto` to use the number
+    of CPUs in the system. The default is specified by the
+    [`max-jobs`](#conf-max-jobs) configuration setting, which itself
+    defaults to `1`. A higher value is useful on SMP systems or to
+    exploit I/O latency.
+    
+    Setting it to `0` disallows building on the local machine, which is
+    useful when you want builds to happen only on remote builders.
+
+  - `--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 defaults to the value of the
+    [`cores`](#conf-cores) configuration setting, if set, or `1`
+    otherwise. The value `0` means that the builder should use all
+    available CPU cores in the system.
+
+  - `--max-silent-time`  
+    Sets the maximum number of seconds that a builder can go without
+    producing any data on standard output or standard error. The default
+    is specified by the [`max-silent-time`](#conf-max-silent-time)
+    configuration setting. `0` means no time-out.
+
+  - `--timeout`  
+    Sets the maximum number of seconds that a builder can run. The
+    default is specified by the [`timeout`](#conf-timeout) configuration
+    setting. `0` means no timeout.
+
+  - `--keep-going` / `-k`  
+    Keep going in case of failed builds, to the greatest extent
+    possible. That is, if building an input of some derivation fails,
+    Nix will still build the other inputs, but not the derivation
+    itself. Without this option, Nix stops if any build fails (except
+    for builds of substitutes), possibly killing builds in progress (in
+    case of parallel or distributed builds).
+
+  - `--keep-failed` / `-K`  
+    Specifies that in case of a build failure, the temporary directory
+    (usually in `/tmp`) in which the build takes place should not be
+    deleted. The path of the build directory is printed as an
+    informational message.
+
+  - `--fallback`  
+    Whenever Nix attempts to build a derivation for which substitutes
+    are known for each output path, but realising the output paths
+    through the substitutes fails, fall back on building the derivation.
+    
+    The most common scenario in which this is useful is when we have
+    registered substitutes in order to perform binary distribution from,
+    say, a network repository. If the repository is down, the
+    realisation of the derivation will fail. When this option is
+    specified, Nix will build the derivation instead. Thus, installation
+    from binaries falls back on installation from source. This option is
+    not the default since it is generally not desirable for a transient
+    failure in obtaining the substitutes to lead to a full build from
+    source (with the related consumption of resources).
+
+  - `--no-build-hook`  
+    Disables the build hook mechanism. This allows to ignore remote
+    builders if they are setup on the machine.
+    
+    It's useful in cases where the bandwidth between the client and the
+    remote builder is too low. In that case it can take more time to
+    upload the sources to the remote builder and fetch back the result
+    than to do the computation locally.
+
+  - `--readonly-mode`  
+    When this option is used, no attempt is made to open the Nix
+    database. Most Nix operations do need database access, so those
+    operations will fail.
+
+  - `--arg` name value  
+    This option is accepted by `nix-env`, `nix-instantiate`, `nix-shell`
+    and `nix-build`. When evaluating Nix expressions, the expression
+    evaluator will automatically try to call functions that it
+    encounters. It can automatically call functions for which every
+    argument has a [default value](#ss-functions) (e.g., `{ argName ?
+            defaultValue }:
+            ...`). With `--arg`, you can also call functions that have arguments
+    without a default value (or override a default value). That is, if
+    the evaluator encounters a function with an argument named name, it
+    will call it with value value.
+    
+    For instance, the top-level `default.nix` in Nixpkgs is actually a
+    function:
+    
+        { # The system (e.g., `i686-linux') for which to build the packages.
+          system ? builtins.currentSystem
+          ...
+        }: ...
+    
+    So if you call this Nix expression (e.g., when you do `nix-env -i
+    pkgname`), the function will be called automatically using the value
+    [`builtins.currentSystem`](#builtin-currentSystem) for the `system`
+    argument. You can override this using `--arg`, e.g., `nix-env -i
+            pkgname --arg system
+            \"i686-freebsd\"`. (Note that since the argument is a Nix string
+    literal, you have to escape the quotes.)
+
+  - `--argstr` name value  
+    This option is like `--arg`, only the value is not a Nix expression
+    but a string. So instead of `--arg system \"i686-linux\"` (the outer
+    quotes are to keep the shell happy) you can say `--argstr system
+            i686-linux`.
+
+  - `--attr` / `-A` attrPath  
+    Select an attribute from the top-level Nix expression being
+    evaluated. (`nix-env`, `nix-instantiate`, `nix-build` and
+    `nix-shell` only.) The *attribute path* attrPath is a sequence of
+    attribute names separated by dots. For instance, given a top-level
+    Nix expression e, the attribute path `xorg.xorgserver` would cause
+    the expression `e.xorg.xorgserver` to be used. See [`nix-env
+            --install`](#refsec-nix-env-install-examples) for some concrete
+    examples.
+    
+    In addition to attribute names, you can also specify array indices.
+    For instance, the attribute path `foo.3.bar` selects the `bar`
+    attribute of the fourth element of the array in the `foo` attribute
+    of the top-level expression.
+
+  - `--expr` / `-E`  
+    Interpret the command line arguments as a list of Nix expressions to
+    be parsed and evaluated, rather than as a list of file names of Nix
+    expressions. (`nix-instantiate`, `nix-build` and `nix-shell` only.)
+    
+    For `nix-shell`, this option is commonly used to give you a shell in
+    which you can build the packages returned by the expression. If you
+    want to get a shell which contain the *built* packages ready for
+    use, give your expression to the `nix-shell -p` convenience flag
+    instead.
+
+  - `-I` path  
+    Add a path to the Nix expression search path. This option may be
+    given multiple times. See the NIX\_PATH\</literal\> environment
+    variable for information on the semantics of the Nix search path.
+    Paths added through `-I` take precedence over `NIX_PATH`.
+
+  - `--option` name value  
+    Set the Nix configuration option name to value. This overrides
+    settings in the Nix configuration file (see nix.conf5).
+
+  - `--repair`  
+    Fix corrupted or missing store paths by redownloading or rebuilding
+    them. Note that this is slow because it requires computing a
+    cryptographic hash of the contents of every path in the closure of
+    the build. Also note the warning under `nix-store --repair-path`.

doc/manual/src/expressions/advanced-attributes.md

@@ -87,7 +87,7 @@ Derivations can declare some infrequently used optional attributes.
         impureEnvVars = [ "http_proxy" "https_proxy" ... ];
     
     to make it use the proxy server configuration specified by the user
-    in the environment variables http\_proxy and friends.
+    in the environment variables `http_proxy` and friends.
     
     This attribute is only allowed in [fixed-output
     derivations](#fixed-output-drvs), where impurities such as these are
@@ -201,15 +201,15 @@ Derivations can declare some infrequently used optional attributes.
         
     ```
     
-    then when the builder runs, the environment variable bigPath will
+    then when the builder runs, the environment variable `bigPath` will
     contain the absolute path to a temporary file containing `a very
     long
                     string`. That is, for any attribute x listed in `passAsFile`, Nix
-    will pass an environment variable xPath holding the path of the file
+    will pass an environment variable `xPath` holding the path of the
-    containing the value of attribute x. This is useful when you need to
+    file containing the value of attribute x. This is useful when you
-    pass large strings to a builder, since most operating systems impose
+    need to pass large strings to a builder, since most operating
-    a limit on the size of the environment (typically, a few hundred
+    systems impose a limit on the size of the environment (typically, a
-    kilobyte).
+    few hundred kilobyte).
 
   - `preferLocalBuild`  
     If this attribute is set to `true` and [distributed building is

doc/manual/src/expressions/build-script.md

@@ -19,29 +19,29 @@ what a builder does. It performs the following steps:
 
   - When Nix runs a builder, it initially completely clears the
     environment (except for the attributes declared in the derivation).
-    For instance, the PATH variable is empty\[1\]. This is done to
+    For instance, the `PATH` variable is empty\[1\]. This is done to
     prevent undeclared inputs from being used in the build process. If
-    for example the PATH contained `/usr/bin`, then you might
+    for example the `PATH` contained `/usr/bin`, then you might
     accidentally use `/usr/bin/gcc`.
     
     So the first step is to set up the environment. This is done by
     calling the `setup` script of the standard environment. The
-    environment variable stdenv points to the location of the standard
+    environment variable `stdenv` points to the location of the standard
     environment being used. (It wasn't specified explicitly as an
     attribute in [???](#ex-hello-nix), but `mkDerivation` adds it
     automatically.)
 
   - Since Hello needs Perl, we have to make sure that Perl is in the
-    PATH. The perl environment variable points to the location of the
+    `PATH`. The `perl` environment variable points to the location of
-    Perl package (since it was passed in as an attribute to the
+    the Perl package (since it was passed in as an attribute to the
     derivation), so `$perl/bin` is the directory containing the Perl
     interpreter.
 
   - Now we have to unpack the sources. The `src` attribute was bound to
     the result of fetching the Hello source tarball from the network, so
-    the src environment variable points to the location in the Nix store
+    the `src` environment variable points to the location in the Nix
-    to which the tarball was downloaded. After unpacking, we `cd` to the
+    store to which the tarball was downloaded. After unpacking, we `cd`
-    resulting source directory.
+    to the resulting source directory.
     
     The whole build is performed in a temporary directory created in
     `/tmp`, by the way. This directory is removed after the builder
@@ -55,13 +55,13 @@ what a builder does. It performs the following steps:
     separate location in the Nix store, for instance
     `/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix
     computes this path by cryptographically hashing all attributes of
-    the derivation. The path is passed to the builder through the out
+    the derivation. The path is passed to the builder through the `out`
     environment variable. So here we give `configure` the parameter
     `--prefix=$out` to cause Hello to be installed in the expected
     location.
 
   - Finally we build Hello (`make`) and install it into the location
-    specified by out (`make install`).
+    specified by `out` (`make install`).
 
 If you are wondering about the absence of error checking on the result
 of various commands called in the builder: this is because the shell

doc/manual/src/expressions/builder-syntax.md

@@ -19,29 +19,29 @@ what a builder does. It performs the following steps:
 
   - When Nix runs a builder, it initially completely clears the
     environment (except for the attributes declared in the derivation).
-    For instance, the PATH variable is empty\[1\]. This is done to
+    For instance, the `PATH` variable is empty\[1\]. This is done to
     prevent undeclared inputs from being used in the build process. If
-    for example the PATH contained `/usr/bin`, then you might
+    for example the `PATH` contained `/usr/bin`, then you might
     accidentally use `/usr/bin/gcc`.
     
     So the first step is to set up the environment. This is done by
     calling the `setup` script of the standard environment. The
-    environment variable stdenv points to the location of the standard
+    environment variable `stdenv` points to the location of the standard
     environment being used. (It wasn't specified explicitly as an
     attribute in [???](#ex-hello-nix), but `mkDerivation` adds it
     automatically.)
 
   - Since Hello needs Perl, we have to make sure that Perl is in the
-    PATH. The perl environment variable points to the location of the
+    `PATH`. The `perl` environment variable points to the location of
-    Perl package (since it was passed in as an attribute to the
+    the Perl package (since it was passed in as an attribute to the
     derivation), so `$perl/bin` is the directory containing the Perl
     interpreter.
 
   - Now we have to unpack the sources. The `src` attribute was bound to
     the result of fetching the Hello source tarball from the network, so
-    the src environment variable points to the location in the Nix store
+    the `src` environment variable points to the location in the Nix
-    to which the tarball was downloaded. After unpacking, we `cd` to the
+    store to which the tarball was downloaded. After unpacking, we `cd`
-    resulting source directory.
+    to the resulting source directory.
     
     The whole build is performed in a temporary directory created in
     `/tmp`, by the way. This directory is removed after the builder
@@ -55,13 +55,13 @@ what a builder does. It performs the following steps:
     separate location in the Nix store, for instance
     `/nix/store/9a54ba97fb71b65fda531012d0443ce2-hello-2.1.1`. Nix
     computes this path by cryptographically hashing all attributes of
-    the derivation. The path is passed to the builder through the out
+    the derivation. The path is passed to the builder through the `out`
     environment variable. So here we give `configure` the parameter
     `--prefix=$out` to cause Hello to be installed in the expected
     location.
 
   - Finally we build Hello (`make`) and install it into the location
-    specified by out (`make install`).
+    specified by `out` (`make install`).
 
 If you are wondering about the absence of error checking on the result
 of various commands called in the builder: this is because the shell

doc/manual/src/expressions/derivations.md

@@ -83,32 +83,32 @@ as a command-line argument. See the Nixpkgs manual for details.
 The builder is executed as follows:
 
   - A temporary directory is created under the directory specified by
-    TMPDIR (default `/tmp`) where the build will take place. The current
+    `TMPDIR` (default `/tmp`) where the build will take place. The
-    directory is changed to this directory.
+    current directory is changed to this directory.
 
   - The environment is cleared and set to the derivation attributes, as
     specified above.
 
   - In addition, the following variables are set:
     
-      - NIX\_BUILD\_TOP contains the path of the temporary directory for
+      - `NIX_BUILD_TOP` contains the path of the temporary directory for
         this build.
     
-      - Also, TMPDIR, TEMPDIR, TMP, TEMP are set to point to the
+      - Also, `TMPDIR`, `TEMPDIR`, `TMP`, `TEMP` are set to point to the
         temporary directory. This is to prevent the builder from
         accidentally writing temporary files anywhere else. Doing so
         might cause interference by other processes.
     
-      - PATH is set to `/path-not-set` to prevent shells from
+      - `PATH` is set to `/path-not-set` to prevent shells from
         initialising it to their built-in default value.
     
-      - HOME is set to `/homeless-shelter` to prevent programs from
+      - `HOME` is set to `/homeless-shelter` to prevent programs from
         using `/etc/passwd` or the like to find the user's home
-        directory, which could cause impurity. Usually, when HOME is
+        directory, which could cause impurity. Usually, when `HOME` is
         set, it is used as the location of the home directory, even if
         it points to a non-existent path.
     
-      - NIX\_STORE is set to the path of the top-level Nix store
+      - `NIX_STORE` is set to the path of the top-level Nix store
         directory (typically, `/nix/store`).
     
       - For each output declared in `outputs`, the corresponding

doc/manual/src/expressions/generic-builder.md

@@ -22,9 +22,9 @@ build facilities in shown in [example\_title](#ex-hello-builder2).
     
     genericBuild 
 
-  - The buildInputs variable tells `setup` to use the indicated packages
+  - The `buildInputs` variable tells `setup` to use the indicated
-    as “inputs”. This means that if a package provides a `bin`
+    packages as “inputs”. This means that if a package provides a `bin`
-    subdirectory, it's added to PATH; if it has a `include`
+    subdirectory, it's added to `PATH`; if it has a `include`
     subdirectory, it's added to GCC's header search path; and so
     on.\[1\]
 
@@ -37,7 +37,7 @@ build facilities in shown in [example\_title](#ex-hello-builder2).
     It can be customised in many ways; see the Nixpkgs manual for
     details.
 
-Discerning readers will note that the buildInputs could just as well
+Discerning readers will note that the `buildInputs` could just as well
 have been set in the Nix expression, like this:
 
 ``` 
@@ -57,5 +57,6 @@ entirely.
 1.  How does it work? `setup` tries to source the file
     `pkg/nix-support/setup-hook` of all dependencies. These “setup
     hooks” can then set up whatever environment variables they want;
-    for instance, the setup hook for Perl sets the PERL5LIB environment
+    for instance, the setup hook for Perl sets the `PERL5LIB`
-    variable to contain the `lib/site_perl` directories of all inputs.
+    environment variable to contain the `lib/site_perl` directories of
+    all inputs.

doc/manual/src/expressions/language-values.md

@@ -120,8 +120,8 @@ Nix has the following basic data types:
     
     Paths can also be specified between angle brackets, e.g.
     `<nixpkgs>`. This means that the directories listed in the
-    environment variable NIX\_PATH will be searched for the given file
+    environment variable NIX\_PATH\</literal\> will be searched for the
-    or directory name.
+    given file or directory name.
 
   - *Booleans* with values `true` and `false`.
 

doc/manual/src/expressions/simple-building-testing.md

@@ -32,7 +32,7 @@ of the build will be safely kept on your system. You can use
 
 Nix has transactional semantics. Once a build finishes successfully, Nix
 makes a note of this in its database: it registers that the path denoted
-by out is now “valid”. If you try to build the derivation again, Nix
+by `out` is now “valid”. If you try to build the derivation again, Nix
 will see that the path is already valid and finish immediately. If a
 build fails, either because it returns a non-zero exit code, because Nix
 or the builder are killed, or because the machine crashes, then the

doc/manual/src/installation/env-variables.md

@@ -1,7 +1,7 @@
 # Environment Variables
 
 To use Nix, some environment variables should be set. In particular,
-PATH should contain the directories `prefix/bin` and
+`PATH` should contain the directories `prefix/bin` and
 `~/.nix-profile/bin`. The first directory contains the Nix tools
 themselves, while `~/.nix-profile` is a symbolic link to the current
 *user environment* (an automatically generated package consisting of
@@ -12,13 +12,13 @@ this:
 
     source prefix/etc/profile.d/nix.sh
 
-# NIX\_SSL\_CERT\_FILE
+# `NIX_SSL_CERT_FILE`
 
 If you need to specify a custom certificate bundle to account for an
 HTTPS-intercepting man in the middle proxy, you must specify the path to
-the certificate bundle in the environment variable NIX\_SSL\_CERT\_FILE.
+the certificate bundle in the environment variable `NIX_SSL_CERT_FILE`.
 
-If you don't specify a NIX\_SSL\_CERT\_FILE manually, Nix will install
+If you don't specify a `NIX_SSL_CERT_FILE` manually, Nix will install
 and use its own certificate bundle.
 
 Set the environment variable and install Nix
@@ -36,7 +36,7 @@ In the shell profile and rc files (for example, `/etc/bashrc`,
 > You must not add the export and then do the install, as the Nix
 > installer will detect the presense of Nix configuration, and abort.
 
-## NIX\_SSL\_CERT\_FILE with macOS and the Nix daemon
+## `NIX_SSL_CERT_FILE` with macOS and the Nix daemon
 
 On macOS you must specify the environment variable for the Nix daemon
 service, then restart it:

doc/manual/src/installation/installing-binary.md

@@ -34,8 +34,8 @@ manually create `/nix` first as root, e.g.:
 The install script will modify the first writable file from amongst
 `.bash_profile`, `.bash_login` and `.profile` to source
 `~/.nix-profile/etc/profile.d/nix.sh`. You can set the
-NIX\_INSTALLER\_NO\_MODIFY\_PROFILE environment variable before
+`NIX_INSTALLER_NO_MODIFY_PROFILE` environment variable before executing
-executing the install script to disable this behaviour.
+the install script to disable this behaviour.
 
 You can uninstall Nix simply by running:
 

doc/manual/src/installation/multi-user.md

@@ -43,7 +43,7 @@ The [Nix daemon](#sec-nix-daemon) should be started as follows (as
 You’ll want to put that line somewhere in your system’s boot scripts.
 
 To let unprivileged users use the daemon, they should set the
-[NIX\_REMOTE environment variable](#envar-remote) to `daemon`. So you
+[`NIX_REMOTE` environment variable](#envar-remote) to `daemon`. So you
 should put a line like
 
     export NIX_REMOTE=daemon

doc/manual/src/package-management/basic-package-mgmt.md

@@ -8,10 +8,10 @@ In Nix, different users can have different “views” on the set of
 installed applications. That is, there might be lots of applications
 present on the system (possibly in many different versions), but users
 can have a specific selection of those active — where “active” just
-means that it appears in a directory in the user’s PATH. Such a view on
+means that it appears in a directory in the user’s `PATH`. Such a view
-the set of installed applications is called a *user environment*, which
+on the set of installed applications is called a *user environment*,
-is just a directory tree consisting of symlinks to the files of the
+which is just a directory tree consisting of symlinks to the files of
-active applications.
+the active applications.
 
 Components are installed from a set of *Nix expressions* that tell Nix
 how to build those packages, including, if necessary, their

doc/manual/src/package-management/profiles.md

@@ -24,9 +24,9 @@ Of course, you wouldn’t want to type
     $ /nix/store/dpmvp969yhdq...-subversion-1.1.3/bin/svn
 
 every time you want to run Subversion. Of course we could set up the
-PATH environment variable to include the `bin` directory of every
+`PATH` environment variable to include the `bin` directory of every
 package we want to use, but this is not very convenient since changing
-PATH doesn’t take effect for already existing processes. The solution
+`PATH` doesn’t take effect for already existing processes. The solution
 Nix uses is to create directory trees of symlinks to *activated*
 packages. These are called *user environments* and they are packages
 themselves (though automatically generated by `nix-env`), so they too
@@ -89,9 +89,9 @@ also see all available generations:
     $ nix-env --list-generations
 
 You generally wouldn’t have `/nix/var/nix/profiles/some-profile/bin` in
-your PATH. Rather, there is a symlink `~/.nix-profile` that points to
+your `PATH`. Rather, there is a symlink `~/.nix-profile` that points to
 your current profile. This means that you should put
-`~/.nix-profile/bin` in your PATH (and indeed, that’s what the
+`~/.nix-profile/bin` in your `PATH` (and indeed, that’s what the
 initialisation script `/nix/etc/profile.d/nix.sh` does). This makes it
 easier to switch to a different profile. You can do that using the
 command `nix-env --switch-profile`:

doc/manual/src/release-notes/rl-0.10.md

@@ -124,8 +124,8 @@
             URL` allows a package to be installed directly from the given URL.
 
   - Nix now works behind an HTTP proxy server; just set the standard
-    environment variables http\_proxy, https\_proxy, ftp\_proxy or
+    environment variables `http_proxy`, `https_proxy`, `ftp_proxy` or
-    all\_proxy appropriately. Functions such as `fetchurl` in Nixpkgs
+    `all_proxy` appropriately. Functions such as `fetchurl` in Nixpkgs
     also respect these variables.
 
   - `nix-build -o

doc/manual/src/release-notes/rl-0.12.md

@@ -33,7 +33,7 @@
     (remote) Nix stores mounted somewhere in the filesystem. For
     instance, you can speed up an installation by mounting some remote
     Nix store that already has the packages in question via NFS or
-    `sshfs`. The environment variable NIX\_OTHER\_STORES specifies the
+    `sshfs`. The environment variable `NIX_OTHER_STORES` specifies the
     locations of the remote Nix directories, e.g. `/mnt/remote-fs/nix`.
 
   - New `nix-store` operations `--dump-db` and `--load-db` to dump and
@@ -111,7 +111,7 @@
         (integer multiplication), `builtins.div` (integer division).
 
   - `nix-prefetch-url` now supports `mirror://` URLs, provided that the
-    environment variable NIXPKGS\_ALL points at a Nixpkgs tree.
+    environment variable `NIXPKGS_ALL` points at a Nixpkgs tree.
 
   - Removed the commands `nix-pack-closure` and `nix-unpack-closure`.
     You can do almost the same thing but much more efficiently by doing

doc/manual/src/release-notes/rl-0.16.md

@@ -14,7 +14,7 @@ This release has the following improvements:
     performed in parallel was not configurable. Nix now has an option
     `--cores
                             N` as well as a configuration setting `build-cores =
-                            N` that causes the environment variable NIX\_BUILD\_CORES to be set
+                            N` that causes the environment variable `NIX_BUILD_CORES` to be set
     to N when the builder is invoked. The builder can use this at its
     discretion to perform a parallel build, e.g., by calling `make -j
                             N`. In Nixpkgs, this can be enabled on a per-package basis by

doc/manual/src/release-notes/rl-1.0.md

@@ -14,7 +14,7 @@ release. Here are the most significant:
     significant speedup.
 
   - Nix now has an search path for expressions. The search path is set
-    using the environment variable NIX\_PATH and the `-I` command line
+    using the environment variable `NIX_PATH` and the `-I` command line
     option. In Nix expressions, paths between angle brackets are used to
     specify files that must be looked up in the search path. For
     instance, the expression `<nixpkgs/default.nix>` looks for a file

doc/manual/src/release-notes/rl-1.2.md

@@ -77,7 +77,7 @@ This release has the following improvements and changes:
     about twice as fast.
 
   - Basic Nix expression evaluation profiling: setting the environment
-    variable NIX\_COUNT\_CALLS to `1` will cause Nix to print how many
+    variable `NIX_COUNT_CALLS` to `1` will cause Nix to print how many
     times each primop or function was executed.
 
   - New primops: `concatLists`, `elem`, `elemAt` and `filter`.

doc/manual/src/release-notes/rl-1.6.md

@@ -13,7 +13,7 @@ features:
     get an environment that more closely corresponds to the “real” Nix
     build.
 
-  - `nix-shell` now sets the shell prompt (PS1) to ensure that Nix
+  - `nix-shell` now sets the shell prompt (`PS1`) to ensure that Nix
     shells are distinguishable from your regular shells.
 
   - `nix-env` no longer requires a `*` argument to match all packages,

doc/manual/src/release-notes/rl-1.8.md

@@ -76,7 +76,7 @@
     them anyway.
 
   - Various commands now automatically pipe their output into the pager
-    as specified by the PAGER environment variable.
+    as specified by the `PAGER` environment variable.
 
   - Several improvements to reduce memory consumption in the evaluator.
 

doc/manual/src/release-notes/rl-1.9.md

@@ -39,8 +39,8 @@ features:
         This builds GNU Hello from the latest revision of the Nixpkgs
         master branch.
     
-      - In the Nix search path (as specified via NIX\_PATH or `-I`). For
+      - In the Nix search path (as specified via `NIX_PATH` or `-I`).
-        example, to start a shell containing the Pan package from a
+        For example, to start a shell containing the Pan package from a
         specific version of Nixpkgs:
         
             $ nix-shell -p pan -I nixpkgs=https://github.com/NixOS/nixpkgs-channels/archive/8a3eea054838b55aca962c3fbde9c83c102b8bf2.tar.gz
@@ -124,8 +124,8 @@ features:
   - `nix-env` now only creates a new “generation” symlink in
     `/nix/var/nix/profiles` if something actually changed.
 
-  - The environment variable NIX\_PAGER can now be set to override
+  - The environment variable `NIX_PAGER` can now be set to override
-    PAGER. You can set it to `cat` to disable paging for Nix commands
+    `PAGER`. You can set it to `cat` to disable paging for Nix commands
     only.
 
   - Failing `<...>` lookups now show position information.

doc/manual/src/release-notes/rl-2.0.md

@@ -18,7 +18,7 @@ The following incompatible changes have been made:
       - `bspatch`
 
   - The “copy from other stores” substituter mechanism
-    (`copy-from-other-stores` and the NIX\_OTHER\_STORES environment
+    (`copy-from-other-stores` and the `NIX_OTHER_STORES` environment
     variable) has been removed. It was primarily used by the NixOS
     installer to copy available paths from the installation medium. The
     replacement is to use a chroot store as a substituter (e.g.
@@ -233,7 +233,7 @@ This release has the following new features:
         store, the latter via the Nix daemon. You can use `auto` or the
         empty string to auto-select a local or daemon store depending on
         whether you have write permission to the Nix store. It is no
-        longer necessary to set the NIX\_REMOTE environment variable to
+        longer necessary to set the `NIX_REMOTE` environment variable to
         use the Nix daemon.
         
         As noted above, `LocalStore` now supports chroot builds,
@@ -296,7 +296,7 @@ This release has the following new features:
         [now](https://github.com/NixOS/nix/commit/eba840c8a13b465ace90172ff76a0db2899ab11b)
         use `/build` instead of `/tmp` as the temporary build directory.
         This fixes potential security problems when a build accidentally
-        stores its TMPDIR in some security-sensitive place, such as an
+        stores its `TMPDIR` in some security-sensitive place, such as an
         RPATH.
 
   - *Pure evaluation mode*. With the `--pure-eval` flag, Nix enables a
@@ -334,8 +334,8 @@ This release has the following new features:
     using the Nix daemon, you can now just specify a remote build
     machine on the command line, e.g. `--option builders
                     'ssh://my-mac x86_64-darwin'`. The environment variable
-    NIX\_BUILD\_HOOK has been removed and is no longer needed. The
+    `NIX_BUILD_HOOK` has been removed and is no longer needed. The
-    environment variable NIX\_REMOTE\_SYSTEMS is still supported for
+    environment variable `NIX_REMOTE_SYSTEMS` is still supported for
     compatibility, but it is also possible to specify builders in
     `nix.conf` by setting the option `builders =
                     @path`.
@@ -353,7 +353,7 @@ This release has the following new features:
     Nixpkgs provides `lib.inNixShell` to check this variable during
     evaluation.
 
-  - NIX\_PATH is now lazy, so URIs in the path are only downloaded if
+  - `NIX_PATH` is now lazy, so URIs in the path are only downloaded if
     they are needed for evaluation.
 
   - You can now use <channel:> as a short-hand for
@@ -406,7 +406,7 @@ This release has the following new features:
     non-standard base-32.
 
   - `nix-shell` now uses `bashInteractive` from Nixpkgs, rather than the
-    `bash` command that happens to be in the caller’s PATH. This is
+    `bash` command that happens to be in the caller’s `PATH`. This is
     especially important on macOS where the `bash` provided by the
     system is seriously outdated and cannot execute `stdenv`’s setup
     script.
@@ -433,7 +433,7 @@ The Nix language has the following new features:
     
         configureFlags = "--prefix=${placeholder "out"} --includedir=${placeholder "dev"}";
     
-    will cause the configureFlags environment variable to contain the
+    will cause the `configureFlags` environment variable to contain the
     actual store paths corresponding to the `out` and `dev` outputs.
 
 The following builtin functions are new or extended:
@@ -481,23 +481,23 @@ The Nix build environment has the following changes:
     be passed to builders in a non-lossy way. If the special attribute
     `__structuredAttrs` is set to `true`, the other derivation
     attributes are serialised in JSON format and made available to the
-    builder via the file .attrs.json in the builder’s temporary
+    builder via the file `.attrs.json` in the builder’s temporary
     directory. This obviates the need for `passAsFile` since JSON files
     have no size restrictions, unlike process environments.
     
     [As a convenience to Bash
     builders](https://github.com/NixOS/nix/commit/2d5b1b24bf70a498e4c0b378704cfdb6471cc699),
-    Nix writes a script named .attrs.sh to the builder’s directory that
+    Nix writes a script named `.attrs.sh` to the builder’s directory
-    initialises shell variables corresponding to all attributes that are
+    that initialises shell variables corresponding to all attributes
-    representable in Bash. This includes non-nested (associative)
+    that are representable in Bash. This includes non-nested
-    arrays. For example, the attribute `hardening.format =
+    (associative) arrays. For example, the attribute `hardening.format =
                     true` ends up as the Bash associative array element
     `${hardening[format]}`.
 
   - Builders can
     [now](https://github.com/NixOS/nix/commit/88e6bb76de5564b3217be9688677d1c89101b2a3)
     communicate what build phase they are in by writing messages to the
-    file descriptor specified in NIX\_LOG\_FD. The current phase is
+    file descriptor specified in `NIX_LOG_FD`. The current phase is
     shown by the `nix` progress indicator.
 
   - In Linux sandbox builds, we

doc/manual/src/release-notes/rl-2.2.md

@@ -69,7 +69,7 @@ This is primarily a bug fix release. It also has the following changes:
   - Integers are now 64 bits on all platforms.
 
   - The evaluator now prints profiling statistics (enabled via the
-    NIX\_SHOW\_STATS and NIX\_COUNT\_CALLS environment variables) in
+    `NIX_SHOW_STATS` and `NIX_COUNT_CALLS` environment variables) in
     JSON format.
 
   - The option `--xml` in `nix-store

doc/manual/src/release-notes/rl-2.3.md

@@ -25,7 +25,7 @@ It also has the following changes:
     line in the progress bar. To distinguish between concurrent builds,
     log lines are prefixed by the name of the package.
 
-  - Builds are now executed in a pseudo-terminal, and the TERM
+  - Builds are now executed in a pseudo-terminal, and the `TERM`
     environment variable is set to `xterm-256color`. This allows many
     programs (e.g. `gcc`, `clang`, `cmake`) to print colorized log
     output.