Merge pull request #38831 from rdnetto/improve-cross-refs

Improve cross referencing in NixOS Manual

nixos/doc/manual/installation/installing.xml

@@ -203,26 +203,29 @@ for a UEFI installation is by and large the same as a BIOS installation. The dif
     <variablelist>
 
       <varlistentry><term>BIOS systems</term>
-      <listitem><para>You <emphasis>must</emphasis> set the option
-    <option>boot.loader.grub.device</option> to specify on which disk
-    the GRUB boot loader is to be installed.  Without it, NixOS cannot
-      boot.</para></listitem></varlistentry>
+        <listitem><para>You <emphasis>must</emphasis> set the option
+            <xref linkend="opt-boot.loader.grub.device"/> to specify on which disk
+            the GRUB boot loader is to be installed.  Without it, NixOS cannot
+            boot.</para></listitem></varlistentry>
 
       <varlistentry><term>UEFI systems</term>
-      <listitem><para>You <emphasis>must</emphasis> set the option
-      <option>boot.loader.systemd-boot.enable</option> to <literal>true</literal>.
-      <command>nixos-generate-config</command> should do this automatically for new
-      configurations when booted in
-      UEFI mode.</para>
-      <para>You may want to look at the options starting with
-      <option>boot.loader.efi</option> and <option>boot.loader.systemd-boot</option>
-      as well.</para></listitem></varlistentry>
+        <listitem><para>You <emphasis>must</emphasis> set the option
+            <xref linkend="opt-boot.loader.systemd-boot.enable"/> to <literal>true</literal>.
+            <command>nixos-generate-config</command> should do this automatically for new
+            configurations when booted in
+            UEFI mode.</para>
+          <para>You may want to look at the options starting with
+            <option><link linkend="opt-boot.loader.efi.canTouchEfiVariables">boot.loader.efi</link></option> and
+            <option><link linkend="opt-boot.loader.systemd-boot.enable">boot.loader.systemd</link></option> as well.
+          </para>
+        </listitem>
+      </varlistentry>
 
     </variablelist>
 
     <para>If there are other operating systems running on the machine before
     installing NixOS, the
-    <option>boot.loader.grub.useOSProber</option> option can be set to
+    <xref linkend="opt-boot.loader.grub.useOSProber"/> option can be set to
     <literal>true</literal> to automatically add them to the grub menu.</para>
 
     <para>Another critical option is <option>fileSystems</option>,
@@ -264,15 +267,15 @@ for a UEFI installation is by and large the same as a BIOS installation. The dif
     <para>As the last step, <command>nixos-install</command> will ask
     you to set the password for the <literal>root</literal> user, e.g.
 
-<screen>
+    <screen>
 setting root password...
 Enter new UNIX password: ***
 Retype new UNIX password: ***
-</screen>
+    </screen>
 
     <note>
       <para>
-        To prevent the password prompt, set <code>users.mutableUsers = false;</code> in
+        To prevent the password prompt, set <code><xref linkend="opt-users.mutableUsers"/> = false;</code> in
         <filename>configuration.nix</filename>, which allows unattended installation
         necessary in automation.
       </para>
@@ -285,20 +288,20 @@ Retype new UNIX password: ***
   <listitem>
     <para>If everything went well:
 
-<screen>
-# reboot</screen>
+      <screen>
+        # reboot</screen>
 
   </para></listitem>
 
   <listitem>
 
     <para>You should now be able to boot into the installed NixOS. The
-    GRUB boot menu shows a list of <emphasis>available
-    configurations</emphasis> (initially just one). Every time you
-    change the NixOS configuration (see <link
-    linkend="sec-changing-config">Changing Configuration</link> ), a
-    new item is added to the menu. This allows you to easily roll back
-    to a previous configuration if something goes wrong.</para>
+      GRUB boot menu shows a list of <emphasis>available
+        configurations</emphasis> (initially just one). Every time you
+      change the NixOS configuration (see <link
+        linkend="sec-changing-config">Changing Configuration</link> ), a
+      new item is added to the menu. This allows you to easily roll back
+      to a previous configuration if something goes wrong.</para>
 
     <para>You should log in and change the <literal>root</literal>
     password with <command>passwd</command>.</para>
@@ -372,26 +375,25 @@ drive (here <filename>/dev/sda</filename>).  <xref linkend="ex-config"
 </example>
 
 <example xml:id='ex-config'><title>NixOS Configuration</title>
-<screen>
-{ config, pkgs, ... }:
+  <screen>
+{ config, pkgs, ... }: {
+  imports = [
+    # Include the results of the hardware scan.
+    ./hardware-configuration.nix
+  ];
 
-{
-  imports =
-    [ # Include the results of the hardware scan.
-      ./hardware-configuration.nix
-    ];
-
-  boot.loader.grub.device = "/dev/sda";   # <lineannotation>(for BIOS systems only)</lineannotation>
-  boot.loader.systemd-boot.enable = true; # <lineannotation>(for UEFI systems only)</lineannotation>
+  <xref linkend="opt-boot.loader.grub.device"/> = "/dev/sda";   # <lineannotation>(for BIOS systems only)</lineannotation>
+  <xref linkend="opt-boot.loader.systemd-boot.enable"/> = true; # <lineannotation>(for UEFI systems only)</lineannotation>
 
   # Note: setting fileSystems is generally not
   # necessary, since nixos-generate-config figures them out
   # automatically in hardware-configuration.nix.
-  #fileSystems."/".device = "/dev/disk/by-label/nixos";
+  #<link linkend="opt-fileSystems._name__.device">fileSystems."/".device</link> = "/dev/disk/by-label/nixos";
 
   # Enable the OpenSSH server.
   services.sshd.enable = true;
-}</screen>
+}
+  </screen>
 </example>
 
 <xi:include href="installing-usb.xml" />