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

diff --git a/nixos/modules/services/backup/borgbackup.nix b/nixos/modules/services/backup/borgbackup.nix
index c5fc09dcea028..bc2d79ac10ac6 100644
--- a/nixos/modules/services/backup/borgbackup.nix
+++ b/nixos/modules/services/backup/borgbackup.nix
@@ -226,7 +226,7 @@ let
 
 in {
   meta.maintainers = with maintainers; [ dotlambda ];
-  meta.doc = ./borgbackup.xml;
+  meta.doc = ./borgbackup.md;
 
   ###### interface
 
diff --git a/nixos/modules/services/backup/borgbackup.xml b/nixos/modules/services/backup/borgbackup.xml
deleted file mode 100644
index 2b9e0baa6d09a..0000000000000
--- a/nixos/modules/services/backup/borgbackup.xml
+++ /dev/null
@@ -1,215 +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-borgbase">
-  <title>BorgBackup</title>
-  <para>
-    <emphasis>Source:</emphasis>
-    <filename>modules/services/backup/borgbackup.nix</filename>
-  </para>
-  <para>
-    <emphasis>Upstream documentation:</emphasis>
-    <link xlink:href="https://borgbackup.readthedocs.io/">https://borgbackup.readthedocs.io/</link>
-  </para>
-  <para>
-    <link xlink:href="https://www.borgbackup.org/">BorgBackup</link>
-    (short: Borg) is a deduplicating backup program. Optionally, it
-    supports compression and authenticated encryption.
-  </para>
-  <para>
-    The main goal of Borg is to provide an efficient and secure way to
-    backup data. The data deduplication technique used makes Borg
-    suitable for daily backups since only changes are stored. The
-    authenticated encryption technique makes it suitable for backups to
-    not fully trusted targets.
-  </para>
-  <section xml:id="module-services-backup-borgbackup-configuring">
-    <title>Configuring</title>
-    <para>
-      A complete list of options for the Borgbase module may be found
-      <link linkend="opt-services.borgbackup.jobs">here</link>.
-    </para>
-  </section>
-  <section xml:id="opt-services-backup-borgbackup-local-directory">
-    <title>Basic usage for a local backup</title>
-    <para>
-      A very basic configuration for backing up to a locally accessible
-      directory is:
-    </para>
-    <programlisting>
-{
-    opt.services.borgbackup.jobs = {
-      { rootBackup = {
-          paths = &quot;/&quot;;
-          exclude = [ &quot;/nix&quot; &quot;/path/to/local/repo&quot; ];
-          repo = &quot;/path/to/local/repo&quot;;
-          doInit = true;
-          encryption = {
-            mode = &quot;repokey&quot;;
-            passphrase = &quot;secret&quot;;
-          };
-          compression = &quot;auto,lzma&quot;;
-          startAt = &quot;weekly&quot;;
-        };
-      }
-    };
-}
-</programlisting>
-    <warning>
-      <para>
-        If you do not want the passphrase to be stored in the
-        world-readable Nix store, use passCommand. You find an example
-        below.
-      </para>
-    </warning>
-  </section>
-  <section xml:id="opt-services-backup-create-server">
-    <title>Create a borg backup server</title>
-    <para>
-      You should use a different SSH key for each repository you write
-      to, because the specified keys are restricted to running borg
-      serve and can only access this single repository. You need the
-      output of the generate pub file.
-    </para>
-    <programlisting>
-# sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_my_borg_repo
-# cat /run/keys/id_ed25519_my_borg_repo
-ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos
-</programlisting>
-    <para>
-      Add the following snippet to your NixOS configuration:
-    </para>
-    <programlisting>
-{
-  services.borgbackup.repos = {
-    my_borg_repo = {
-      authorizedKeys = [
-        &quot;ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/ root@nixos&quot;
-      ] ;
-      path = &quot;/var/lib/my_borg_repo&quot; ;
-    };
-  };
-}
-</programlisting>
-  </section>
-  <section xml:id="opt-services-backup-borgbackup-remote-server">
-    <title>Backup to the borg repository server</title>
-    <para>
-      The following NixOS snippet creates an hourly backup to the
-      service (on the host nixos) as created in the section above. We
-      assume that you have stored a secret passphrasse in the file
-      <filename>/run/keys/borgbackup_passphrase</filename>, which should
-      be only accessible by root
-    </para>
-    <programlisting>
-{
-  services.borgbackup.jobs = {
-    backupToLocalServer = {
-      paths = [ &quot;/etc/nixos&quot; ];
-      doInit = true;
-      repo =  &quot;borg@nixos:.&quot; ;
-      encryption = {
-        mode = &quot;repokey-blake2&quot;;
-        passCommand = &quot;cat /run/keys/borgbackup_passphrase&quot;;
-      };
-      environment = { BORG_RSH = &quot;ssh -i /run/keys/id_ed25519_my_borg_repo&quot;; };
-      compression = &quot;auto,lzma&quot;;
-      startAt = &quot;hourly&quot;;
-    };
-  };
-};
-</programlisting>
-    <para>
-      The following few commands (run as root) let you test your backup.
-    </para>
-    <programlisting>
-&gt; nixos-rebuild switch
-...restarting the following units: polkit.service
-&gt; systemctl restart borgbackup-job-backupToLocalServer
-&gt; sleep 10
-&gt; systemctl restart borgbackup-job-backupToLocalServer
-&gt; export BORG_PASSPHRASE=topSecrect
-&gt; borg list --rsh='ssh -i /run/keys/id_ed25519_my_borg_repo' borg@nixos:.
-nixos-backupToLocalServer-2020-03-30T21:46:17 Mon, 2020-03-30 21:46:19 [84feb97710954931ca384182f5f3cb90665f35cef214760abd7350fb064786ac]
-nixos-backupToLocalServer-2020-03-30T21:46:30 Mon, 2020-03-30 21:46:32 [e77321694ecd160ca2228611747c6ad1be177d6e0d894538898de7a2621b6e68]
-</programlisting>
-  </section>
-  <section xml:id="opt-services-backup-borgbackup-borgbase">
-    <title>Backup to a hosting service</title>
-    <para>
-      Several companies offer
-      <link xlink:href="https://www.borgbackup.org/support/commercial.html">(paid)
-      hosting services</link> for Borg repositories.
-    </para>
-    <para>
-      To backup your home directory to borgbase you have to:
-    </para>
-    <itemizedlist>
-      <listitem>
-        <para>
-          Generate a SSH key without a password, to access the remote
-          server. E.g.
-        </para>
-        <programlisting>
-sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_borgbase
-</programlisting>
-      </listitem>
-      <listitem>
-        <para>
-          Create the repository on the server by following the
-          instructions for your hosting server.
-        </para>
-      </listitem>
-      <listitem>
-        <para>
-          Initialize the repository on the server. Eg.
-        </para>
-        <programlisting>
-sudo borg init --encryption=repokey-blake2  \
-    -rsh &quot;ssh -i /run/keys/id_ed25519_borgbase&quot; \
-    zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo
-</programlisting>
-      </listitem>
-      <listitem>
-        <para>
-          Add it to your NixOS configuration, e.g.
-        </para>
-        <programlisting>
-{
-    services.borgbackup.jobs = {
-    my_Remote_Backup = {
-        paths = [ &quot;/&quot; ];
-        exclude = [ &quot;/nix&quot; &quot;'**/.cache'&quot; ];
-        repo =  &quot;zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo&quot;;
-          encryption = {
-          mode = &quot;repokey-blake2&quot;;
-          passCommand = &quot;cat /run/keys/borgbackup_passphrase&quot;;
-        };
-        environment = { BORG_RSH = &quot;ssh -i /run/keys/id_ed25519_borgbase&quot;; };
-        compression = &quot;auto,lzma&quot;;
-        startAt = &quot;daily&quot;;
-    };
-  };
-}}
-</programlisting>
-      </listitem>
-    </itemizedlist>
-  </section>
-  <section xml:id="opt-services-backup-borgbackup-vorta">
-    <title>Vorta backup client for the desktop</title>
-    <para>
-      Vorta is a backup client for macOS and Linux desktops. It
-      integrates the mighty BorgBackup with your desktop environment to
-      protect your data from disk failure, ransomware and theft.
-    </para>
-    <para>
-      It can be installed in NixOS e.g. by adding
-      <literal>pkgs.vorta</literal> to
-      <xref linkend="opt-environment.systemPackages" />.
-    </para>
-    <para>
-      Details about using Vorta can be found under
-      <link xlink:href="https://vorta.borgbase.com/usage">https://vorta.borgbase.com</link>
-      .
-    </para>
-  </section>
-</chapter>