Get rid of footnotes

Markdown doesn't support them.

doc/manual/command-ref/nix-instantiate.xml

@@ -106,7 +106,7 @@ input.</para>
   <varlistentry><term><option>--find-file</option></term>
 
     <listitem><para>Look up the given files in Nix’s search path (as
-    specified by the <envar linkend="env-NIX_PATH">NIX_PATH</literal>
+    specified by the <literal linkend="env-NIX_PATH">NIX_PATH</literal>
     environment variable).  If found, print the corresponding absolute
     paths on standard output.  For instance, if
     <literal>NIX_PATH</literal> is

doc/manual/command-ref/opt-common.xml

@@ -369,7 +369,7 @@
 <varlistentry xml:id="opt-I"><term><option>-I</option> <emphasis>path</emphasis></term>
 
   <listitem><para>Add a path to the Nix expression search path.  This
-  option may be given multiple times.  See the <envar
+  option may be given multiple times.  See the <literal
   linkend="env-NIX_PATH">NIX_PATH</literal> environment variable for
   information on the semantics of the Nix search path.  Paths added
   through <option>-I</option> take precedence over

doc/manual/expressions/build-script.xml

@@ -33,13 +33,10 @@ steps:</para>
 
     <para>When Nix runs a builder, it initially completely clears the
     environment (except for the attributes declared in the
-    derivation).  For instance, the <literal>PATH</literal> variable is
-    empty<footnote><para>Actually, it's initialised to
-    <filename>/path-not-set</filename> to prevent Bash from setting it
-    to a default value.</para></footnote>.  This is done to prevent
-    undeclared inputs from being used in the build process.  If for
-    example the <literal>PATH</literal> contained
-    <filename>/usr/bin</filename>, then you might accidentally use
+    derivation).  This is done to prevent undeclared inputs from being
+    used in the build process. If for example the
+    <literal>PATH</literal> contained <filename>/usr/bin</filename>,
+    then you might accidentally use
     <filename>/usr/bin/gcc</filename>.</para>
 
     <para>So the first step is to set up the environment.  This is

doc/manual/expressions/derivations.xml

@@ -13,16 +13,15 @@ of which specify the inputs of the build.</para>
 
 <itemizedlist>
 
-  <listitem xml:id="attr-system"><para>There must be an attribute named
-  <varname>system</varname> whose value must be a string specifying a
-  Nix platform identifier, such as <literal>"i686-linux"</literal> or
-  <literal>"x86_64-darwin"</literal><footnote><para>To figure out
-  your platform identifier, look at the line <quote>Checking for the
-  canonical Nix system name</quote> in the output of Nix's
-  <filename>configure</filename> script.</para></footnote> The build
-  can only be performed on a machine and operating system matching the
-  platform identifier.  (Nix can automatically forward builds for
-  other platforms by forwarding them to other machines; see <xref
+  <listitem xml:id="attr-system"><para>There must be an attribute
+  named <varname>system</varname> whose value must be a string
+  specifying a Nix system type, such as
+  <literal>"i686-linux"</literal> or
+  <literal>"x86_64-darwin"</literal>. (To figure out your system type,
+  run <literal>nix -vv --version</literal>.) The build can only be
+  performed on a machine and operating system matching the system
+  type.  (Nix can automatically forward builds for other platforms by
+  forwarding them to other machines; see <xref
   linkend='chap-distributed-builds' />.)</para></listitem>
 
   <listitem><para>There must be an attribute named

doc/manual/expressions/generic-builder.xml

@@ -42,14 +42,14 @@ genericBuild ③</programlisting>
     <filename>bin</filename> subdirectory, it's added to
     <literal>PATH</literal>; if it has a <filename>include</filename>
     subdirectory, it's added to GCC's header search path; and so
-    on.<footnote><para>How does it work? <filename>setup</filename>
-    tries to source the file
+    on. (This is implemented in a modular way:
+    <filename>setup</filename> tries to source the file
     <filename><emphasis>pkg</emphasis>/nix-support/setup-hook</filename>
     of all dependencies.  These “setup hooks” can then set up whatever
     environment variables they want; for instance, the setup hook for
     Perl sets the <literal>PERL5LIB</literal> environment variable to
     contain the <filename>lib/site_perl</filename> directories of all
-    inputs.</para></footnote>
+    inputs.)
     </para>
 
   </listitem>

doc/manual/expressions/language-constructs.xml

@@ -26,7 +26,7 @@ is, in a normal (non-recursive) set, attributes are not added to the
 lexical scope; in a recursive set, they are.</para>
 
 <para>Recursive sets of course introduce the danger of infinite
-recursion.  For example,
+recursion.  For example, the expression
 
 <programlisting>
 rec {
@@ -34,9 +34,8 @@ rec {
   y = x;
 }.x</programlisting>
 
-does not terminate<footnote><para>Actually, Nix detects infinite
-recursion in this case and aborts (<quote>infinite recursion
-encountered</quote>).</para></footnote>.</para>
+will crash with an <literal>infinite recursion encountered</literal>
+error message.</para>
 
 </section>
 

doc/manual/expressions/language-values.xml

@@ -154,11 +154,10 @@ stdenv.mkDerivation {
 
   <listitem><para><emphasis>Paths</emphasis>, e.g.,
   <filename>/bin/sh</filename> or <filename>./builder.sh</filename>.
-  A path must contain at least one slash to be recognised as such; for
-  instance, <filename>builder.sh</filename> is not a
-  path<footnote><para>It's parsed as an expression that selects the
-  attribute <varname>sh</varname> from the variable
-  <varname>builder</varname>.</para></footnote>.  If the file name is
+  A path must contain at least one slash to be recognised as such. For
+  instance, <filename>builder.sh</filename> is not a path: it's parsed
+  as an expression that selects the attribute <varname>sh</varname>
+  from the variable <varname>builder</varname>. If the file name is
   relative, i.e., if it does not begin with a slash, it is made
   absolute at parse time relative to the directory of the Nix
   expression that contained it.  For instance, if a Nix expression in
@@ -176,7 +175,7 @@ stdenv.mkDerivation {
   <para>Paths can also be specified between angle brackets, e.g.
   <literal>&lt;nixpkgs&gt;</literal>. This means that the directories
   listed in the environment variable
-  <envar linkend="env-NIX_PATH">NIX_PATH</literal> will be searched
+  <literal linkend="env-NIX_PATH">NIX_PATH</literal> will be searched
   for the given file or directory name.
   </para>
 

doc/manual/expressions/simple-expression.xml

@@ -21,10 +21,9 @@ need to do three things:
   such as dependencies, sources, and so on.</para></listitem>
 
   <listitem><para>Write a <emphasis>builder</emphasis>.  This is a
-  shell script<footnote><para>In fact, it can be written in any
-  language, but typically it's a <command>bash</command> shell
-  script.</para></footnote> that actually builds the package from
-  the inputs.</para></listitem>
+  shell script that builds the package from the inputs. (In fact, it
+  can be written in any language, but typically it's a
+  <command>bash</command> shell script.)</para></listitem>
 
   <listitem><para>Add the package to the file
   <filename>pkgs/top-level/all-packages.nix</filename>.  The Nix

doc/manual/packages/profiles.xml

@@ -18,13 +18,12 @@ of the Subversion package might be stored in a directory
 while another version might be stored in
 <filename>/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2</filename>.
 The long strings prefixed to the directory names are cryptographic
-hashes<footnote><para>160-bit truncations of SHA-256 hashes encoded in
-a base-32 notation, to be precise.</para></footnote> of
-<emphasis>all</emphasis> inputs involved in building the package —
-sources, dependencies, compiler flags, and so on.  So if two packages
-differ in any way, they end up in different locations in the file
-system, so they don’t interfere with each other.  Here is what a part
-of a typical Nix store looks like:</para>
+hashes (to be precise, 160-bit truncations of SHA-256 hashes encoded
+in a base-32 notation) of <emphasis>all</emphasis> inputs involved in
+building the package — sources, dependencies, compiler flags, and so
+on.  So if two packages differ in any way, they end up in different
+locations in the file system, so they don’t interfere with each other.
+Here is what a part of a typical Nix store looks like:</para>
 
 <mediaobject>
   <imageobject>

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

@@ -82,11 +82,10 @@ See also [???](#sec-common-options) for a list of common options.
 
   - `--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`.
+    `NIX_PATH` 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

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

@@ -206,9 +206,9 @@ Most Nix commands accept the following command-line options:
 
   - `-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`.
+    given multiple times. See the `NIX_PATH` 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

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

@@ -19,10 +19,9 @@ steps to elucidate what a builder does. It performs the following steps:
 
 1.  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
-    prevent undeclared inputs from being used in the build process. If
-    for example the `PATH` contained `/usr/bin`, then you might
-    accidentally use `/usr/bin/gcc`.
+    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 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
@@ -67,6 +66,3 @@ 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
 script is evaluated with Bash's `-e` option, which causes the script to
 be aborted if any command fails without an error check.
-
-1.  Actually, it's initialised to `/path-not-set` to prevent Bash from
-    setting it to a default value.

doc/manual/src/expressions/derivations.md

@@ -5,11 +5,12 @@ describe a single derivation (a build action). It takes as input a set,
 the attributes of which specify the inputs of the build.
 
   - There must be an attribute named `system` whose value must be a
-    string specifying a Nix platform identifier, such as `"i686-linux"`
-    or `"x86_64-darwin"`\[1\] The build can only be performed on a
-    machine and operating system matching the platform identifier. (Nix
-    can automatically forward builds for other platforms by forwarding
-    them to other machines; see [???](#chap-distributed-builds).)
+    string specifying a Nix system type, such as `"i686-linux"` or
+    `"x86_64-darwin"`. (To figure out your system type, run `nix -vv
+    --version`.) The build can only be performed on a machine and
+    operating system matching the system type. (Nix can automatically
+    forward builds for other platforms by forwarding them to other
+    machines; see [???](#chap-distributed-builds).)
 
   - There must be an attribute named `name` whose value must be a
     string. This is used as a symbolic name for the package by
@@ -146,9 +147,3 @@ The builder is executed as follows:
     supported by Nix. This is because the Nix archives used in
     deployment have no concept of ownership information, and because it
     makes the build result dependent on the user performing the build.
-
-<!-- end list -->
-
-1.  To figure out your platform identifier, look at the line “Checking
-    for the canonical Nix system name” in the output of Nix's
-    `configure` script.

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

@@ -27,8 +27,12 @@ Here is what each line means:
 1.  The `buildInputs` variable tells `setup` to use the indicated
     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 GCC's header search path; and so
-    on.\[1\]
+    subdirectory, it's added to GCC's header search path; and so on.
+    (This is implemented in a modular way: `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
+    variable to contain the `lib/site_perl` directories of all inputs.)
 
 2.  The function `genericBuild` is defined in the file `$stdenv/setup`.
 
@@ -55,10 +59,3 @@ shorter:
 In fact, `mkDerivation` provides a default builder that looks exactly
 like that, so it is actually possible to omit the builder for Hello
 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 variable to contain the `lib/site_perl` directories of
-    all inputs.

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

@@ -17,14 +17,14 @@ would be invalid if no such variable exists. That is, in a normal
 recursive set, they are.
 
 Recursive sets of course introduce the danger of infinite recursion. For
-example,
+example, the expression
 
     rec {
       x = y;
       y = x;
     }.x
 
-does not terminate\[1\].
+will crash with an `infinite recursion encountered` error message.
 
 ## Let-expressions
 
@@ -304,6 +304,3 @@ establishes the same scope as
 Comments can be single-line, started with a `#` character, or
 inline/multi-line, enclosed within `/*
 ... */`.
-
-1.  Actually, Nix detects infinite recursion in this case and aborts
-    (“infinite recursion encountered”).

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

@@ -108,12 +108,14 @@ Nix has the following basic data types:
     floating point number will have a floating point number as a result.
 
   - *Paths*, e.g., `/bin/sh` or `./builder.sh`. A path must contain at
-    least one slash to be recognised as such; for instance, `builder.sh`
-    is not a path\[1\]. If the file name is relative, i.e., if it does
-    not begin with a slash, it is made absolute at parse time relative
-    to the directory of the Nix expression that contained it. For
-    instance, if a Nix expression in `/foo/bar/bla.nix` refers to
-    `../xyzzy/fnord.nix`, the absolute path is `/foo/xyzzy/fnord.nix`.
+    least one slash to be recognised as such. For instance, `builder.sh`
+    is not a path: it's parsed as an expression that selects the
+    attribute `sh` from the variable `builder`. If the file name is
+    relative, i.e., if it does not begin with a slash, it is made
+    absolute at parse time relative to the directory of the Nix
+    expression that contained it. For instance, if a Nix expression in
+    `/foo/bar/bla.nix` refers to `../xyzzy/fnord.nix`, the absolute path
+    is `/foo/xyzzy/fnord.nix`.
     
     If the first component of a path is a `~`, it is interpreted as if
     the rest of the path were relative to the user's home directory.
@@ -122,8 +124,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\</literal\> will be searched for the
-    given file or directory name.
+    environment variable `NIX_PATH` will be searched for the given file
+    or directory name.
 
   - *Booleans* with values `true` and `false`.
 
@@ -210,6 +212,3 @@ passed in first , e.g.,
 evaluates to `2`. This can be used to attach metadata to a function
 without the caller needing to treat it specially, or to implement a form
 of object-oriented programming, for example.
-
-1.  It's parsed as an expression that selects the attribute `sh` from
-    the variable `builder`.

doc/manual/src/expressions/simple-expression.md

@@ -12,16 +12,12 @@ do three things:
     describes all the inputs involved in building the package, such as
     dependencies, sources, and so on.
 
-2.  Write a *builder*. This is a shell script\[1\] that actually builds
-    the package from the inputs.
+2.  Write a *builder*. This is a shell script that builds the package
+    from the inputs. (In fact, it can be written in any language, but
+    typically it's a `bash` shell script.)
 
 3.  Add the package to the file `pkgs/top-level/all-packages.nix`. The
     Nix expression written in the first step is a *function*; it
     requires other packages in order to build it. In this step you put
     it all together, i.e., you call the function with the right
     arguments to build the actual package.
-
-<!-- end list -->
-
-1.  In fact, it can be written in any language, but typically it's a
-    `bash` shell script.

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

@@ -10,12 +10,13 @@ in a directory
 `/nix/store/dpmvp969yhdqs7lm2r1a3gng7pyq6vy4-subversion-1.1.3/`, while
 another version might be stored in
 `/nix/store/5mq2jcn36ldlmh93yj1n8s9c95pj7c5s-subversion-1.1.2`. The long
-strings prefixed to the directory names are cryptographic hashes\[1\] of
-*all* inputs involved in building the package — sources, dependencies,
-compiler flags, and so on. So if two packages differ in any way, they
-end up in different locations in the file system, so they don’t
-interfere with each other. Here is what a part of a typical Nix store
-looks like:
+strings prefixed to the directory names are cryptographic hashes (to be
+precise, 160-bit truncations of SHA-256 hashes encoded in a base-32
+notation) of *all* inputs involved in building the package — sources,
+dependencies, compiler flags, and so on. So if two packages differ in
+any way, they end up in different locations in the file system, so they
+don’t interfere with each other. Here is what a part of a typical Nix
+store looks like:
 
 ![](../figures/user-environments.png)
 
@@ -113,6 +114,3 @@ All `nix-env` operations work on the profile pointed to by
     $ nix-env -p /nix/var/nix/profiles/other-profile -i subversion
 
 This will *not* change the `~/.nix-profile` symlink.
-
-1.  160-bit truncations of SHA-256 hashes encoded in a base-32 notation,
-    to be precise.