nixos/manual: render module chapters with nixos-render-docs

this converts meta.doc into an md pointer, not an xml pointer. since we
no longer need xml for manual chapters we can also remove support for
manual chapters from md-to-db.sh

since pandoc converts smart quotes to docbook quote elements and our
nixos-render-docs does not we lose this distinction in the rendered
output. that's probably not that bad, our stylesheet didn't make use of
this anyway (and pre-23.05 versions of the chapters didn't use quote
elements either).

also updates the nixpkgs manual to clarify that option docs support all
extensions (although it doesn't support headings at all, so heading
anchors don't work by extension).

2 files changed, 1 insertions, 113 deletions

diff --git a/nixos/modules/services/mail/mailman.nix b/nixos/modules/services/mail/mailman.nix
index 2adc7427abf4..9273f71db7d5 100644
--- a/nixos/modules/services/mail/mailman.nix
+++ b/nixos/modules/services/mail/mailman.nix
@@ -642,7 +642,7 @@ in {
 
   meta = {
     maintainers = with lib.maintainers; [ lheckemann qyliss ma27 ];
-    doc = ./mailman.xml;
+    doc = ./mailman.md;
   };
 
 }
diff --git a/nixos/modules/services/mail/mailman.xml b/nixos/modules/services/mail/mailman.xml
deleted file mode 100644
index 23b0d0b7da4c..000000000000
--- a/nixos/modules/services/mail/mailman.xml
+++ /dev/null
@@ -1,112 +0,0 @@
-<!-- Do not edit this file directly, edit its companion .md instead
-     and regenerate this file using nixos/doc/manual/md-to-db.sh -->
-<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.
-  </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:
-    </para>
-    <programlisting>
-{ config, ... }: {
-  services.postfix = {
-    enable = true;
-    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 = [&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 = [&quot;lists.example.org&quot;];
-    siteOwner = &quot;mailman@example.org&quot;;
-  };
-  services.nginx.virtualHosts.&quot;lists.example.org&quot;.enableACME = true;
-  networking.firewall.allowedTCPPorts = [ 25 80 443 ];
-}
-</programlisting>
-    <para>
-      DNS records will also be required:
-    </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.
-    </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:
-    </para>
-    <programlisting>
-{ config, ... }: {
-  services = {
-    mailman = {
-      enable = true;
-      siteOwner = &quot;mailman@example.org&quot;;
-      enablePostfix = false;
-      settings.mta = {
-        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 = {
-      enable = true;
-      # You can configure Exim in a separate file to reduce configuration.nix clutter
-      config = builtins.readFile ./exim.conf;
-    };
-  };
-}
-</programlisting>
-    <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.
-    </para>
-  </section>
-</chapter>