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
+    derivation).  This is done to prevent undeclared inputs from being
-    empty<footnote><para>Actually, it's initialised to
+    used in the build process. If for example the
-    <filename>/path-not-set</filename> to prevent Bash from setting it
+    <literal>PATH</literal> contained <filename>/usr/bin</filename>,
-    to a default value.</para></footnote>.  This is done to prevent
+    then you might accidentally use
-    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
+  <listitem xml:id="attr-system"><para>There must be an attribute
-  <varname>system</varname> whose value must be a string specifying a
+  named <varname>system</varname> whose value must be a string
-  Nix platform identifier, such as <literal>"i686-linux"</literal> or
+  specifying a Nix system type, such as
-  <literal>"x86_64-darwin"</literal><footnote><para>To figure out
+  <literal>"i686-linux"</literal> or
-  your platform identifier, look at the line <quote>Checking for the
+  <literal>"x86_64-darwin"</literal>. (To figure out your system type,
-  canonical Nix system name</quote> in the output of Nix's
+  run <literal>nix -vv --version</literal>.) The build can only be
-  <filename>configure</filename> script.</para></footnote> The build
+  performed on a machine and operating system matching the system
-  can only be performed on a machine and operating system matching the
+  type.  (Nix can automatically forward builds for other platforms by
-  platform identifier.  (Nix can automatically forward builds for
+  forwarding them to other machines; see <xref
-  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>
+    on. (This is implemented in a modular way:
-    tries to source the file
+    <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
+will crash with an <literal>infinite recursion encountered</literal>
-recursion in this case and aborts (<quote>infinite recursion
+error message.</para>
-encountered</quote>).</para></footnote>.</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
+  A path must contain at least one slash to be recognised as such. For
-  instance, <filename>builder.sh</filename> is not a
+  instance, <filename>builder.sh</filename> is not a path: it's parsed
-  path<footnote><para>It's parsed as an expression that selects the
+  as an expression that selects the attribute <varname>sh</varname>
-  attribute <varname>sh</varname> from the variable
+  from the variable <varname>builder</varname>. If the file name is
-  <varname>builder</varname>.</para></footnote>.  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
+  shell script that builds the package from the inputs. (In fact, it
-  language, but typically it's a <command>bash</command> shell
+  can be written in any language, but typically it's a
-  script.</para></footnote> that actually builds the package from
+  <command>bash</command> shell script.)</para></listitem>
-  the inputs.</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
+hashes (to be precise, 160-bit truncations of SHA-256 hashes encoded
-a base-32 notation, to be precise.</para></footnote> of
+in a base-32 notation) of <emphasis>all</emphasis> inputs involved in
-<emphasis>all</emphasis> inputs involved in building the package —
+building the package — sources, dependencies, compiler flags, and so
-sources, dependencies, compiler flags, and so on.  So if two packages
+on.  So if two packages differ in any way, they end up in different
-differ in any way, they end up in different locations in the file
+locations in the file system, so they don’t interfere with each other.
-system, so they don’t interfere with each other.  Here is what a part
+Here is what a part of a typical Nix store looks like:</para>
-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
+    `NIX_PATH` environment variable). If found, print the corresponding
-    corresponding absolute paths on standard output. For instance, if
+    absolute paths on standard output. For instance, if `NIX_PATH` is
-    `NIX_PATH` is `nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate
+    `nixpkgs=/home/alice/nixpkgs`, then `nix-instantiate --find-file
-    --find-file nixpkgs/default.nix` will print
+    nixpkgs/default.nix` will print `/home/alice/nixpkgs/default.nix`.
-    `/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
+    given multiple times. See the `NIX_PATH` environment variable for
-    variable for information on the semantics of the Nix search path.
+    information on the semantics of the Nix search path. Paths added
-    Paths added through `-I` take precedence over `NIX_PATH`.
+    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
+    This is done to prevent undeclared inputs from being used in the
-    prevent undeclared inputs from being used in the build process. If
+    build process. If for example the `PATH` contained `/usr/bin`, then
-    for example the `PATH` contained `/usr/bin`, then you might
+    you might accidentally use `/usr/bin/gcc`.
-    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"`
+    string specifying a Nix system type, such as `"i686-linux"` or
-    or `"x86_64-darwin"`\[1\] The build can only be performed on a
+    `"x86_64-darwin"`. (To figure out your system type, run `nix -vv
-    machine and operating system matching the platform identifier. (Nix
+    --version`.) The build can only be performed on a machine and
-    can automatically forward builds for other platforms by forwarding
+    operating system matching the system type. (Nix can automatically
-    them to other machines; see [???](#chap-distributed-builds).)
+    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
+    subdirectory, it's added to GCC's header search path; and so on.
-    on.\[1\]
+    (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`
+    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
+    is not a path: it's parsed as an expression that selects the
-    not begin with a slash, it is made absolute at parse time relative
+    attribute `sh` from the variable `builder`. If the file name is
-    to the directory of the Nix expression that contained it. For
+    relative, i.e., if it does not begin with a slash, it is made
-    instance, if a Nix expression in `/foo/bar/bla.nix` refers to
+    absolute at parse time relative to the directory of the Nix
-    `../xyzzy/fnord.nix`, the absolute path is `/foo/xyzzy/fnord.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
+    environment variable `NIX_PATH` will be searched for the given file
-    given file or directory name.
+    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
+2.  Write a *builder*. This is a shell script that builds the package
-    the package from the inputs.
+    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
+strings prefixed to the directory names are cryptographic hashes (to be
-*all* inputs involved in building the package — sources, dependencies,
+precise, 160-bit truncations of SHA-256 hashes encoded in a base-32
-compiler flags, and so on. So if two packages differ in any way, they
+notation) of *all* inputs involved in building the package — sources,
-end up in different locations in the file system, so they don’t
+dependencies, compiler flags, and so on. So if two packages differ in
-interfere with each other. Here is what a part of a typical Nix store
+any way, they end up in different locations in the file system, so they
-looks like:
+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.