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, 131 deletions

diff --git a/nixos/modules/services/misc/taskserver/default.nix b/nixos/modules/services/misc/taskserver/default.nix
index 7331c323adbaa..775b3b6d2eae9 100644
--- a/nixos/modules/services/misc/taskserver/default.nix
+++ b/nixos/modules/services/misc/taskserver/default.nix
@@ -566,5 +566,5 @@ in {
     })
   ];
 
-  meta.doc = ./default.xml;
+  meta.doc = ./default.md;
 }
diff --git a/nixos/modules/services/misc/taskserver/default.xml b/nixos/modules/services/misc/taskserver/default.xml
deleted file mode 100644
index bbb38211b7cae..0000000000000
--- a/nixos/modules/services/misc/taskserver/default.xml
+++ /dev/null
@@ -1,130 +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-taskserver">
-  <title>Taskserver</title>
-  <para>
-    Taskserver is the server component of
-    <link xlink:href="https://taskwarrior.org/">Taskwarrior</link>, a
-    free and open source todo list application.
-  </para>
-  <para>
-    <emphasis>Upstream documentation:</emphasis>
-    <link xlink:href="https://taskwarrior.org/docs/#taskd">https://taskwarrior.org/docs/#taskd</link>
-  </para>
-  <section xml:id="module-services-taskserver-configuration">
-    <title>Configuration</title>
-    <para>
-      Taskserver does all of its authentication via TLS using client
-      certificates, so you either need to roll your own CA or purchase a
-      certificate from a known CA, which allows creation of client
-      certificates. These certificates are usually advertised as
-      <quote>server certificates</quote>.
-    </para>
-    <para>
-      So in order to make it easier to handle your own CA, there is a
-      helper tool called <command>nixos-taskserver</command> which
-      manages the custom CA along with Taskserver organisations, users
-      and groups.
-    </para>
-    <para>
-      While the client certificates in Taskserver only authenticate
-      whether a user is allowed to connect, every user has its own UUID
-      which identifies it as an entity.
-    </para>
-    <para>
-      With <command>nixos-taskserver</command> the client certificate is
-      created along with the UUID of the user, so it handles all of the
-      credentials needed in order to setup the Taskwarrior client to
-      work with a Taskserver.
-    </para>
-  </section>
-  <section xml:id="module-services-taskserver-nixos-taskserver-tool">
-    <title>The nixos-taskserver tool</title>
-    <para>
-      Because Taskserver by default only provides scripts to setup users
-      imperatively, the <command>nixos-taskserver</command> tool is used
-      for addition and deletion of organisations along with users and
-      groups defined by
-      <xref linkend="opt-services.taskserver.organisations" /> and as
-      well for imperative set up.
-    </para>
-    <para>
-      The tool is designed to not interfere if the command is used to
-      manually set up some organisations, users or groups.
-    </para>
-    <para>
-      For example if you add a new organisation using
-      <command>nixos-taskserver org add foo</command>, the organisation
-      is not modified and deleted no matter what you define in
-      <option>services.taskserver.organisations</option>, even if you’re
-      adding the same organisation in that option.
-    </para>
-    <para>
-      The tool is modelled to imitate the official
-      <command>taskd</command> command, documentation for each
-      subcommand can be shown by using the <option>--help</option>
-      switch.
-    </para>
-  </section>
-  <section xml:id="module-services-taskserver-declarative-ca-management">
-    <title>Declarative/automatic CA management</title>
-    <para>
-      Everything is done according to what you specify in the module
-      options, however in order to set up a Taskwarrior client for
-      synchronisation with a Taskserver instance, you have to transfer
-      the keys and certificates to the client machine.
-    </para>
-    <para>
-      This is done using
-      <command>nixos-taskserver user export $orgname $username</command>
-      which is printing a shell script fragment to stdout which can
-      either be used verbatim or adjusted to import the user on the
-      client machine.
-    </para>
-    <para>
-      For example, let’s say you have the following configuration:
-    </para>
-    <programlisting>
-{
-  services.taskserver.enable = true;
-  services.taskserver.fqdn = &quot;server&quot;;
-  services.taskserver.listenHost = &quot;::&quot;;
-  services.taskserver.organisations.my-company.users = [ &quot;alice&quot; ];
-}
-</programlisting>
-    <para>
-      This creates an organisation called <literal>my-company</literal>
-      with the user <literal>alice</literal>.
-    </para>
-    <para>
-      Now in order to import the <literal>alice</literal> user to
-      another machine <literal>alicebox</literal>, all we need to do is
-      something like this:
-    </para>
-    <programlisting>
-$ ssh server nixos-taskserver user export my-company alice | sh
-</programlisting>
-    <para>
-      Of course, if no SSH daemon is available on the server you can
-      also copy &amp; paste it directly into a shell.
-    </para>
-    <para>
-      After this step the user should be set up and you can start
-      synchronising your tasks for the first time with
-      <command>task sync init</command> on <literal>alicebox</literal>.
-    </para>
-    <para>
-      Subsequent synchronisation requests merely require the command
-      <command>task sync</command> after that stage.
-    </para>
-  </section>
-  <section xml:id="module-services-taskserver-manual-ca-management">
-    <title>Manual CA management</title>
-    <para>
-      If you set any options within
-      <link linkend="opt-services.taskserver.pki.manual.ca.cert">service.taskserver.pki.manual</link>.*,
-      <command>nixos-taskserver</command> won’t issue certificates, but
-      you can still use it for adding or removing user accounts.
-    </para>
-  </section>
-</chapter>