treewide: tweak DocBook docs for conversion

These help `nix-munge-doc` automate more of the Markdown conversion
process. See the following nixpkgs commits for explanations of many
of these changes:

* https://github.com/NixOS/nixpkgs/commit/275a34e0d8a937a81b267e47302dd8a92fa781df
* https://github.com/NixOS/nixpkgs/commit/694d5b19d30bf66687b42fb77f43ea7cd1002a62
* https://github.com/NixOS/nixpkgs/commit/f1d39b6d6187997b630647400c5efe5b01e06a23
* https://github.com/NixOS/nixpkgs/commit/16102dce2fbad670bd47dd75c860a8daa5fe47ad

I couldn't think of any particularly good way to format the
`system.defaults` breadcrumbs, so I just made them standalone
paragraphs. They weren't rendering correctly in DocBook anyway.

5 files changed, 41 insertions, 22 deletions

diff --git a/modules/system/defaults/NSGlobalDomain.nix b/modules/system/defaults/NSGlobalDomain.nix
index 3fb8db0..a23737e 100644
--- a/modules/system/defaults/NSGlobalDomain.nix
+++ b/modules/system/defaults/NSGlobalDomain.nix
@@ -229,7 +229,8 @@ in {
       type = types.nullOr types.int;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Keyboard
+        Apple menu > System Preferences > Keyboard
+
         If you press and hold certain keyboard keys when in a text area, the key’s character begins to repeat.
         For example, the Delete key continues to remove text for as long as you hold it down.
 
@@ -241,7 +242,8 @@ in {
       type = types.nullOr types.int;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Keyboard
+        Apple menu > System Preferences > Keyboard
+
         If you press and hold certain keyboard keys when in a text area, the key’s character begins to repeat.
         For example, the Delete key continues to remove text for as long as you hold it down.
 
@@ -285,7 +287,8 @@ in {
       type = types.nullOr floatWithDeprecationError;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Sound
+        Apple menu > System Preferences > Sound
+
         Sets the beep/alert volume level from 0.000 (muted) to 1.000 (100% volume).
 
         75% = 0.7788008
@@ -300,7 +303,8 @@ in {
       type = types.nullOr types.int;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Sound
+        Apple menu > System Preferences > Sound
+
         Make a feedback sound when the system volume changed. This setting accepts
         the integers 0 or 1. Defaults to 1.
       '';
diff --git a/modules/system/defaults/alf.nix b/modules/system/defaults/alf.nix
index f62ead2..96a9806 100644
--- a/modules/system/defaults/alf.nix
+++ b/modules/system/defaults/alf.nix
@@ -8,7 +8,8 @@ with lib;
       type = types.nullOr types.int;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Security and Privacy > Firewall
+        Apple menu > System Preferences > Security and Privacy > Firewall
+
         Enable the internal firewall to prevent unauthorised applications, programs
         and services from accepting incoming connections.
 
@@ -22,7 +23,8 @@ with lib;
       type = types.nullOr types.int;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Security and Privacy > Firewall
+        Apple menu > System Preferences > Security and Privacy > Firewall
+
         Allows any signed Application to accept incoming requests. Default is true.
 
         0 = disabled
@@ -34,7 +36,8 @@ with lib;
       type = types.nullOr types.int;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Security and Privacy > Firewall
+        Apple menu > System Preferences > Security and Privacy > Firewall
+
         Allows any downloaded Application that has been signed to accept incoming requests. Default is 0.
 
         0 = disabled
@@ -46,7 +49,8 @@ with lib;
       type = types.nullOr types.int;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Security and Privacy > Firewall
+        Apple menu > System Preferences > Security and Privacy > Firewall
+
         Enable logging of requests made to the firewall. Default is 0.
 
         0 = disabled
@@ -58,7 +62,8 @@ with lib;
       type = types.nullOr types.int;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Security and firewall
+        Apple menu > System Preferences > Security and firewall
+
         Drops incoming requests via ICMP such as ping requests. Default is 0.
 
         0 = disabled
diff --git a/modules/system/defaults/loginwindow.nix b/modules/system/defaults/loginwindow.nix
index 0194cc1..5f0491a 100644
--- a/modules/system/defaults/loginwindow.nix
+++ b/modules/system/defaults/loginwindow.nix
@@ -8,7 +8,8 @@ with lib;
       type = types.nullOr types.bool;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         Displays login window as a name and password field instead of a list of users.
         Default is false.
       '';
@@ -18,7 +19,8 @@ with lib;
       type = types.nullOr types.str;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         Auto login the supplied user on boot. Default is Off.
       '';
     };
@@ -27,7 +29,8 @@ with lib;
       type = types.nullOr types.bool;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         Allow users to login to the machine as guests using the Guest account. Default is true.
       '';
     };
@@ -44,7 +47,8 @@ with lib;
       type = types.nullOr types.bool;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         Hides the Shut Down button on the login screen. Default is false.
       '';
     };
@@ -53,7 +57,8 @@ with lib;
       type = types.nullOr types.bool;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         Hides the Sleep button on the login screen. Default is false.
       '';
     };
@@ -62,7 +67,8 @@ with lib;
       type = types.nullOr types.bool;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         Hides the Restart button on the login screen. Default is false.
       '';
     };
@@ -71,7 +77,8 @@ with lib;
       type = types.nullOr types.bool;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         Disables the "Shutdown" option when users are logged in. Default is false.
       '';
     };
@@ -80,7 +87,8 @@ with lib;
       type = types.nullOr types.bool;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         If set to true, the Power Off menu item will be disabled when the user is logged in. Default is false.
       '';
     };
@@ -89,7 +97,8 @@ with lib;
       type = types.nullOr types.bool;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Users and Groups > Login Options
+        Apple menu > System Preferences > Users and Groups > Login Options
+
         Disables the “Restart” option when users are logged in. Default is false.
       '';
     };
diff --git a/modules/system/defaults/spaces.nix b/modules/system/defaults/spaces.nix
index 8f256f3..ac2355b 100644
--- a/modules/system/defaults/spaces.nix
+++ b/modules/system/defaults/spaces.nix
@@ -8,7 +8,8 @@ with lib;
       type = types.nullOr types.bool;
       default = null;
       description = ''
-        # Apple menu > System Preferences > Mission Control
+        Apple menu > System Preferences > Mission Control
+
         Displays have separate Spaces (note a logout is required before
         this setting will take effect).
 
diff --git a/modules/system/patches.nix b/modules/system/patches.nix
index 452ed3b..0b56681 100644
--- a/modules/system/patches.nix
+++ b/modules/system/patches.nix
@@ -29,9 +29,9 @@ in
       description = ''
         Set of patches to apply to <filename>/</filename>.
 
-        <warning>
-        <para>This can modify everything so use with caution.</para>
-        </warning>
+        <warning><para>
+        This can modify everything so use with caution.
+        </para></warning>
 
         Useful for safely changing system files.  Unlike the etc module this
         won't remove or modify files with unexpected content.