From 5f8d14546b6a5a5df8a4768833497a674083dd8e Mon Sep 17 00:00:00 2001
From: Wilhelm Schuster <ws@wilhelm.re>
Date: Wed, 1 Jun 2016 16:23:32 +0200
Subject: [PATCH] Manual: Explicitly mark commands that require to be run as
 root (#15589)

* manual: Mark commands that require root

Mark every command that requires to be run as root by prefixing them
with '#' instead of '$'.

* manual: Add note about commands that require root
---
 .../manual/administration/cleaning-store.xml  |  4 +-
 .../administration/container-networking.xml   |  4 +-
 .../administration/imperative-containers.xml  | 24 ++++++------
 .../administration/maintenance-mode.xml       |  4 +-
 .../administration/network-problems.xml       |  4 +-
 nixos/doc/manual/administration/rebooting.xml |  8 ++--
 nixos/doc/manual/administration/rollback.xml  |  8 ++--
 .../manual/administration/service-mgmt.xml    |  6 +--
 .../administration/store-corruption.xml       |  6 +--
 .../manual/administration/user-sessions.xml   |  4 +-
 .../configuration/adding-custom-packages.xml  |  2 +-
 .../doc/manual/configuration/linux-kernel.xml |  2 +-
 .../configuration/luks-file-systems.xml       |  6 +--
 nixos/doc/manual/configuration/user-mgmt.xml  |  8 ++--
 nixos/doc/manual/configuration/wireless.xml   |  4 +-
 nixos/doc/manual/configuration/x-windows.xml  |  4 +-
 .../doc/manual/development/building-nixos.xml |  4 +-
 .../doc/manual/development/building-parts.xml |  6 +--
 nixos/doc/manual/development/sources.xml      |  2 +-
 .../manual/development/testing-installer.xml  |  8 ++--
 .../manual/installation/changing-config.xml   |  8 ++--
 .../manual/installation/installing-uefi.xml   |  2 +-
 nixos/doc/manual/installation/installing.xml  | 38 +++++++++----------
 nixos/doc/manual/installation/upgrading.xml   | 12 +++---
 nixos/doc/manual/man-configuration.xml        |  4 +-
 nixos/doc/manual/man-nixos-build-vms.xml      |  8 ++--
 nixos/doc/manual/man-nixos-option.xml         |  4 +-
 nixos/doc/manual/manual.xml                   |  5 ++-
 28 files changed, 101 insertions(+), 98 deletions(-)

diff --git a/nixos/doc/manual/administration/cleaning-store.xml b/nixos/doc/manual/administration/cleaning-store.xml
index 41dc65795b68..4cf62947f528 100644
--- a/nixos/doc/manual/administration/cleaning-store.xml
+++ b/nixos/doc/manual/administration/cleaning-store.xml
@@ -21,7 +21,7 @@ Alternatively, you can use a systemd unit that does the same in the
 background:
 
 <screen>
-$ systemctl start nix-gc.service
+# systemctl start nix-gc.service
 </screen>
 
 You can tell NixOS in <filename>configuration.nix</filename> to run
@@ -59,4 +59,4 @@ $ nix-store --optimise
 Since this command needs to read the entire Nix store, it can take
 quite a while to finish.</para>
 
-</chapter>
\ No newline at end of file
+</chapter>
diff --git a/nixos/doc/manual/administration/container-networking.xml b/nixos/doc/manual/administration/container-networking.xml
index adea3e69840d..1b1576d3babe 100644
--- a/nixos/doc/manual/administration/container-networking.xml
+++ b/nixos/doc/manual/administration/container-networking.xml
@@ -13,7 +13,7 @@ create</literal>, it gets it own private IPv4 address in the range
 address as follows:
 
 <screen>
-$ nixos-container show-ip foo
+# nixos-container show-ip foo
 10.233.4.2
 
 $ ping -c1 10.233.4.2
@@ -47,4 +47,4 @@ where <literal>eth0</literal> should be replaced with the desired
 external interface. Note that <literal>ve-+</literal> is a wildcard
 that matches all container interfaces.</para>
 
-</section>
\ No newline at end of file
+</section>
diff --git a/nixos/doc/manual/administration/imperative-containers.xml b/nixos/doc/manual/administration/imperative-containers.xml
index 6131d4e04ea8..3a52658436ac 100644
--- a/nixos/doc/manual/administration/imperative-containers.xml
+++ b/nixos/doc/manual/administration/imperative-containers.xml
@@ -11,7 +11,7 @@
 identifier <literal>foo</literal> as follows:
 
 <screen>
-$ nixos-container create foo
+# nixos-container create foo
 </screen>
 
 This creates the container’s root directory in
@@ -25,7 +25,7 @@ line. For instance, to create a container that has
 <literal>root</literal>:
 
 <screen>
-$ nixos-container create foo --config 'services.openssh.enable = true; \
+# nixos-container create foo --config 'services.openssh.enable = true; \
   users.extraUsers.root.openssh.authorizedKeys.keys = ["ssh-dss AAAAB3N…"];'
 </screen>
 
@@ -35,7 +35,7 @@ $ nixos-container create foo --config 'services.openssh.enable = true; \
 run:
 
 <screen>
-$ nixos-container start foo
+# nixos-container start foo
 </screen>
 
 This command will return as soon as the container has booted and has
@@ -46,7 +46,7 @@ Thus, if something went wrong, you can get status info using
 <command>systemctl</command>:
 
 <screen>
-$ systemctl status container@foo
+# systemctl status container@foo
 </screen>
 
 </para>
@@ -55,7 +55,7 @@ $ systemctl status container@foo
 root using the <command>root-login</command> operation:
 
 <screen>
-$ nixos-container root-login foo
+# nixos-container root-login foo
 [root@foo:~]#
 </screen>
 
@@ -65,7 +65,7 @@ authentication).  You can also get a regular login prompt using the
 the host:
 
 <screen>
-$ nixos-container login foo
+# nixos-container login foo
 foo login: alice
 Password: ***
 </screen>
@@ -74,7 +74,7 @@ With <command>nixos-container run</command>, you can execute arbitrary
 commands in the container:
 
 <screen>
-$ nixos-container run foo -- uname -a
+# nixos-container run foo -- uname -a
 Linux foo 3.4.82 #1-NixOS SMP Thu Mar 20 14:44:05 UTC 2014 x86_64 GNU/Linux
 </screen>
 
@@ -86,17 +86,17 @@ container. First, on the host, you can edit
 and run
 
 <screen>
-$ nixos-container update foo
+# nixos-container update foo
 </screen>
 
 This will build and activate the new configuration. You can also
 specify a new configuration on the command line:
 
 <screen>
-$ nixos-container update foo --config 'services.httpd.enable = true; \
+# nixos-container update foo --config 'services.httpd.enable = true; \
   services.httpd.adminAddr = "foo@example.org";'
 
-$ curl http://$(nixos-container show-ip foo)/
+# curl http://$(nixos-container show-ip foo)/
 &lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">…
 </screen>
 
@@ -116,9 +116,9 @@ start</literal>, respectively, or by using
 destroy a container, including its file system, do
 
 <screen>
-$ nixos-container destroy foo
+# nixos-container destroy foo
 </screen>
 
 </para>
 
-</section>
\ No newline at end of file
+</section>
diff --git a/nixos/doc/manual/administration/maintenance-mode.xml b/nixos/doc/manual/administration/maintenance-mode.xml
index 15c1f902da79..17a1609e5579 100644
--- a/nixos/doc/manual/administration/maintenance-mode.xml
+++ b/nixos/doc/manual/administration/maintenance-mode.xml
@@ -9,10 +9,10 @@
 <para>You can enter rescue mode by running:
 
 <screen>
-$ systemctl rescue</screen>
+# systemctl rescue</screen>
 
 This will eventually give you a single-user root shell.  Systemd will
 stop (almost) all system services.  To get out of maintenance mode,
 just exit from the rescue shell.</para>
 
-</section>
\ No newline at end of file
+</section>
diff --git a/nixos/doc/manual/administration/network-problems.xml b/nixos/doc/manual/administration/network-problems.xml
index 3af9cc59742f..91f9eb4e22c6 100644
--- a/nixos/doc/manual/administration/network-problems.xml
+++ b/nixos/doc/manual/administration/network-problems.xml
@@ -18,14 +18,14 @@ You can disable the use of the binary cache by adding <option>--option
 use-binary-caches false</option>, e.g.
 
 <screen>
-$ nixos-rebuild switch --option use-binary-caches false
+# nixos-rebuild switch --option use-binary-caches false
 </screen>
 
 If you have an alternative binary cache at your disposal, you can use
 it instead:
 
 <screen>
-$ nixos-rebuild switch --option binary-caches http://my-cache.example.org/
+# nixos-rebuild switch --option binary-caches http://my-cache.example.org/
 </screen>
 
 </para>
diff --git a/nixos/doc/manual/administration/rebooting.xml b/nixos/doc/manual/administration/rebooting.xml
index d1db7b141cf2..23f3a3219c6a 100644
--- a/nixos/doc/manual/administration/rebooting.xml
+++ b/nixos/doc/manual/administration/rebooting.xml
@@ -10,7 +10,7 @@
 doing:
 
 <screen>
-$ shutdown
+# shutdown
 </screen>
 
 This is equivalent to running <command>systemctl
@@ -19,7 +19,7 @@ poweroff</command>.</para>
 <para>To reboot the system, run
 
 <screen>
-$ reboot
+# reboot
 </screen>
 
 which is equivalent to <command>systemctl reboot</command>.
@@ -28,7 +28,7 @@ Alternatively, you can quickly reboot the system using
 the new kernel into memory:
 
 <screen>
-$ systemctl kexec
+# systemctl kexec
 </screen>
 
 </para>
@@ -41,4 +41,4 @@ $ systemctl kexec
 i.e. on a virtual console or in X11; otherwise, the user is asked for
 authentication.</para>
 
-</chapter>
\ No newline at end of file
+</chapter>
diff --git a/nixos/doc/manual/administration/rollback.xml b/nixos/doc/manual/administration/rollback.xml
index 23a3ece7c070..ae621f33de2c 100644
--- a/nixos/doc/manual/administration/rollback.xml
+++ b/nixos/doc/manual/administration/rollback.xml
@@ -19,7 +19,7 @@ fails to boot.  After the system has booted, you can make the selected
 configuration the default for subsequent boots:
 
 <screen>
-$ /run/current-system/bin/switch-to-configuration boot</screen>
+# /run/current-system/bin/switch-to-configuration boot</screen>
 
 </para>
 
@@ -27,12 +27,12 @@ $ /run/current-system/bin/switch-to-configuration boot</screen>
 system:
 
 <screen>
-$ nixos-rebuild switch --rollback</screen>
+# nixos-rebuild switch --rollback</screen>
 
 This is equivalent to running:
 
 <screen>
-$ /nix/var/nix/profiles/system-<replaceable>N</replaceable>-link/bin/switch-to-configuration switch</screen>
+# /nix/var/nix/profiles/system-<replaceable>N</replaceable>-link/bin/switch-to-configuration switch</screen>
 
 where <replaceable>N</replaceable> is the number of the NixOS system
 configuration.  To get a list of the available configurations, do:
@@ -45,4 +45,4 @@ lrwxrwxrwx 1 root root 78 Aug 12 13:54 /nix/var/nix/profiles/system-268-link ->
 
 </para>
 
-</section>
\ No newline at end of file
+</section>
diff --git a/nixos/doc/manual/administration/service-mgmt.xml b/nixos/doc/manual/administration/service-mgmt.xml
index c0940a42f307..1627c7a2fdeb 100644
--- a/nixos/doc/manual/administration/service-mgmt.xml
+++ b/nixos/doc/manual/administration/service-mgmt.xml
@@ -66,9 +66,9 @@ messages from the service.
 <para>Units can be stopped, started or restarted:
 
 <screen>
-$ systemctl stop postgresql.service
-$ systemctl start postgresql.service
-$ systemctl restart postgresql.service
+# systemctl stop postgresql.service
+# systemctl start postgresql.service
+# systemctl restart postgresql.service
 </screen>
 
 These operations are synchronous: they wait until the service has
diff --git a/nixos/doc/manual/administration/store-corruption.xml b/nixos/doc/manual/administration/store-corruption.xml
index 0160cb45358b..9f567042b727 100644
--- a/nixos/doc/manual/administration/store-corruption.xml
+++ b/nixos/doc/manual/administration/store-corruption.xml
@@ -18,7 +18,7 @@ you may be able to fix it automatically.</para>
 system configuration, you can fix it by doing
 
 <screen>
-$ nixos-rebuild switch --repair
+# nixos-rebuild switch --repair
 </screen>
 
 This will cause Nix to check every path in the closure, and if its
@@ -28,10 +28,10 @@ the path is rebuilt or redownloaded.</para>
 <para>You can also scan the entire Nix store for corrupt paths:
 
 <screen>
-$ nix-store --verify --check-contents --repair
+# nix-store --verify --check-contents --repair
 </screen>
 
 Any corrupt paths will be redownloaded if they’re available in a
 binary cache; otherwise, they cannot be repaired.</para>
 
-</section>
\ No newline at end of file
+</section>
diff --git a/nixos/doc/manual/administration/user-sessions.xml b/nixos/doc/manual/administration/user-sessions.xml
index 05e2c1a9b29f..0a7eb8cd123c 100644
--- a/nixos/doc/manual/administration/user-sessions.xml
+++ b/nixos/doc/manual/administration/user-sessions.xml
@@ -45,9 +45,9 @@ track of this, you can terminate a session in a way that ensures that
 all the session’s processes are gone:
 
 <screen>
-$ loginctl terminate-session c3
+# loginctl terminate-session c3
 </screen>
 
 </para>
 
-</chapter>
\ No newline at end of file
+</chapter>
diff --git a/nixos/doc/manual/configuration/adding-custom-packages.xml b/nixos/doc/manual/configuration/adding-custom-packages.xml
index c1789fcbc041..ab3665bae504 100644
--- a/nixos/doc/manual/configuration/adding-custom-packages.xml
+++ b/nixos/doc/manual/configuration/adding-custom-packages.xml
@@ -31,7 +31,7 @@ and you run <command>nixos-rebuild</command>, specifying your own
 Nixpkgs tree:
 
 <screen>
-$ nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>
+# nixos-rebuild switch -I nixpkgs=/path/to/my/nixpkgs</screen>
 
 </para>
 
diff --git a/nixos/doc/manual/configuration/linux-kernel.xml b/nixos/doc/manual/configuration/linux-kernel.xml
index b008baaa66c9..52be26d6024a 100644
--- a/nixos/doc/manual/configuration/linux-kernel.xml
+++ b/nixos/doc/manual/configuration/linux-kernel.xml
@@ -82,7 +82,7 @@ $ nix-shell '<nixpkgs>' -A linuxPackages.kernel
 $ unpackPhase
 $ cd linux-*
 $ make -C $dev/lib/modules/*/build M=$(pwd)/drivers/net/ethernet/mellanox modules
-$ sudo insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
+# insmod ./drivers/net/ethernet/mellanox/mlx5/core/mlx5_core.ko
 ]]></screen>
 
 </section>
diff --git a/nixos/doc/manual/configuration/luks-file-systems.xml b/nixos/doc/manual/configuration/luks-file-systems.xml
index 88b506d5323d..2062456703f7 100644
--- a/nixos/doc/manual/configuration/luks-file-systems.xml
+++ b/nixos/doc/manual/configuration/luks-file-systems.xml
@@ -12,7 +12,7 @@ here is how you create an encrypted Ext4 file system on the device
 <filename>/dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d</filename>:
 
 <screen>
-$ cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d
+# cryptsetup luksFormat /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d
 
 WARNING!
 ========
@@ -22,10 +22,10 @@ Are you sure? (Type uppercase yes): YES
 Enter LUKS passphrase: ***
 Verify passphrase: ***
 
-$ cryptsetup luksOpen /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d crypted
+# cryptsetup luksOpen /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d crypted
 Enter passphrase for /dev/disk/by-uuid/3f6b0024-3a44-4fde-a43a-767b872abe5d: ***
 
-$ mkfs.ext4 /dev/mapper/crypted
+# mkfs.ext4 /dev/mapper/crypted
 </screen>
 
 To ensure that this file system is automatically mounted at boot time
diff --git a/nixos/doc/manual/configuration/user-mgmt.xml b/nixos/doc/manual/configuration/user-mgmt.xml
index 631742059278..829e5b9ea842 100644
--- a/nixos/doc/manual/configuration/user-mgmt.xml
+++ b/nixos/doc/manual/configuration/user-mgmt.xml
@@ -63,14 +63,14 @@ commands such as <command>useradd</command>,
 account named <literal>alice</literal>:
 
 <screen>
-$ useradd -m alice</screen>
+# useradd -m alice</screen>
 
 To make all nix tools available to this new user use `su - USER` which 
 opens a login shell (==shell that loads the profile) for given user. 
 This will create the ~/.nix-defexpr symlink. So run:
 
 <screen>
-$ su - alice -c "true"</screen>
+# su - alice -c "true"</screen>
 
 
 The flag <option>-m</option> causes the creation of a home directory
@@ -79,7 +79,7 @@ have an initial password and therefore cannot log in.  A password can
 be set using the <command>passwd</command> utility:
 
 <screen>
-$ passwd alice
+# passwd alice
 Enter new UNIX password: ***
 Retype new UNIX password: ***
 </screen>
@@ -87,7 +87,7 @@ Retype new UNIX password: ***
 A user can be deleted using <command>userdel</command>:
 
 <screen>
-$ userdel -r alice</screen>
+# userdel -r alice</screen>
 
 The flag <option>-r</option> deletes the user’s home directory.
 Accounts can be modified using <command>usermod</command>.  Unix
diff --git a/nixos/doc/manual/configuration/wireless.xml b/nixos/doc/manual/configuration/wireless.xml
index e4560f2da36b..1868380dcbfa 100644
--- a/nixos/doc/manual/configuration/wireless.xml
+++ b/nixos/doc/manual/configuration/wireless.xml
@@ -41,13 +41,13 @@ If you are using WPA2 the <command>wpa_passphrase</command> tool might be useful
 to generate the <literal>wpa_supplicant.conf</literal>.
 
 <screen>
-$ wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf</screen>
+# wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf</screen>
 
 After you have edited the <literal>wpa_supplicant.conf</literal>,
 you need to restart the wpa_supplicant service.
 
 <screen>
-$ systemctl restart wpa_supplicant.service</screen>
+# systemctl restart wpa_supplicant.service</screen>
 </para>
 
 </section>
diff --git a/nixos/doc/manual/configuration/x-windows.xml b/nixos/doc/manual/configuration/x-windows.xml
index 7f43acab2c38..0405146ab0fa 100644
--- a/nixos/doc/manual/configuration/x-windows.xml
+++ b/nixos/doc/manual/configuration/x-windows.xml
@@ -5,7 +5,7 @@
          xml:id="sec-x11">
 
 <title>X Window System</title>
-    
+
 <para>The X Window System (X11) provides the basis of NixOS’ graphical
 user interface.  It can be enabled as follows:
 <programlisting>
@@ -48,7 +48,7 @@ services.xserver.autorun = false;
 </programlisting>
 The X server can then be started manually:
 <screen>
-$ systemctl start display-manager.service
+# systemctl start display-manager.service
 </screen>
 </para>
 
diff --git a/nixos/doc/manual/development/building-nixos.xml b/nixos/doc/manual/development/building-nixos.xml
index 21c5bfe6a5b1..150fa1d7017e 100644
--- a/nixos/doc/manual/development/building-nixos.xml
+++ b/nixos/doc/manual/development/building-nixos.xml
@@ -25,8 +25,8 @@ $ nix-build -A config.system.build.isoImage -I nixos-config=modules/installer/cd
 suggested by the following command:
 
 <screen>
-$ mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen>
+# mount -o loop -t iso9660 ./result/iso/cd.iso /mnt/iso</screen>
 
 </para>
 
-</chapter>
\ No newline at end of file
+</chapter>
diff --git a/nixos/doc/manual/development/building-parts.xml b/nixos/doc/manual/development/building-parts.xml
index cb8dee039c8e..09a40114f02e 100644
--- a/nixos/doc/manual/development/building-parts.xml
+++ b/nixos/doc/manual/development/building-parts.xml
@@ -94,8 +94,8 @@ $ nix-build -A 'config.systemd.units."httpd.service".unit'
 <screen>
 $ cp $(nix-build -A 'config.systemd.units."httpd.service".unit')/httpd.service \
     /run/systemd/system/tmp-httpd.service
-$ systemctl daemon-reload
-$ systemctl start tmp-httpd.service
+# systemctl daemon-reload
+# systemctl start tmp-httpd.service
 </screen>
 
       Note that the unit must not have the same name as any unit in
@@ -110,4 +110,4 @@ $ systemctl start tmp-httpd.service
 
 </para>
 
-</chapter>
\ No newline at end of file
+</chapter>
diff --git a/nixos/doc/manual/development/sources.xml b/nixos/doc/manual/development/sources.xml
index fd0b0109b322..7cd5ce0002c2 100644
--- a/nixos/doc/manual/development/sources.xml
+++ b/nixos/doc/manual/development/sources.xml
@@ -70,7 +70,7 @@ sources, you need to tell <command>nixos-rebuild</command> about them
 using the <option>-I</option> flag:
 
 <screen>
-$ nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs
+# nixos-rebuild switch -I nixpkgs=<replaceable>/my/sources</replaceable>/nixpkgs
 </screen>
 
 </para>
diff --git a/nixos/doc/manual/development/testing-installer.xml b/nixos/doc/manual/development/testing-installer.xml
index 87e40e326171..20c8d51815ad 100644
--- a/nixos/doc/manual/development/testing-installer.xml
+++ b/nixos/doc/manual/development/testing-installer.xml
@@ -12,16 +12,16 @@ properly:
 
 <screen>
 $ nix-build -A config.system.build.nixos-install
-$ mount -t tmpfs none /mnt
-$ ./result/bin/nixos-install</screen>
+# mount -t tmpfs none /mnt
+# ./result/bin/nixos-install</screen>
 
 To start a login shell in the new NixOS installation in
 <filename>/mnt</filename>:
 
 <screen>
-$ ./result/bin/nixos-install --chroot
+# ./result/bin/nixos-install --chroot
 </screen>
 
 </para>
 
-</chapter>
\ No newline at end of file
+</chapter>
diff --git a/nixos/doc/manual/installation/changing-config.xml b/nixos/doc/manual/installation/changing-config.xml
index aa31742434e4..43b591a1cae9 100644
--- a/nixos/doc/manual/installation/changing-config.xml
+++ b/nixos/doc/manual/installation/changing-config.xml
@@ -10,7 +10,7 @@ contains the current configuration of your machine.  Whenever you’ve
 changed something to that file, you should do
 
 <screen>
-$ nixos-rebuild switch</screen>
+# nixos-rebuild switch</screen>
 
 to build the new configuration, make it the default configuration for
 booting, and try to realise the configuration in the running system
@@ -23,7 +23,7 @@ either run them from a root shell or by prefixing them with
 <para>You can also do
 
 <screen>
-$ nixos-rebuild test</screen>
+# nixos-rebuild test</screen>
 
 to build the configuration and switch the running system to it, but
 without making it the boot default.  So if (say) the configuration
@@ -33,7 +33,7 @@ configuration.</para>
 <para>There is also
 
 <screen>
-$ nixos-rebuild boot</screen>
+# nixos-rebuild boot</screen>
 
 to build the configuration and make it the boot default, but not
 switch to it now (so it will only take effect after the next
@@ -44,7 +44,7 @@ of the GRUB 2 boot screen by giving it a different <emphasis>profile
 name</emphasis>, e.g.
 
 <screen>
-$ nixos-rebuild switch -p test </screen>
+# nixos-rebuild switch -p test </screen>
 
 which causes the new configuration (and previous ones created using
 <literal>-p test</literal>) to show up in the GRUB submenu “NixOS -
diff --git a/nixos/doc/manual/installation/installing-uefi.xml b/nixos/doc/manual/installation/installing-uefi.xml
index 1cb431129448..927648febc50 100644
--- a/nixos/doc/manual/installation/installing-uefi.xml
+++ b/nixos/doc/manual/installation/installing-uefi.xml
@@ -5,7 +5,7 @@
          xml:id="sec-uefi-installation">
 
 <title>UEFI Installation</title>
-    
+
 <para>NixOS can also be installed on UEFI systems.  The procedure
 is by and large the same as a BIOS installation, with the following
 changes:
diff --git a/nixos/doc/manual/installation/installing.xml b/nixos/doc/manual/installation/installing.xml
index 3e53062c3e84..2f118d27b1a5 100644
--- a/nixos/doc/manual/installation/installing.xml
+++ b/nixos/doc/manual/installation/installing.xml
@@ -54,7 +54,7 @@
     changes.  For example:
 
 <screen>
-$ mkfs.ext4 -L nixos /dev/sda1</screen>
+# mkfs.ext4 -L nixos /dev/sda1</screen>
 
     </para></listitem>
 
@@ -66,10 +66,10 @@ $ mkfs.ext4 -L nixos /dev/sda1</screen>
     <listitem><para>For creating LVM volumes, the LVM commands, e.g.,
 
 <screen>
-$ pvcreate /dev/sda1 /dev/sdb1
-$ vgcreate MyVolGroup /dev/sda1 /dev/sdb1
-$ lvcreate --size 2G --name bigdisk MyVolGroup
-$ lvcreate --size 1G --name smalldisk MyVolGroup</screen>
+# pvcreate /dev/sda1 /dev/sdb1
+# vgcreate MyVolGroup /dev/sda1 /dev/sdb1
+# lvcreate --size 2G --name bigdisk MyVolGroup
+# lvcreate --size 1G --name smalldisk MyVolGroup</screen>
 
     </para></listitem>
 
@@ -84,7 +84,7 @@ $ lvcreate --size 1G --name smalldisk MyVolGroup</screen>
   be installed on <filename>/mnt</filename>, e.g.
 
 <screen>
-$ mount /dev/disk/by-label/nixos /mnt
+# mount /dev/disk/by-label/nixos /mnt
 </screen>
 
   </para></listitem>
@@ -113,14 +113,14 @@ $ mount /dev/disk/by-label/nixos /mnt
     generate an initial configuration file for you:
 
 <screen>
-$ nixos-generate-config --root /mnt</screen>
+# nixos-generate-config --root /mnt</screen>
 
     You should then edit
     <filename>/mnt/etc/nixos/configuration.nix</filename> to suit your
     needs:
 
 <screen>
-$ nano /mnt/etc/nixos/configuration.nix
+# nano /mnt/etc/nixos/configuration.nix
 </screen>
 
     If you’re using the graphical ISO image, other editors may be
@@ -162,7 +162,7 @@ $ nano /mnt/etc/nixos/configuration.nix
   <listitem><para>Do the installation:
 
 <screen>
-$ nixos-install</screen>
+# nixos-install</screen>
 
     Cross fingers.  If this fails due to a temporary problem (such as
     a network issue while downloading binaries from the NixOS binary
@@ -186,7 +186,7 @@ Retype new UNIX password: ***
   <listitem><para>If everything went well:
 
 <screen>
-$ reboot</screen>
+# reboot</screen>
 
   </para></listitem>
 
@@ -235,15 +235,15 @@ drive (here <filename>/dev/sda</filename>).  <xref linkend="ex-config"
 
 <example xml:id='ex-install-sequence'><title>Commands for Installing NixOS on <filename>/dev/sda</filename></title>
 <screen>
-$ fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation>
-$ mkfs.ext4 -L nixos /dev/sda1
-$ mkswap -L swap /dev/sda2
-$ swapon /dev/sda2
-$ mount /dev/disk/by-label/nixos /mnt
-$ nixos-generate-config --root /mnt
-$ nano /mnt/etc/nixos/configuration.nix
-$ nixos-install
-$ reboot</screen>
+# fdisk /dev/sda # <lineannotation>(or whatever device you want to install on)</lineannotation>
+# mkfs.ext4 -L nixos /dev/sda1
+# mkswap -L swap /dev/sda2
+# swapon /dev/sda2
+# mount /dev/disk/by-label/nixos /mnt
+# nixos-generate-config --root /mnt
+# nano /mnt/etc/nixos/configuration.nix
+# nixos-install
+# reboot</screen>
 </example>
 
 <example xml:id='ex-config'><title>NixOS Configuration</title>
diff --git a/nixos/doc/manual/installation/upgrading.xml b/nixos/doc/manual/installation/upgrading.xml
index c4812cc637c3..65d395b0c88e 100644
--- a/nixos/doc/manual/installation/upgrading.xml
+++ b/nixos/doc/manual/installation/upgrading.xml
@@ -60,33 +60,33 @@ the <literal>nixos-14.12</literal> channel.  To see which NixOS
 channel you’re subscribed to, run the following as root:
 
 <screen>
-$ nix-channel --list | grep nixos
+# nix-channel --list | grep nixos
 nixos https://nixos.org/channels/nixos-unstable
 </screen>
 
 To switch to a different NixOS channel, do
 
 <screen>
-$ nix-channel --add https://nixos.org/channels/<replaceable>channel-name</replaceable> nixos
+# nix-channel --add https://nixos.org/channels/<replaceable>channel-name</replaceable> nixos
 </screen>
 
 (Be sure to include the <literal>nixos</literal> parameter at the
 end.)  For instance, to use the NixOS 14.12 stable channel:
 
 <screen>
-$ nix-channel --add https://nixos.org/channels/nixos-14.12 nixos
+# nix-channel --add https://nixos.org/channels/nixos-14.12 nixos
 </screen>
 
 If you have a server, you may want to use the “small” channel instead:
 
 <screen>
-$ nix-channel --add https://nixos.org/channels/nixos-14.12-small nixos
+# nix-channel --add https://nixos.org/channels/nixos-14.12-small nixos
 </screen>
 
 And if you want to live on the bleeding edge:
 
 <screen>
-$ nix-channel --add https://nixos.org/channels/nixos-unstable nixos
+# nix-channel --add https://nixos.org/channels/nixos-unstable nixos
 </screen>
 
 </para>
@@ -95,7 +95,7 @@ $ nix-channel --add https://nixos.org/channels/nixos-unstable nixos
 channel by running
 
 <screen>
-$ nixos-rebuild switch --upgrade
+# nixos-rebuild switch --upgrade
 </screen>
 
 which is equivalent to the more verbose <literal>nix-channel --update
diff --git a/nixos/doc/manual/man-configuration.xml b/nixos/doc/manual/man-configuration.xml
index d49369d2c584..05531b3909a3 100644
--- a/nixos/doc/manual/man-configuration.xml
+++ b/nixos/doc/manual/man-configuration.xml
@@ -1,7 +1,7 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
           xmlns:xlink="http://www.w3.org/1999/xlink"
           xmlns:xi="http://www.w3.org/2001/XInclude">
-  
+
 <refmeta>
   <refentrytitle><filename>configuration.nix</filename></refentrytitle>
   <manvolnum>5</manvolnum>
@@ -34,5 +34,5 @@ therein.</para>
 <xi:include href="options-db.xml" />
 
 </refsection>
-  
+
 </refentry>
diff --git a/nixos/doc/manual/man-nixos-build-vms.xml b/nixos/doc/manual/man-nixos-build-vms.xml
index f37677629d0c..878ebee05273 100644
--- a/nixos/doc/manual/man-nixos-build-vms.xml
+++ b/nixos/doc/manual/man-nixos-build-vms.xml
@@ -1,7 +1,7 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
           xmlns:xlink="http://www.w3.org/1999/xlink"
           xmlns:xi="http://www.w3.org/2001/XInclude">
-  
+
 <refmeta>
   <refentrytitle><command>nixos-build-vms</command></refentrytitle>
   <manvolnum>8</manvolnum>
@@ -42,10 +42,10 @@ points to the generated virtual network.
       services.openssh.enable = true;
       nixpkgs.system = "i686-linux";
       deployment.targetHost = "test1.example.net";
-      
+
       # Other NixOS options
     };
-    
+
   test2 = {pkgs, config, ...}:
     {
       services.openssh.enable = true;
@@ -53,7 +53,7 @@ points to the generated virtual network.
       environment.systemPackages = [ pkgs.lynx ];
       nixpkgs.system = "x86_64-linux";
       deployment.targetHost = "test2.example.net";
-      
+
       # Other NixOS options
     };
 }
diff --git a/nixos/doc/manual/man-nixos-option.xml b/nixos/doc/manual/man-nixos-option.xml
index 2875336c67e5..6be8bc780f13 100644
--- a/nixos/doc/manual/man-nixos-option.xml
+++ b/nixos/doc/manual/man-nixos-option.xml
@@ -1,7 +1,7 @@
 <refentry xmlns="http://docbook.org/ns/docbook"
           xmlns:xlink="http://www.w3.org/1999/xlink"
           xmlns:xi="http://www.w3.org/2001/XInclude">
-  
+
 <refmeta>
   <refentrytitle><command>nixos-option</command></refentrytitle>
   <manvolnum>8</manvolnum>
@@ -64,7 +64,7 @@ $ nixos-option boot.loader.grub.enable
 Value:
 true
 
-Default: 
+Default:
 true
 
 Description:
diff --git a/nixos/doc/manual/manual.xml b/nixos/doc/manual/manual.xml
index 736d1d4eff71..42b2cf75a77a 100644
--- a/nixos/doc/manual/manual.xml
+++ b/nixos/doc/manual/manual.xml
@@ -3,7 +3,7 @@
       xmlns:xi="http://www.w3.org/2001/XInclude"
       version="5.0"
       xml:id="book-nixos-manual">
-  
+
   <info>
     <title>NixOS Manual</title>
     <subtitle>Version <xi:include href="version" parse="text" /></subtitle>
@@ -26,6 +26,9 @@
     xlink:href="https://github.com/NixOS/nixpkgs/issues">NixOS’ GitHub
     issue tracker</link>.</para>
 
+    <note>Commands prefixed with <literal>#</literal> have to be run as
+    root, either requiring to login as root user or temporarily switching
+    to it using <literal>sudo</literal> for example.</note>
   </preface>
 
   <xi:include href="installation/installation.xml" />