nixos/mailman: convert manual chapter to MD

3 files changed, 141 insertions, 45 deletions

diff --git a/nixos/modules/services/mail/mailman.md b/nixos/modules/services/mail/mailman.md
new file mode 100644
index 00000000000..55b61f8a258
--- /dev/null
+++ b/nixos/modules/services/mail/mailman.md
@@ -0,0 +1,82 @@
+# Mailman {#module-services-mailman}
+
+[Mailman](https://www.list.org) is free
+software for managing electronic mail discussion and e-newsletter
+lists. Mailman and its web interface can be configured using the
+corresponding NixOS module. Note that this service is best used with
+an existing, securely configured Postfix setup, as it does not automatically configure this.
+
+## Basic usage with Postfix {#module-services-mailman-basic-usage}
+
+For a basic configuration with Postfix as the MTA, the following settings are suggested:
+```
+{ config, ... }: {
+  services.postfix = {
+    enable = true;
+    relayDomains = ["hash:/var/lib/mailman/data/postfix_domains"];
+    sslCert = config.security.acme.certs."lists.example.org".directory + "/full.pem";
+    sslKey = config.security.acme.certs."lists.example.org".directory + "/key.pem";
+    config = {
+      transport_maps = ["hash:/var/lib/mailman/data/postfix_lmtp"];
+      local_recipient_maps = ["hash:/var/lib/mailman/data/postfix_lmtp"];
+    };
+  };
+  services.mailman = {
+    enable = true;
+    serve.enable = true;
+    hyperkitty.enable = true;
+    webHosts = ["lists.example.org"];
+    siteOwner = "mailman@example.org";
+  };
+  services.nginx.virtualHosts."lists.example.org".enableACME = true;
+  networking.firewall.allowedTCPPorts = [ 25 80 443 ];
+}
+```
+
+DNS records will also be required:
+
+  - `AAAA` and `A` records pointing to the host in question, in order for browsers to be able to discover the address of the web server;
+  - An `MX` record pointing to a domain name at which the host is reachable, in order for other mail servers to be able to deliver emails to the mailing lists it hosts.
+
+After this has been done and appropriate DNS records have been
+set up, the Postorius mailing list manager and the Hyperkitty
+archive browser will be available at
+https://lists.example.org/. Note that this setup is not
+sufficient to deliver emails to most email providers nor to
+avoid spam -- a number of additional measures for authenticating
+incoming and outgoing mails, such as SPF, DMARC and DKIM are
+necessary, but outside the scope of the Mailman module.
+
+## Using with other MTAs {#module-services-mailman-other-mtas}
+
+Mailman also supports other MTA, though with a little bit more configuration. For example, to use Mailman with Exim, you can use the following settings:
+```
+{ config, ... }: {
+  services = {
+    mailman = {
+      enable = true;
+      siteOwner = "mailman@example.org";
+      enablePostfix = false;
+      settings.mta = {
+        incoming = "mailman.mta.exim4.LMTP";
+        outgoing = "mailman.mta.deliver.deliver";
+        lmtp_host = "localhost";
+        lmtp_port = "8024";
+        smtp_host = "localhost";
+        smtp_port = "25";
+        configuration = "python:mailman.config.exim4";
+      };
+    };
+    exim = {
+      enable = true;
+      # You can configure Exim in a separate file to reduce configuration.nix clutter
+      config = builtins.readFile ./exim.conf;
+    };
+  };
+}
+```
+
+The exim config needs some special additions to work with Mailman. Currently
+NixOS can't manage Exim config with such granularity. Please refer to
+[Mailman documentation](https://mailman.readthedocs.io/en/latest/src/mailman/docs/mta.html)
+for more info on configuring Mailman for working with Exim.
diff --git a/nixos/modules/services/mail/mailman.nix b/nixos/modules/services/mail/mailman.nix
index 2adc7427abf..cc072505c3c 100644
--- a/nixos/modules/services/mail/mailman.nix
+++ b/nixos/modules/services/mail/mailman.nix
@@ -642,6 +642,8 @@ in {
 
   meta = {
     maintainers = with lib.maintainers; [ lheckemann qyliss ma27 ];
+    # Don't edit the docbook xml directly, edit the md and generate it:
+    # `pandoc mailman.md -t docbook --top-level-division=chapter --extract-media=media -f markdown-smart --lua-filter ../../../../doc/build-aux/pandoc-filters/myst-reader/roles.lua --lua-filter ../../../../doc/build-aux/pandoc-filters/docbook-writer/rst-roles.lua > mailman.xml`
     doc = ./mailman.xml;
   };
 
diff --git a/nixos/modules/services/mail/mailman.xml b/nixos/modules/services/mail/mailman.xml
index c1ad5d1a285..115f3225333 100644
--- a/nixos/modules/services/mail/mailman.xml
+++ b/nixos/modules/services/mail/mailman.xml
@@ -1,82 +1,93 @@
-<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-services-mailman">
+<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="module-services-mailman">
   <title>Mailman</title>
   <para>
     <link xlink:href="https://www.list.org">Mailman</link> is free
     software for managing electronic mail discussion and e-newsletter
     lists. Mailman and its web interface can be configured using the
     corresponding NixOS module. Note that this service is best used with
-    an existing, securely configured Postfix setup, as it does not automatically configure this.
+    an existing, securely configured Postfix setup, as it does not
+    automatically configure this.
   </para>
-
   <section xml:id="module-services-mailman-basic-usage">
     <title>Basic usage with Postfix</title>
     <para>
-      For a basic configuration with Postfix as the MTA, the following settings are suggested:
-      <programlisting>
+      For a basic configuration with Postfix as the MTA, the following
+      settings are suggested:
+    </para>
+    <programlisting>
 { config, ... }: {
   services.postfix = {
     enable = true;
-    relayDomains = ["hash:/var/lib/mailman/data/postfix_domains"];
-    sslCert = config.security.acme.certs."lists.example.org".directory + "/full.pem";
-    sslKey = config.security.acme.certs."lists.example.org".directory + "/key.pem";
+    relayDomains = [&quot;hash:/var/lib/mailman/data/postfix_domains&quot;];
+    sslCert = config.security.acme.certs.&quot;lists.example.org&quot;.directory + &quot;/full.pem&quot;;
+    sslKey = config.security.acme.certs.&quot;lists.example.org&quot;.directory + &quot;/key.pem&quot;;
     config = {
-      transport_maps = ["hash:/var/lib/mailman/data/postfix_lmtp"];
-      local_recipient_maps = ["hash:/var/lib/mailman/data/postfix_lmtp"];
+      transport_maps = [&quot;hash:/var/lib/mailman/data/postfix_lmtp&quot;];
+      local_recipient_maps = [&quot;hash:/var/lib/mailman/data/postfix_lmtp&quot;];
     };
   };
   services.mailman = {
     enable = true;
     serve.enable = true;
     hyperkitty.enable = true;
-    webHosts = ["lists.example.org"];
-    siteOwner = "mailman@example.org";
+    webHosts = [&quot;lists.example.org&quot;];
+    siteOwner = &quot;mailman@example.org&quot;;
   };
-  services.nginx.virtualHosts."lists.example.org".enableACME = true;
+  services.nginx.virtualHosts.&quot;lists.example.org&quot;.enableACME = true;
   networking.firewall.allowedTCPPorts = [ 25 80 443 ];
 }
 </programlisting>
-    </para>
     <para>
       DNS records will also be required:
-      <itemizedlist>
-        <listitem><para><literal>AAAA</literal> and <literal>A</literal> records pointing to the host in question, in order for browsers to be able to discover the address of the web server;</para></listitem>
-        <listitem><para>An <literal>MX</literal> record pointing to a domain name at which the host is reachable, in order for other mail servers to be able to deliver emails to the mailing lists it hosts.</para></listitem>
-      </itemizedlist>
     </para>
+    <itemizedlist spacing="compact">
+      <listitem>
+        <para>
+          <literal>AAAA</literal> and <literal>A</literal> records
+          pointing to the host in question, in order for browsers to be
+          able to discover the address of the web server;
+        </para>
+      </listitem>
+      <listitem>
+        <para>
+          An <literal>MX</literal> record pointing to a domain name at
+          which the host is reachable, in order for other mail servers
+          to be able to deliver emails to the mailing lists it hosts.
+        </para>
+      </listitem>
+    </itemizedlist>
     <para>
-      After this has been done and appropriate DNS records have been
-      set up, the Postorius mailing list manager and the Hyperkitty
-      archive browser will be available at
-      https://lists.example.org/. Note that this setup is not
-      sufficient to deliver emails to most email providers nor to
-      avoid spam -- a number of additional measures for authenticating
-      incoming and outgoing mails, such as SPF, DMARC and DKIM are
-      necessary, but outside the scope of the Mailman module.
+      After this has been done and appropriate DNS records have been set
+      up, the Postorius mailing list manager and the Hyperkitty archive
+      browser will be available at https://lists.example.org/. Note that
+      this setup is not sufficient to deliver emails to most email
+      providers nor to avoid spam -- a number of additional measures for
+      authenticating incoming and outgoing mails, such as SPF, DMARC and
+      DKIM are necessary, but outside the scope of the Mailman module.
     </para>
   </section>
   <section xml:id="module-services-mailman-other-mtas">
     <title>Using with other MTAs</title>
     <para>
-      Mailman also supports other MTA, though with a little bit more configuration. For example, to use Mailman with Exim, you can use the following settings:
-      <programlisting>
+      Mailman also supports other MTA, though with a little bit more
+      configuration. For example, to use Mailman with Exim, you can use
+      the following settings:
+    </para>
+    <programlisting>
 { config, ... }: {
   services = {
     mailman = {
       enable = true;
-      siteOwner = "mailman@example.org";
+      siteOwner = &quot;mailman@example.org&quot;;
       enablePostfix = false;
       settings.mta = {
-        incoming = "mailman.mta.exim4.LMTP";
-        outgoing = "mailman.mta.deliver.deliver";
-        lmtp_host = "localhost";
-        lmtp_port = "8024";
-        smtp_host = "localhost";
-        smtp_port = "25";
-        configuration = "python:mailman.config.exim4";
+        incoming = &quot;mailman.mta.exim4.LMTP&quot;;
+        outgoing = &quot;mailman.mta.deliver.deliver&quot;;
+        lmtp_host = &quot;localhost&quot;;
+        lmtp_port = &quot;8024&quot;;
+        smtp_host = &quot;localhost&quot;;
+        smtp_port = &quot;25&quot;;
+        configuration = &quot;python:mailman.config.exim4&quot;;
       };
     };
     exim = {
@@ -87,12 +98,13 @@
   };
 }
 </programlisting>
-    </para>
     <para>
-      The exim config needs some special additions to work with Mailman. Currently
-      NixOS can't manage Exim config with such granularity. Please refer to
-      <link xlink:href="https://mailman.readthedocs.io/en/latest/src/mailman/docs/mta.html">Mailman documentation</link>
-      for more info on configuring Mailman for working with Exim.
+      The exim config needs some special additions to work with Mailman.
+      Currently NixOS can't manage Exim config with such granularity.
+      Please refer to
+      <link xlink:href="https://mailman.readthedocs.io/en/latest/src/mailman/docs/mta.html">Mailman
+      documentation</link> for more info on configuring Mailman for
+      working with Exim.
     </para>
   </section>
 </chapter>