nixos/digitalbitbox: convert manual chapter to MD

3 files changed, 101 insertions, 58 deletions

diff --git a/nixos/modules/programs/digitalbitbox/default.nix b/nixos/modules/programs/digitalbitbox/default.nix
index 101ee8ddbaf..38420df3d9e 100644
--- a/nixos/modules/programs/digitalbitbox/default.nix
+++ b/nixos/modules/programs/digitalbitbox/default.nix
@@ -33,6 +33,8 @@ in
   };
 
   meta = {
+    # Don't edit the docbook xml directly, edit the md and generate it:
+    # `pandoc doc.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart > doc.xml`
     doc = ./doc.xml;
     maintainers = with lib.maintainers; [ vidbina ];
   };
diff --git a/nixos/modules/programs/digitalbitbox/doc.md b/nixos/modules/programs/digitalbitbox/doc.md
new file mode 100644
index 00000000000..9bca14e97ff
--- /dev/null
+++ b/nixos/modules/programs/digitalbitbox/doc.md
@@ -0,0 +1,47 @@
+# Digital Bitbox {#module-programs-digitalbitbox}
+
+Digital Bitbox is a hardware wallet and second-factor authenticator.
+
+The `digitalbitbox` programs module may be installed by setting
+`programs.digitalbitbox` to `true` in a manner similar to
+```
+programs.digitalbitbox.enable = true;
+```
+and bundles the `digitalbitbox` package (see [](#sec-digitalbitbox-package)),
+which contains the `dbb-app` and `dbb-cli` binaries, along with the hardware
+module (see [](#sec-digitalbitbox-hardware-module)) which sets up the necessary
+udev rules to access the device.
+
+Enabling the digitalbitbox module is pretty much the easiest way to get a
+Digital Bitbox device working on your system.
+
+For more information, see <https://digitalbitbox.com/start_linux>.
+
+## Package {#sec-digitalbitbox-package}
+
+The binaries, `dbb-app` (a GUI tool) and `dbb-cli` (a CLI tool), are available
+through the `digitalbitbox` package which could be installed as follows:
+```
+environment.systemPackages = [
+  pkgs.digitalbitbox
+];
+```
+
+## Hardware {#sec-digitalbitbox-hardware-module}
+
+The digitalbitbox hardware package enables the udev rules for Digital Bitbox
+devices and may be installed as follows:
+```
+hardware.digitalbitbox.enable = true;
+```
+
+In order to alter the udev rules, one may provide different values for the
+`udevRule51` and `udevRule52` attributes by means of overriding as follows:
+```
+programs.digitalbitbox = {
+  enable = true;
+  package = pkgs.digitalbitbox.override {
+    udevRule51 = "something else";
+  };
+};
+```
diff --git a/nixos/modules/programs/digitalbitbox/doc.xml b/nixos/modules/programs/digitalbitbox/doc.xml
index e4ac6195dae..30150640504 100644
--- a/nixos/modules/programs/digitalbitbox/doc.xml
+++ b/nixos/modules/programs/digitalbitbox/doc.xml
@@ -1,74 +1,68 @@
-<chapter xmlns="http://docbook.org/ns/docbook"
-         xmlns:xlink="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0"
-         xml:id="module-programs-digitalbitbox">
- <title>Digital Bitbox</title>
- <para>
-  Digital Bitbox is a hardware wallet and second-factor authenticator.
- </para>
- <para>
-  The <literal>digitalbitbox</literal> programs module may be installed by
-  setting <literal>programs.digitalbitbox</literal> to <literal>true</literal>
-  in a manner similar to
-<programlisting>
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-programs-digitalbitbox">
+  <title>Digital Bitbox</title>
+  <para>
+    Digital Bitbox is a hardware wallet and second-factor authenticator.
+  </para>
+  <para>
+    The <literal>digitalbitbox</literal> programs module may be
+    installed by setting <literal>programs.digitalbitbox</literal> to
+    <literal>true</literal> in a manner similar to
+  </para>
+  <programlisting>
 programs.digitalbitbox.enable = true;
 </programlisting>
-  and bundles the <literal>digitalbitbox</literal> package (see
-  <xref
-      linkend="sec-digitalbitbox-package" />), which contains the
-  <literal>dbb-app</literal> and <literal>dbb-cli</literal> binaries, along
-  with the hardware module (see
-  <xref
-      linkend="sec-digitalbitbox-hardware-module" />) which sets up the
-  necessary udev rules to access the device.
- </para>
- <para>
-  Enabling the digitalbitbox module is pretty much the easiest way to get a
-  Digital Bitbox device working on your system.
- </para>
- <para>
-  For more information, see
-  <link xlink:href="https://digitalbitbox.com/start_linux" />.
- </para>
- <section xml:id="sec-digitalbitbox-package">
-  <title>Package</title>
-
   <para>
-   The binaries, <literal>dbb-app</literal> (a GUI tool) and
-   <literal>dbb-cli</literal> (a CLI tool), are available through the
-   <literal>digitalbitbox</literal> package which could be installed as
-   follows:
-<programlisting>
+    and bundles the <literal>digitalbitbox</literal> package (see
+    <xref linkend="sec-digitalbitbox-package"></xref>), which contains
+    the <literal>dbb-app</literal> and <literal>dbb-cli</literal>
+    binaries, along with the hardware module (see
+    <xref linkend="sec-digitalbitbox-hardware-module"></xref>) which
+    sets up the necessary udev rules to access the device.
+  </para>
+  <para>
+    Enabling the digitalbitbox module is pretty much the easiest way to
+    get a Digital Bitbox device working on your system.
+  </para>
+  <para>
+    For more information, see
+    <link xlink:href="https://digitalbitbox.com/start_linux" role="uri">https://digitalbitbox.com/start_linux</link>.
+  </para>
+  <section xml:id="sec-digitalbitbox-package">
+    <title>Package</title>
+    <para>
+      The binaries, <literal>dbb-app</literal> (a GUI tool) and
+      <literal>dbb-cli</literal> (a CLI tool), are available through the
+      <literal>digitalbitbox</literal> package which could be installed
+      as follows:
+    </para>
+    <programlisting>
 environment.systemPackages = [
   pkgs.digitalbitbox
 ];
 </programlisting>
-  </para>
- </section>
- <section xml:id="sec-digitalbitbox-hardware-module">
-  <title>Hardware</title>
-
-  <para>
-   The digitalbitbox hardware package enables the udev rules for Digital Bitbox
-   devices and may be installed as follows:
-<programlisting>
+  </section>
+  <section xml:id="sec-digitalbitbox-hardware-module">
+    <title>Hardware</title>
+    <para>
+      The digitalbitbox hardware package enables the udev rules for
+      Digital Bitbox devices and may be installed as follows:
+    </para>
+    <programlisting>
 hardware.digitalbitbox.enable = true;
 </programlisting>
-  </para>
-
-  <para>
-   In order to alter the udev rules, one may provide different values for the
-   <literal>udevRule51</literal> and <literal>udevRule52</literal> attributes
-   by means of overriding as follows:
-<programlisting>
+    <para>
+      In order to alter the udev rules, one may provide different values
+      for the <literal>udevRule51</literal> and
+      <literal>udevRule52</literal> attributes by means of overriding as
+      follows:
+    </para>
+    <programlisting>
 programs.digitalbitbox = {
   enable = true;
   package = pkgs.digitalbitbox.override {
-    udevRule51 = "something else";
+    udevRule51 = &quot;something else&quot;;
   };
 };
 </programlisting>
-  </para>
- </section>
+  </section>
 </chapter>