nixos/manual: normalize <programlisting>

makes sure that program listing tags are separated from their contents by exactly a newline character. this makes the markdown translation easier to verify (since no new newlines need to be inserted), and there's no rendering difference anyway.
2023-01-04 00:45:35 +01:00 · 2023-01-04 00:45:35 +01:00 · 0715ecf936
commit 0715ecf936
parent 6930425922
11 changed files with 80 additions and 38 deletions
--- a/nixos/modules/services/backup/borgbackup.xml
+++ b/nixos/modules/services/backup/borgbackup.xml
@ -53,7 +53,8 @@
        };
      }
    };
-}</programlisting>
+}
+</programlisting>
  </para>
  <warning>
    <para>
@ -86,7 +87,8 @@ ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/
      path = "/var/lib/my_borg_repo" ;
    };
  };
-}</programlisting>
+}
+</programlisting>
    </para>
 </section>

@ -115,7 +117,8 @@ ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/
      startAt = "hourly";
    };
  };
-};</programlisting>
+};
+</programlisting>
  </para>
  <para>The following few commands (run as root) let you test your backup.
      <programlisting>
@ -127,7 +130,8 @@ ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAID78zmOyA+5uPG4Ot0hfAy+sLDPU1L4AiIoRYEIVbbQ/
 > export BORG_PASSPHRASE=topSecrect
 > 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>
+nixos-backupToLocalServer-2020-03-30T21:46:30 Mon, 2020-03-30 21:46:32 [e77321694ecd160ca2228611747c6ad1be177d6e0d894538898de7a2621b6e68]
+</programlisting>
    </para>
 </section>

@ -148,7 +152,9 @@ nixos-backupToLocalServer-2020-03-30T21:46:30 Mon, 2020-03-30 21:46:32 [e7732169
      Generate a SSH key without a password, to access the remote server. E.g.
    </para>
    <para>
-        <programlisting>sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_borgbase</programlisting>
+        <programlisting>
+sudo ssh-keygen -N '' -t ed25519 -f /run/keys/id_ed25519_borgbase
+</programlisting>
    </para>
  </listitem>
  <listitem>
@ -163,7 +169,8 @@ nixos-backupToLocalServer-2020-03-30T21:46:30 Mon, 2020-03-30 21:46:32 [e7732169
      <programlisting>
 sudo borg init --encryption=repokey-blake2  \
    -rsh "ssh -i /run/keys/id_ed25519_borgbase" \
-    zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo</programlisting>
+    zzz2aaaaa@zzz2aaaaa.repo.borgbase.com:repo
+</programlisting>
  </para>
  </listitem>
  <listitem>
@ -184,7 +191,8 @@ sudo borg init --encryption=repokey-blake2  \
        startAt = "daily";
    };
  };
-}}</programlisting>
+}}
+</programlisting>
  </para>
  </listitem>
 </itemizedlist>
--- a/nixos/modules/services/development/blackfire.xml
+++ b/nixos/modules/services/development/blackfire.xml
@ -13,7 +13,8 @@
 </para>
 <para>
  To use it, you will need to enable the agent and the probe on your server. The exact method will depend on the way you use PHP but here is an example of NixOS configuration for PHP-FPM:
-<programlisting>let
+<programlisting>
+let
  php = pkgs.php.withExtensions ({ enabled, all }: enabled ++ (with all; [
    blackfire
  ]));
@ -38,7 +39,8 @@ in {
  # (WantedBy= from the upstream unit not respected: https://github.com/NixOS/nixpkgs/issues/81138)
  # Alternately, you can start it manually with `systemctl start blackfire-agent`.
  systemd.services.blackfire-agent.wantedBy = [ "phpfpm-foo.service" ];
-}</programlisting>
+}
+</programlisting>
 </para>
 <para>
  On your developer machine, you will also want to install <link xlink:href="https://blackfire.io/docs/up-and-running/installation#install-a-profiling-client">the client</link> (see <package>blackfire</package> package) or the browser extension to actually trigger the profiling.
--- a/nixos/modules/services/editors/emacs.xml
+++ b/nixos/modules/services/editors/emacs.xml
@ -446,7 +446,9 @@ emacsclient --create-frame --tty  # opens a new frame on the current terminal
   <para>
    If you have formed certain bad habits when editing files, these can be
    corrected with a shell alias to the wrapper script:
-<programlisting>alias vi=$EDITOR</programlisting>
+    <programlisting>
+alias vi=$EDITOR
+</programlisting>
   </para>
  </section>

@ -467,7 +469,9 @@ services.emacs.install = true;
   <para>
    To enable the <command>systemd</command> user service for just the
    currently logged in user, run:
-<programlisting>systemctl --user enable emacs</programlisting>
+    <programlisting>
+systemctl --user enable emacs
+</programlisting>
    This will add the symlink
    <filename>~/.config/systemd/user/emacs.service</filename>.
   </para>
--- a/nixos/modules/services/mail/mailman.xml
+++ b/nixos/modules/services/mail/mailman.xml
@ -16,7 +16,8 @@
    <title>Basic usage with Postfix</title>
    <para>
      For a basic configuration with Postfix as the MTA, the following settings are suggested:
-      <programlisting>{ config, ... }: {
+      <programlisting>
+{ config, ... }: {
  services.postfix = {
    enable = true;
    relayDomains = ["hash:/var/lib/mailman/data/postfix_domains"];
@ -36,7 +37,8 @@
  };
  services.nginx.virtualHosts."lists.example.org".enableACME = true;
  networking.firewall.allowedTCPPorts = [ 25 80 443 ];
-}</programlisting>
+}
+</programlisting>
    </para>
    <para>
      DNS records will also be required:
@ -60,7 +62,8 @@
    <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>{ config, ... }: {
+      <programlisting>
+{ config, ... }: {
  services = {
    mailman = {
      enable = true;
@ -82,7 +85,8 @@
      config = builtins.readFile ./exim.conf;
    };
  };
-}</programlisting>
+}
+</programlisting>
    </para>
    <para>
      The exim config needs some special additions to work with Mailman. Currently
--- a/nixos/modules/services/matrix/synapse.xml
+++ b/nixos/modules/services/matrix/synapse.xml
@ -185,7 +185,9 @@ Success!
      <listitem>
       <para>
        Create a file with the following contents:
-<programlisting>registration_shared_secret: your-very-secret-secret</programlisting>
+<programlisting>
+registration_shared_secret: your-very-secret-secret
+</programlisting>
       </para>
      </listitem>
      <listitem>
--- a/nixos/modules/services/networking/prosody.xml
+++ b/nixos/modules/services/networking/prosody.xml
@ -54,7 +54,8 @@ services.prosody = {
  uploadHttp = {
      domain = "upload.example.org";
  };
-};</programlisting>
+};
+</programlisting>
  </para>
 </section>
 <section xml:id="module-services-prosody-letsencrypt">
@ -81,7 +82,8 @@ security.acme = {
      extraDomainNames = [ "conference.example.org" "upload.example.org" ];
    };
  };
-};</programlisting>
+};
+</programlisting>
 </para>
 </section>
 </chapter>
--- a/nixos/modules/services/web-apps/grocy.xml
+++ b/nixos/modules/services/web-apps/grocy.xml
@ -14,13 +14,15 @@
   <title>Basic usage</title>
   <para>
    A very basic configuration may look like this:
-<programlisting>{ pkgs, ... }:
+<programlisting>
+{ pkgs, ... }:
 {
  services.grocy = {
    enable = true;
    hostName = "grocy.tld";
  };
-}</programlisting>
+}
+</programlisting>
    This configures a simple vhost using <link linkend="opt-services.nginx.enable">nginx</link>
    which listens to <literal>grocy.tld</literal> with fully configured ACME/LE (this can be
    disabled by setting <link linkend="opt-services.grocy.nginx.enableSSL">services.grocy.nginx.enableSSL</link>
@ -39,7 +41,8 @@
   <para>
    The configuration for <literal>grocy</literal> is located at <literal>/etc/grocy/config.php</literal>.
    By default, the following settings can be defined in the NixOS-configuration:
-<programlisting>{ pkgs, ... }:
+<programlisting>
+{ pkgs, ... }:
 {
  services.grocy.settings = {
    # The default currency in the system for invoices etc.
@ -60,17 +63,20 @@
      firstDayOfWeek = 2;
    };
  };
-}</programlisting>
+}
+</programlisting>
   </para>
   <para>
    If you want to alter the configuration file on your own, you can do this manually with
    an expression like this:
-<programlisting>{ lib, ... }:
+<programlisting>
+{ lib, ... }:
 {
  environment.etc."grocy/config.php".text = lib.mkAfter ''
    // Arbitrary PHP code in grocy's configuration file
  '';
-}</programlisting>
+}
+</programlisting>
   </para>
  </section>

--- a/nixos/modules/services/web-apps/jitsi-meet.xml
+++ b/nixos/modules/services/web-apps/jitsi-meet.xml
@ -13,7 +13,8 @@
 <title>Basic usage</title>
   <para>
     A minimal configuration using Let's Encrypt for TLS certificates looks like this:
-<programlisting>{
+<programlisting>
+{
  services.jitsi-meet = {
    enable = true;
    hostName = "jitsi.example.com";
@ -22,7 +23,8 @@
  networking.firewall.allowedTCPPorts = [ 80 443 ];
  security.acme.email = "me@example.com";
  security.acme.acceptTerms = true;
-}</programlisting>
+}
+</programlisting>
   </para>
 </section>

@ -30,7 +32,8 @@
 <title>Configuration</title>
   <para>
     Here is the minimal configuration with additional configurations:
-<programlisting>{
+<programlisting>
+{
  services.jitsi-meet = {
    enable = true;
    hostName = "jitsi.example.com";
@ -48,7 +51,8 @@
  networking.firewall.allowedTCPPorts = [ 80 443 ];
  security.acme.email = "me@example.com";
  security.acme.acceptTerms = true;
-}</programlisting>
+}
+</programlisting>
   </para>
 </section>

--- a/nixos/modules/services/web-apps/nextcloud.xml
+++ b/nixos/modules/services/web-apps/nextcloud.xml
@ -28,7 +28,8 @@

  <para>
   A very basic configuration may look like this:
-<programlisting>{ pkgs, ... }:
+<programlisting>
+{ pkgs, ... }:
 {
  services.nextcloud = {
    enable = true;
@ -60,7 +61,8 @@
  };

  networking.firewall.allowedTCPPorts = [ 80 443 ];
-}</programlisting>
+}
+</programlisting>
  </para>

  <para>
@ -198,7 +200,8 @@
  </para>
  <para>
   An exemplary configuration may look like this:
-<programlisting>{ config, lib, pkgs, ... }: {
+<programlisting>
+{ config, lib, pkgs, ... }: {
  services.nginx.enable = false;
  services.nextcloud = {
    enable = true;
@ -238,7 +241,8 @@
      '';
    };
  };
-}</programlisting>
+}
+</programlisting>
  </para>
 </section>

@ -286,14 +290,16 @@
   in NixOS for a safe upgrade-path before removing those. In that case we should keep those
   packages, but mark them as insecure in an expression like this (in
   <literal>&lt;nixpkgs/pkgs/servers/nextcloud/default.nix&gt;</literal>):
-<programlisting>/* ... */
+<programlisting>
+/* ... */
 {
  nextcloud17 = generic {
    version = "17.0.x";
    sha256 = "0000000000000000000000000000000000000000000000000000";
    eol = true;
  };
-}</programlisting>
+}
+</programlisting>
  </para>

  <para>
--- a/nixos/modules/services/web-apps/plausible.xml
+++ b/nixos/modules/services/web-apps/plausible.xml
@ -16,7 +16,8 @@
  </para>
  <para>
   After that, <package>plausible</package> can be deployed like this:
-<programlisting>{
+<programlisting>
+{
  services.plausible = {
    enable = true;
    adminUser = {
@ -29,7 +30,8 @@
      secretKeybaseFile = "/run/secrets/plausible-secret-key-base"; <co xml:id='ex-plausible-cfg-secretbase' />
    };
  };
-}</programlisting>
+}
+</programlisting>
   <calloutlist>
    <callout arearefs='ex-plausible-cfg-activate'>
     <para>
--- a/nixos/modules/services/web-servers/garage-doc.xml
+++ b/nixos/modules/services/web-servers/garage-doc.xml
@ -119,14 +119,16 @@
   in NixOS for a safe upgrade-path before removing those. In that case we shold keep those
   packages, but mark them as insecure in an expression like this (in
   <literal>&lt;nixpkgs/pkgs/tools/filesystem/garage/default.nix&gt;</literal>):
-<programlisting>/* ... */
+<programlisting>
+/* ... */
 {
  garage_0_7_3 = generic {
    version = "0.7.3";
    sha256 = "0000000000000000000000000000000000000000000000000000";
    eol = true;
  };
-}</programlisting>
+}
+</programlisting>
  </para>

  <para>