nixos: nixos/doc/manual/configuration/wireless.xml to CommonMark

4 files changed, 141 insertions, 71 deletions

diff --git a/nixos/doc/manual/configuration/networking.xml b/nixos/doc/manual/configuration/networking.xml
index c24f87afc57..f5587195f1f 100644
--- a/nixos/doc/manual/configuration/networking.xml
+++ b/nixos/doc/manual/configuration/networking.xml
@@ -13,7 +13,7 @@
  <xi:include href="../from_md/configuration/ipv4-config.section.xml" />
  <xi:include href="../from_md/configuration/ipv6-config.section.xml" />
  <xi:include href="../from_md/configuration/firewall.section.xml" />
- <xi:include href="wireless.xml" />
+ <xi:include href="../from_md/configuration/wireless.section.xml" />
  <xi:include href="ad-hoc-network-config.xml" />
  <xi:include href="renaming-interfaces.xml" />
 <!-- TODO: OpenVPN, NAT -->
diff --git a/nixos/doc/manual/configuration/wireless.section.md b/nixos/doc/manual/configuration/wireless.section.md
new file mode 100644
index 00000000000..6b223d843ac
--- /dev/null
+++ b/nixos/doc/manual/configuration/wireless.section.md
@@ -0,0 +1,67 @@
+# Wireless Networks {#sec-wireless}
+
+For a desktop installation using NetworkManager (e.g., GNOME), you just
+have to make sure the user is in the `networkmanager` group and you can
+skip the rest of this section on wireless networks.
+
+NixOS will start wpa_supplicant for you if you enable this setting:
+
+```nix
+networking.wireless.enable = true;
+```
+
+NixOS lets you specify networks for wpa_supplicant declaratively:
+
+```nix
+networking.wireless.networks = {
+  echelon = {                # SSID with no spaces or special characters
+    psk = "abcdefgh";
+  };
+  "echelon's AP" = {         # SSID with spaces and/or special characters
+    psk = "ijklmnop";
+  };
+  echelon = {                # Hidden SSID
+    hidden = true;
+    psk = "qrstuvwx";
+  };
+  free.wifi = {};            # Public wireless network
+};
+```
+
+Be aware that keys will be written to the nix store in plaintext! When
+no networks are set, it will default to using a configuration file at
+`/etc/wpa_supplicant.conf`. You should edit this file yourself to define
+wireless networks, WPA keys and so on (see wpa_supplicant.conf(5)).
+
+If you are using WPA2 you can generate pskRaw key using
+`wpa_passphrase`:
+
+```ShellSession
+$ wpa_passphrase ESSID PSK
+network={
+        ssid="echelon"
+        #psk="abcdefgh"
+        psk=dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435
+}
+```
+
+```nix
+networking.wireless.networks = {
+  echelon = {
+    pskRaw = "dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435";
+  };
+}
+```
+
+or you can use it to directly generate the `wpa_supplicant.conf`:
+
+```ShellSession
+# wpa_passphrase ESSID PSK > /etc/wpa_supplicant.conf
+```
+
+After you have edited the `wpa_supplicant.conf`, you need to restart the
+wpa_supplicant service.
+
+```ShellSession
+# systemctl restart wpa_supplicant.service
+```
diff --git a/nixos/doc/manual/configuration/wireless.xml b/nixos/doc/manual/configuration/wireless.xml
deleted file mode 100644
index 247d29d5831..00000000000
--- a/nixos/doc/manual/configuration/wireless.xml
+++ /dev/null
@@ -1,70 +0,0 @@
-<section 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="sec-wireless">
- <title>Wireless Networks</title>
-
- <para>
-  For a desktop installation using NetworkManager (e.g., GNOME), you just have
-  to make sure the user is in the <code>networkmanager</code> group and you can
-  skip the rest of this section on wireless networks.
- </para>
-
- <para>
-  NixOS will start wpa_supplicant for you if you enable this setting:
-<programlisting>
-<xref linkend="opt-networking.wireless.enable"/> = true;
-</programlisting>
-  NixOS lets you specify networks for wpa_supplicant declaratively:
-<programlisting>
-<xref linkend="opt-networking.wireless.networks"/> = {
-  echelon = {                # SSID with no spaces or special characters
-    psk = "abcdefgh";
-  };
-  "echelon's AP" = {         # SSID with spaces and/or special characters
-    psk = "ijklmnop";
-  };
-  echelon = {                # Hidden SSID
-    hidden = true;
-    psk = "qrstuvwx";
-  };
-  free.wifi = {};            # Public wireless network
-};
-</programlisting>
-  Be aware that keys will be written to the nix store in plaintext! When no
-  networks are set, it will default to using a configuration file at
-  <literal>/etc/wpa_supplicant.conf</literal>. You should edit this file
-  yourself to define wireless networks, WPA keys and so on (see <citerefentry>
-  <refentrytitle>wpa_supplicant.conf</refentrytitle>
-  <manvolnum>5</manvolnum> </citerefentry>).
- </para>
-
- <para>
-  If you are using WPA2 you can generate pskRaw key using
-  <command>wpa_passphrase</command>:
-<screen>
-<prompt>$ </prompt>wpa_passphrase ESSID PSK
-network={
-        ssid="echelon"
-        #psk="abcdefgh"
-        psk=dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435
-}
-</screen>
-<programlisting>
-<xref linkend="opt-networking.wireless.networks"/> = {
-  echelon = {
-    pskRaw = "dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435";
-  };
-}
-</programlisting>
-  or you can use it to directly generate the
-  <literal>wpa_supplicant.conf</literal>:
-<screen>
-<prompt># </prompt>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>
-<prompt># </prompt>systemctl restart wpa_supplicant.service</screen>
- </para>
-</section>
diff --git a/nixos/doc/manual/from_md/configuration/wireless.section.xml b/nixos/doc/manual/from_md/configuration/wireless.section.xml
new file mode 100644
index 00000000000..82bc2013515
--- /dev/null
+++ b/nixos/doc/manual/from_md/configuration/wireless.section.xml
@@ -0,0 +1,73 @@
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="sec-wireless">
+  <title>Wireless Networks</title>
+  <para>
+    For a desktop installation using NetworkManager (e.g., GNOME), you
+    just have to make sure the user is in the
+    <literal>networkmanager</literal> group and you can skip the rest of
+    this section on wireless networks.
+  </para>
+  <para>
+    NixOS will start wpa_supplicant for you if you enable this setting:
+  </para>
+  <programlisting language="bash">
+networking.wireless.enable = true;
+</programlisting>
+  <para>
+    NixOS lets you specify networks for wpa_supplicant declaratively:
+  </para>
+  <programlisting language="bash">
+networking.wireless.networks = {
+  echelon = {                # SSID with no spaces or special characters
+    psk = &quot;abcdefgh&quot;;
+  };
+  &quot;echelon's AP&quot; = {         # SSID with spaces and/or special characters
+    psk = &quot;ijklmnop&quot;;
+  };
+  echelon = {                # Hidden SSID
+    hidden = true;
+    psk = &quot;qrstuvwx&quot;;
+  };
+  free.wifi = {};            # Public wireless network
+};
+</programlisting>
+  <para>
+    Be aware that keys will be written to the nix store in plaintext!
+    When no networks are set, it will default to using a configuration
+    file at <literal>/etc/wpa_supplicant.conf</literal>. You should edit
+    this file yourself to define wireless networks, WPA keys and so on
+    (see wpa_supplicant.conf(5)).
+  </para>
+  <para>
+    If you are using WPA2 you can generate pskRaw key using
+    <literal>wpa_passphrase</literal>:
+  </para>
+  <programlisting>
+$ wpa_passphrase ESSID PSK
+network={
+        ssid=&quot;echelon&quot;
+        #psk=&quot;abcdefgh&quot;
+        psk=dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435
+}
+</programlisting>
+  <programlisting language="bash">
+networking.wireless.networks = {
+  echelon = {
+    pskRaw = &quot;dca6d6ed41f4ab5a984c9f55f6f66d4efdc720ebf66959810f4329bb391c5435&quot;;
+  };
+}
+</programlisting>
+  <para>
+    or you can use it to directly generate the
+    <literal>wpa_supplicant.conf</literal>:
+  </para>
+  <programlisting>
+# wpa_passphrase ESSID PSK &gt; /etc/wpa_supplicant.conf
+</programlisting>
+  <para>
+    After you have edited the <literal>wpa_supplicant.conf</literal>,
+    you need to restart the wpa_supplicant service.
+  </para>
+  <programlisting>
+# systemctl restart wpa_supplicant.service
+</programlisting>
+</section>