nixos/doc: clean up defaults and examples

3 years ago · 2ddc335e6f
parent 330b1e08b8
commit 2ddc335e6f
584 changed files with 1612 additions and 1554 deletions
--- a/nixos/doc/manual/development/option-declarations.section.md
+++ b/nixos/doc/manual/development/option-declarations.section.md
@ -38,9 +38,19 @@ The function `mkOption` accepts the following arguments.
    of the module will have to define the value of the option, otherwise
    an error will be thrown.

+`defaultText`
+
+:   A textual representation of the default value to be rendered verbatim in
+    the manual. Useful if the default value is a complex expression or depends
+    on other values or packages.
+    Use `lib.literalExpression` for a Nix expression, `lib.literalDocBook` for
+    a plain English description in DocBook format.
+
 `example`

 :   An example value that will be shown in the NixOS manual.
+    You can use `lib.literalExpression` and `lib.literalDocBook` in the same way
+    as in `defaultText`.

 `description`

--- a/nixos/doc/manual/from_md/development/option-declarations.section.xml
+++ b/nixos/doc/manual/from_md/development/option-declarations.section.xml
@ -57,13 +57,31 @@ options = {
        </para>
      </listitem>
    </varlistentry>
+    <varlistentry>
+      <term>
+        <literal>defaultText</literal>
+      </term>
+      <listitem>
+        <para>
+          A textual representation of the default value to be rendered
+          verbatim in the manual. Useful if the default value is a
+          complex expression or depends on other values or packages. Use
+          <literal>lib.literalExpression</literal> for a Nix expression,
+          <literal>lib.literalDocBook</literal> for a plain English
+          description in DocBook format.
+        </para>
+      </listitem>
+    </varlistentry>
    <varlistentry>
      <term>
        <literal>example</literal>
      </term>
      <listitem>
        <para>
-          An example value that will be shown in the NixOS manual.
+          An example value that will be shown in the NixOS manual. You
+          can use <literal>lib.literalExpression</literal> and
+          <literal>lib.literalDocBook</literal> in the same way as in
+          <literal>defaultText</literal>.
        </para>
      </listitem>
    </varlistentry>
--- a/nixos/maintainers/scripts/ec2/amazon-image.nix
+++ b/nixos/maintainers/scripts/ec2/amazon-image.nix
@ -27,7 +27,7 @@ in {
    };

    contents = mkOption {
-      example = literalExample ''
+      example = literalExpression ''
        [ { source = pkgs.memtest86 + "/memtest.bin";
            target = "boot/memtest.bin";
          }
--- a/nixos/modules/config/fonts/fonts.nix
+++ b/nixos/modules/config/fonts/fonts.nix
@ -61,7 +61,7 @@ in
      fonts = mkOption {
        type = types.listOf types.path;
        default = [];
-        example = literalExample "[ pkgs.dejavu_fonts ]";
+        example = literalExpression "[ pkgs.dejavu_fonts ]";
        description = "List of primary font paths.";
      };

--- a/nixos/modules/config/i18n.nix
+++ b/nixos/modules/config/i18n.nix
@ -14,7 +14,7 @@ with lib;
          allLocales = any (x: x == "all") config.i18n.supportedLocales;
          locales = config.i18n.supportedLocales;
        };
-        example = literalExample "pkgs.glibcLocales";
+        example = literalExpression "pkgs.glibcLocales";
        description = ''
          Customized pkg.glibcLocales package.

--- a/nixos/modules/config/krb5/default.nix
+++ b/nixos/modules/config/krb5/default.nix
@ -83,8 +83,8 @@ in {
      kerberos = mkOption {
        type = types.package;
        default = pkgs.krb5Full;
-        defaultText = "pkgs.krb5Full";
-        example = literalExample "pkgs.heimdal";
+        defaultText = literalExpression "pkgs.krb5Full";
+        example = literalExpression "pkgs.heimdal";
        description = ''
          The Kerberos implementation that will be present in
          <literal>environment.systemPackages</literal> after enabling this
@ -96,7 +96,7 @@ in {
        type = with types; either attrs lines;
        default = {};
        apply = attrs: filterEmbeddedMetadata attrs;
-        example = literalExample ''
+        example = literalExpression ''
          {
            default_realm = "ATHENA.MIT.EDU";
          };
@ -109,7 +109,7 @@ in {
      realms = mkOption {
        type = with types; either attrs lines;
        default = {};
-        example = literalExample ''
+        example = literalExpression ''
          {
            "ATHENA.MIT.EDU" = {
              admin_server = "athena.mit.edu";
@ -127,7 +127,7 @@ in {
      domain_realm = mkOption {
        type = with types; either attrs lines;
        default = {};
-        example = literalExample ''
+        example = literalExpression ''
          {
            "example.com" = "EXAMPLE.COM";
            ".example.com" = "EXAMPLE.COM";
@ -142,7 +142,7 @@ in {
      capaths = mkOption {
        type = with types; either attrs lines;
        default = {};
-        example = literalExample ''
+        example = literalExpression ''
          {
            "ATHENA.MIT.EDU" = {
              "EXAMPLE.COM" = ".";
@ -161,7 +161,7 @@ in {
      appdefaults = mkOption {
        type = with types; either attrs lines;
        default = {};
-        example = literalExample ''
+        example = literalExpression ''
          {
            pam = {
              debug = false;
@ -182,7 +182,7 @@ in {
      plugins = mkOption {
        type = with types; either attrs lines;
        default = {};
-        example = literalExample ''
+        example = literalExpression ''
          {
            ccselect = {
              disable = "k5identity";
--- a/nixos/modules/config/networking.nix
+++ b/nixos/modules/config/networking.nix
@ -21,7 +21,7 @@ in

    networking.hosts = lib.mkOption {
      type = types.attrsOf (types.listOf types.str);
-      example = literalExample ''
+      example = literalExpression ''
        {
          "127.0.0.1" = [ "foo.bar.baz" ];
          "192.168.0.2" = [ "fileserver.local" "nameserver.local" ];
@ -34,8 +34,8 @@ in

    networking.hostFiles = lib.mkOption {
      type = types.listOf types.path;
-      defaultText = lib.literalExample "Hosts from `networking.hosts` and `networking.extraHosts`";
-      example = lib.literalExample ''[ "''${pkgs.my-blocklist-package}/share/my-blocklist/hosts" ]'';
+      defaultText = literalDocBook "Hosts from <option>networking.hosts</option> and <option>networking.extraHosts</option>";
+      example = literalExpression ''[ "''${pkgs.my-blocklist-package}/share/my-blocklist/hosts" ]'';
      description = ''
        Files that should be concatenated together to form <filename>/etc/hosts</filename>.
      '';
--- a/nixos/modules/config/power-management.nix
+++ b/nixos/modules/config/power-management.nix
@ -35,7 +35,7 @@ in
      powerUpCommands = mkOption {
        type = types.lines;
        default = "";
-        example = literalExample ''
+        example = literalExpression ''
          "''${pkgs.hdparm}/sbin/hdparm -B 255 /dev/sda"
        '';
        description =
@ -49,7 +49,7 @@ in
      powerDownCommands = mkOption {
        type = types.lines;
        default = "";
-        example = literalExample ''
+        example = literalExpression ''
          "''${pkgs.hdparm}/sbin/hdparm -B 255 /dev/sda"
        '';
        description =
--- a/nixos/modules/config/pulseaudio.nix
+++ b/nixos/modules/config/pulseaudio.nix
@ -149,8 +149,8 @@ in {
        default = if config.services.jack.jackd.enable
                  then pkgs.pulseaudioFull
                  else pkgs.pulseaudio;
-        defaultText = "pkgs.pulseaudio";
-        example = literalExample "pkgs.pulseaudioFull";
+        defaultText = literalExpression "pkgs.pulseaudio";
+        example = literalExpression "pkgs.pulseaudioFull";
        description = ''
          The PulseAudio derivation to use.  This can be used to enable
          features (such as JACK support, Bluetooth) via the
@ -161,7 +161,7 @@ in {
      extraModules = mkOption {
        type = types.listOf types.package;
        default = [];
-        example = literalExample "[ pkgs.pulseaudio-modules-bt ]";
+        example = literalExpression "[ pkgs.pulseaudio-modules-bt ]";
        description = ''
          Extra pulseaudio modules to use. This is intended for out-of-tree
          pulseaudio modules like extra bluetooth codecs.
@ -184,7 +184,7 @@ in {
          type = types.attrsOf types.unspecified;
          default = {};
          description = "Config of the pulse daemon. See <literal>man pulse-daemon.conf</literal>.";
-          example = literalExample ''{ realtime-scheduling = "yes"; }'';
+          example = literalExpression ''{ realtime-scheduling = "yes"; }'';
        };
      };

@ -204,7 +204,7 @@ in {
          allowedIpRanges = mkOption {
            type = types.listOf types.str;
            default = [];
-            example = literalExample ''[ "127.0.0.1" "192.168.1.0/24" ]'';
+            example = literalExpression ''[ "127.0.0.1" "192.168.1.0/24" ]'';
            description = ''
              A list of IP subnets that are allowed to stream to the server.
            '';
--- a/nixos/modules/config/shells-environment.nix
+++ b/nixos/modules/config/shells-environment.nix
@ -136,10 +136,8 @@ in

    environment.binsh = mkOption {
      default = "${config.system.build.binsh}/bin/sh";
-      defaultText = "\${config.system.build.binsh}/bin/sh";
-      example = literalExample ''
-        "''${pkgs.dash}/bin/dash"
-      '';
+      defaultText = literalExpression ''"''${config.system.build.binsh}/bin/sh"'';
+      example = literalExpression ''"''${pkgs.dash}/bin/dash"'';
      type = types.path;
      visible = false;
      description = ''
@ -152,7 +150,7 @@ in

    environment.shells = mkOption {
      default = [];
-      example = literalExample "[ pkgs.bashInteractive pkgs.zsh ]";
+      example = literalExpression "[ pkgs.bashInteractive pkgs.zsh ]";
      description = ''
        A list of permissible login shells for user accounts.
        No need to mention <literal>/bin/sh</literal>
--- a/nixos/modules/config/sysctl.nix
+++ b/nixos/modules/config/sysctl.nix
@ -22,7 +22,7 @@ in

    boot.kernel.sysctl = mkOption {
      default = {};
-      example = literalExample ''
+      example = literalExpression ''
        { "net.ipv4.tcp_syncookies" = false; "vm.swappiness" = 60; }
      '';
      type = types.attrsOf sysctlOption;
--- a/nixos/modules/config/system-path.nix
+++ b/nixos/modules/config/system-path.nix
@ -58,7 +58,7 @@ in
      systemPackages = mkOption {
        type = types.listOf types.package;
        default = [];
-        example = literalExample "[ pkgs.firefox pkgs.thunderbird ]";
+        example = literalExpression "[ pkgs.firefox pkgs.thunderbird ]";
        description = ''
          The set of packages that appear in
          /run/current-system/sw.  These packages are
@ -73,9 +73,9 @@ in
      defaultPackages = mkOption {
        type = types.listOf types.package;
        default = defaultPackages;
-        example = literalExample "[]";
+        example = [];
        description = ''
-          Set of default packages that aren't strictly neccessary
+          Set of default packages that aren't strictly necessary
          for a running system, entries can be removed for a more
          minimal NixOS installation.

--- a/nixos/modules/config/unix-odbc-drivers.nix
+++ b/nixos/modules/config/unix-odbc-drivers.nix
@ -19,7 +19,7 @@ in {
    environment.unixODBCDrivers = mkOption {
      type = types.listOf types.package;
      default = [];
-      example = literalExample "with pkgs.unixODBCDrivers; [ sqlite psql ]";
+      example = literalExpression "with pkgs.unixODBCDrivers; [ sqlite psql ]";
      description = ''
        Specifies Unix ODBC drivers to be registered in
        <filename>/etc/odbcinst.ini</filename>.  You may also want to
--- a/nixos/modules/config/users-groups.nix
+++ b/nixos/modules/config/users-groups.nix
@ -165,8 +165,8 @@ let
      shell = mkOption {
        type = types.nullOr (types.either types.shellPackage (passwdEntry types.path));
        default = pkgs.shadow;
-        defaultText = "pkgs.shadow";
-        example = literalExample "pkgs.bashInteractive";
+        defaultText = literalExpression "pkgs.shadow";
+        example = literalExpression "pkgs.bashInteractive";
        description = ''
          The path to the user's shell. Can use shell derivations,
          like <literal>pkgs.bashInteractive</literal>. Don’t
@ -291,7 +291,7 @@ let
      packages = mkOption {
        type = types.listOf types.package;
        default = [];
-        example = literalExample "[ pkgs.firefox pkgs.thunderbird ]";
+        example = literalExpression "[ pkgs.firefox pkgs.thunderbird ]";
        description = ''
          The set of packages that should be made available to the user.
          This is in contrast to <option>environment.systemPackages</option>,
--- a/nixos/modules/config/xdg/portals/wlr.nix
+++ b/nixos/modules/config/xdg/portals/wlr.nix
@ -37,7 +37,7 @@ in
      default = { };

      # Example taken from the manpage
-      example = literalExample ''
+      example = literalExpression ''
        {
          screencast = {
            output_name = "HDMI-A-1";
--- a/nixos/modules/hardware/ckb-next.nix
+++ b/nixos/modules/hardware/ckb-next.nix
@ -27,7 +27,7 @@ in
      package = mkOption {
        type = types.package;
        default = pkgs.ckb-next;
-        defaultText = "pkgs.ckb-next";
+        defaultText = literalExpression "pkgs.ckb-next";
        description = ''
          The package implementing the Corsair keyboard/mouse driver.
        '';
--- a/nixos/modules/hardware/device-tree.nix
+++ b/nixos/modules/hardware/device-tree.nix
@ -21,7 +21,7 @@ let
          each .dtb file matching "compatible" of the overlay.
        '';
        default = null;
-        example = literalExample "./dts/overlays.dts";
+        example = literalExpression "./dts/overlays.dts";
      };

      dtsText = mkOption {
@ -31,7 +31,7 @@ let
          Literal DTS contents, overlay is applied to
          each .dtb file matching "compatible" of the overlay.
        '';
-        example = literalExample ''
+        example = ''
          /dts-v1/;
          /plugin/;
          / {
@ -125,8 +125,8 @@ in

        kernelPackage = mkOption {
          default = config.boot.kernelPackages.kernel;
-          defaultText = "config.boot.kernelPackages.kernel";
-          example = literalExample "pkgs.linux_latest";
+          defaultText = literalExpression "config.boot.kernelPackages.kernel";
+          example = literalExpression "pkgs.linux_latest";
          type = types.path;
          description = ''
            Kernel package containing the base device-tree (.dtb) to boot. Uses
@ -156,7 +156,7 @@ in

        overlays = mkOption {
          default = [];
-          example = literalExample ''
+          example = literalExpression ''
            [
              { name = "pps"; dtsFile = ./dts/pps.dts; }
              { name = "spi";
--- a/nixos/modules/hardware/digitalbitbox.nix
+++ b/nixos/modules/hardware/digitalbitbox.nix
@ -19,7 +19,7 @@ in
    package = mkOption {
      type = types.package;
      default = pkgs.digitalbitbox;
-      defaultText = "pkgs.digitalbitbox";
+      defaultText = literalExpression "pkgs.digitalbitbox";
      description = "The Digital Bitbox package to use. This can be used to install a package with udev rules that differ from the defaults.";
    };
  };
--- a/nixos/modules/hardware/opengl.nix
+++ b/nixos/modules/hardware/opengl.nix
@ -89,7 +89,7 @@ in
      extraPackages = mkOption {
        type = types.listOf types.package;
        default = [];
-        example = literalExample "with pkgs; [ vaapiIntel libvdpau-va-gl vaapiVdpau intel-ocl ]";
+        example = literalExpression "with pkgs; [ vaapiIntel libvdpau-va-gl vaapiVdpau intel-ocl ]";
        description = ''
          Additional packages to add to OpenGL drivers. This can be used
          to add OpenCL drivers, VA-API/VDPAU drivers etc.
@ -99,7 +99,7 @@ in
      extraPackages32 = mkOption {
        type = types.listOf types.package;
        default = [];
-        example = literalExample "with pkgs.pkgsi686Linux; [ vaapiIntel libvdpau-va-gl vaapiVdpau ]";
+        example = literalExpression "with pkgs.pkgsi686Linux; [ vaapiIntel libvdpau-va-gl vaapiVdpau ]";
        description = ''
          Additional packages to add to 32-bit OpenGL drivers on
          64-bit systems. Used when <option>driSupport32Bit</option> is
--- a/nixos/modules/hardware/opentabletdriver.nix
+++ b/nixos/modules/hardware/opentabletdriver.nix
@ -29,7 +29,7 @@ in
      package = mkOption {
        type = types.package;
        default = pkgs.opentabletdriver;
-        defaultText = "pkgs.opentabletdriver";
+        defaultText = literalExpression "pkgs.opentabletdriver";
        description = ''
          OpenTabletDriver derivation to use.
        '';
--- a/nixos/modules/hardware/printers.nix
+++ b/nixos/modules/hardware/printers.nix
@ -72,10 +72,10 @@ in {
            };
            deviceUri = mkOption {
              type = types.str;
-              example = [
+              example = literalExpression ''
                "ipp://printserver.local/printers/BrotherHL_Workroom"
                "usb://HP/DESKJET%20940C?serial=CN16E6C364BH"
-              ];
+              '';
              description = ''
                How to reach the printer.
                <command>lpinfo -v</command> shows a list of supported device URIs and schemes.
@ -83,8 +83,8 @@ in {
            };
            model = mkOption {
              type = types.str;
-              example = literalExample ''
-                gutenprint.''${lib.versions.majorMinor (lib.getVersion pkgs.gutenprint)}://brother-hl-5140/expert
+              example = literalExpression ''
+                "gutenprint.''${lib.versions.majorMinor (lib.getVersion pkgs.gutenprint)}://brother-hl-5140/expert"
              '';
              description = ''
                Location of the ppd driver file for the printer.
--- a/nixos/modules/hardware/sata.nix
+++ b/nixos/modules/hardware/sata.nix
@ -39,7 +39,7 @@ in
    enable = mkEnableOption "SATA drive timeouts";

    deciSeconds = mkOption {
-      example = "70";
+      example = 70;
      type = types.int;
      description = ''
        Set SCT Error Recovery Control timeout in deciseconds for use in RAID configurations.
--- a/nixos/modules/hardware/video/nvidia.nix
+++ b/nixos/modules/hardware/video/nvidia.nix
@ -165,11 +165,11 @@ in
    hardware.nvidia.package = lib.mkOption {
      type = lib.types.package;
      default = config.boot.kernelPackages.nvidiaPackages.stable;
-      defaultText = "config.boot.kernelPackages.nvidiaPackages.stable";
+      defaultText = literalExpression "config.boot.kernelPackages.nvidiaPackages.stable";
      description = ''
        The NVIDIA X11 derivation to use.
      '';
-      example = "config.boot.kernelPackages.nvidiaPackages.legacy_340";
+      example = literalExpression "config.boot.kernelPackages.nvidiaPackages.legacy_340";
    };
  };

--- a/nixos/modules/hardware/video/uvcvideo/default.nix
+++ b/nixos/modules/hardware/video/uvcvideo/default.nix
@ -33,7 +33,7 @@ in

      packages = mkOption {
        type = types.listOf types.path;
-        example = literalExample "[ pkgs.tiscamera ]";
+        example = literalExpression "[ pkgs.tiscamera ]";
        description = ''
          List of packages containing <command>uvcvideo</command> dynamic controls
          rules. All files found in
--- a/nixos/modules/i18n/input-method/fcitx.nix
+++ b/nixos/modules/i18n/input-method/fcitx.nix
@ -17,7 +17,7 @@ in
      engines = mkOption {
        type    = with types; listOf fcitxEngine;
        default = [];
-        example = literalExample "with pkgs.fcitx-engines; [ mozc hangul ]";
+        example = literalExpression "with pkgs.fcitx-engines; [ mozc hangul ]";
        description =
          let
            enginesDrv = filterAttrs (const isDerivation) pkgs.fcitx-engines;
--- a/nixos/modules/i18n/input-method/fcitx5.nix
+++ b/nixos/modules/i18n/input-method/fcitx5.nix
@ -12,7 +12,7 @@ in {
      addons = mkOption {
        type = with types; listOf package;
        default = [];
-        example = with pkgs; [ fcitx5-rime ];
+        example = literalExpression "with pkgs; [ fcitx5-rime ]";
        description = ''
          Enabled Fcitx5 addons.
        '';
--- a/nixos/modules/i18n/input-method/ibus.nix
+++ b/nixos/modules/i18n/input-method/ibus.nix
@ -36,7 +36,7 @@ in
      engines = mkOption {
        type    = with types; listOf ibusEngine;
        default = [];
-        example = literalExample "with pkgs.ibus-engines; [ mozc hangul ]";
+        example = literalExpression "with pkgs.ibus-engines; [ mozc hangul ]";
        description =
          let
            enginesDrv = filterAttrs (const isDerivation) pkgs.ibus-engines;
@ -48,7 +48,7 @@ in
      panel = mkOption {
        type = with types; nullOr path;
        default = null;
-        example = literalExample "''${pkgs.plasma5Packages.plasma-desktop}/lib/libexec/kimpanel-ibus-panel";
+        example = literalExpression ''"''${pkgs.plasma5Packages.plasma-desktop}/lib/libexec/kimpanel-ibus-panel"'';
        description = "Replace the IBus panel with another panel.";
      };
    };
--- a/nixos/modules/i18n/input-method/kime.nix
+++ b/nixos/modules/i18n/input-method/kime.nix
@ -10,7 +10,7 @@ in
      config = mkOption {
        type = yamlFormat.type;
        default = { };
-        example = literalExample ''
+        example = literalExpression ''
          {
            daemon = {
              modules = ["Xim" "Indicator"];
--- a/nixos/modules/installer/cd-dvd/iso-image.nix
+++ b/nixos/modules/installer/cd-dvd/iso-image.nix
@ -528,7 +528,7 @@ in
    };

    isoImage.contents = mkOption {
-      example = literalExample ''
+      example = literalExpression ''
        [ { source = pkgs.memtest86 + "/memtest.bin";
            target = "boot/memtest.bin";
          }
@ -541,7 +541,7 @@ in
    };

    isoImage.storeContents = mkOption {
-      example = literalExample "[ pkgs.stdenv ]";
+      example = literalExpression "[ pkgs.stdenv ]";
      description = ''
        This option lists additional derivations to be included in the
        Nix store in the generated ISO image.
--- a/nixos/modules/installer/cd-dvd/system-tarball.nix
+++ b/nixos/modules/installer/cd-dvd/system-tarball.nix
@ -15,7 +15,7 @@ in
 {
  options = {
    tarball.contents = mkOption {
-      example = literalExample ''
+      example = literalExpression ''
        [ { source = pkgs.memtest86 + "/memtest.bin";
            target = "boot/memtest.bin";
          }
@ -28,7 +28,7 @@ in
    };

    tarball.storeContents = mkOption {
-      example = literalExample "[ pkgs.stdenv ]";
+      example = literalExpression "[ pkgs.stdenv ]";
      description = ''
        This option lists additional derivations to be included in the
        Nix store in the generated ISO image.
--- a/nixos/modules/installer/netboot/netboot.nix
+++ b/nixos/modules/installer/netboot/netboot.nix
@ -9,7 +9,7 @@ with lib;
  options = {

    netboot.storeContents = mkOption {
-      example = literalExample "[ pkgs.stdenv ]";
+      example = literalExpression "[ pkgs.stdenv ]";
      description = ''
        This option lists additional derivations to be included in the
        Nix store in the generated netboot image.
--- a/nixos/modules/installer/sd-card/sd-image.nix
+++ b/nixos/modules/installer/sd-card/sd-image.nix
@ -49,7 +49,7 @@ in

    storePaths = mkOption {
      type = with types; listOf package;
-      example = literalExample "[ pkgs.stdenv ]";
+      example = literalExpression "[ pkgs.stdenv ]";
      description = ''
        Derivations to be included in the Nix store in the generated SD image.
      '';
@ -107,7 +107,7 @@ in
    };

    populateFirmwareCommands = mkOption {
-      example = literalExample "'' cp \${pkgs.myBootLoader}/u-boot.bin firmware/ ''";
+      example = literalExpression "'' cp \${pkgs.myBootLoader}/u-boot.bin firmware/ ''";
      description = ''
        Shell commands to populate the ./firmware directory.
        All files in that directory are copied to the
@ -116,7 +116,7 @@ in
    };

    populateRootCommands = mkOption {
-      example = literalExample "''\${config.boot.loader.generic-extlinux-compatible.populateCmd} -c \${config.system.build.toplevel} -d ./files/boot''";
+      example = literalExpression "''\${config.boot.loader.generic-extlinux-compatible.populateCmd} -c \${config.system.build.toplevel} -d ./files/boot''";
      description = ''
        Shell commands to populate the ./files directory.
        All files in that directory are copied to the
@ -126,7 +126,7 @@ in
    };

    postBuildCommands = mkOption {
-      example = literalExample "'' dd if=\${pkgs.myBootLoader}/SPL of=$img bs=1024 seek=1 conv=notrunc ''";
+      example = literalExpression "'' dd if=\${pkgs.myBootLoader}/SPL of=$img bs=1024 seek=1 conv=notrunc ''";
      default = "";
      description = ''
        Shell commands to run after the image is built.
--- a/nixos/modules/misc/documentation.nix
+++ b/nixos/modules/misc/documentation.nix
@ -133,7 +133,7 @@ in
          extraOutputsToInstall = ["man"];
          ignoreCollisions = true;
        };
-        defaultText = "all man pages in config.environment.systemPackages";
+        defaultText = literalDocBook "all man pages in <option>config.environment.systemPackages</option>";
        description = ''
          The manual pages to generate caches for if <option>generateCaches</option>
          is enabled. Must be a path to a directory with man pages under
@ -211,7 +211,7 @@ in
          Which extra NixOS module paths the generated NixOS's documentation should strip
          from options.
        '';
-        example = literalExample ''
+        example = literalExpression ''
          # e.g. with options from modules in ''${pkgs.customModules}/nix:
          [ pkgs.customModules ]
        '';
--- a/nixos/modules/misc/locate.nix
+++ b/nixos/modules/misc/locate.nix
@ -25,8 +25,8 @@ in {
    locate = mkOption {
      type = package;
      default = pkgs.findutils;
-      defaultText = "pkgs.findutils";
-      example = "pkgs.mlocate";
+      defaultText = literalExpression "pkgs.findutils";
+      example = literalExpression "pkgs.mlocate";
      description = ''
        The locate implementation to use
      '';
--- a/nixos/modules/misc/nixpkgs.nix
+++ b/nixos/modules/misc/nixpkgs.nix
@ -67,13 +67,13 @@ in
  options.nixpkgs = {

    pkgs = mkOption {
-      defaultText = literalExample
-        ''import "''${nixos}/.." {
-            inherit (cfg) config overlays localSystem crossSystem;
-          }
-        '';
+      defaultText = literalExpression ''
+        import "''${nixos}/.." {
+          inherit (cfg) config overlays localSystem crossSystem;
+        }
+      '';
      type = pkgsType;
-      example = literalExample "import <nixpkgs> {}";
+      example = literalExpression "import <nixpkgs> {}";
      description = ''
        If set, the pkgs argument to all NixOS modules is the value of
        this option, extended with <code>nixpkgs.overlays</code>, if
@ -109,7 +109,7 @@ in

    config = mkOption {
      default = {};
-      example = literalExample
+      example = literalExpression
        ''
          { allowBroken = true; allowUnfree = true; }
        '';
@ -125,7 +125,7 @@ in

    overlays = mkOption {
      default = [];
-      example = literalExample
+      example = literalExpression
        ''
          [
            (self: super: {
@ -158,7 +158,7 @@ in
      # Make sure that the final value has all fields for sake of other modules
      # referring to this. TODO make `lib.systems` itself use the module system.
      apply = lib.systems.elaborate;
-      defaultText = literalExample
+      defaultText = literalExpression
        ''(import "''${nixos}/../lib").lib.systems.examples.aarch64-multiplatform'';
      description = ''
        Specifies the platform on which NixOS should be built. When
--- a/nixos/modules/programs/atop.nix
+++ b/nixos/modules/programs/atop.nix
@ -19,7 +19,7 @@ in
      package = mkOption {
        type = types.package;
        default = pkgs.atop;
-        defaultText = "pkgs.atop";
+        defaultText = literalExpression "pkgs.atop";
        description = ''
          Which package to use for Atop.
        '';
@ -37,7 +37,7 @@ in
        package = mkOption {
          type = types.package;
          default = config.boot.kernelPackages.netatop;
-          defaultText = "config.boot.kernelPackages.netatop";
+          defaultText = literalExpression "config.boot.kernelPackages.netatop";
          description = ''
            Which package to use for netatop.
          '';
--- a/nixos/modules/programs/captive-browser.nix
+++ b/nixos/modules/programs/captive-browser.nix
@ -14,7 +14,7 @@ in
      package = mkOption {
        type = types.package;
        default = pkgs.captive-browser;
-        defaultText = "pkgs.captive-browser";
+        defaultText = literalExpression "pkgs.captive-browser";
        description = "Which package to use for captive-browser";
      };

--- a/nixos/modules/programs/chromium.nix
+++ b/nixos/modules/programs/chromium.nix
@ -33,7 +33,7 @@ in
          for additional details.
        '';
        default = [];
-        example = literalExample ''
+        example = literalExpression ''
          [
            "chlffgpmiacpedhhbkiomidkjlcfhogd" # pushbullet
            "mbniclmhobmnbdlbpiphghaielnnpgdp" # lightshot
@ -75,7 +75,7 @@ in
          Make sure the selected policy is supported on Linux and your browser version.
        '';
        default = {};
-        example = literalExample ''
+        example = literalExpression ''
          {
            "BrowserSignin" = 0;
            "SyncDisabled" = true;
--- a/nixos/modules/programs/digitalbitbox/default.nix
+++ b/nixos/modules/programs/digitalbitbox/default.nix
@ -19,7 +19,7 @@ in
    package = mkOption {
      type = types.package;
      default = pkgs.digitalbitbox;
-      defaultText = "pkgs.digitalbitbox";
+      defaultText = literalExpression "pkgs.digitalbitbox";
      description = "The Digital Bitbox package to use. This can be used to install a package with udev rules that differ from the defaults.";
    };
  };
--- a/nixos/modules/programs/dmrconfig.nix
+++ b/nixos/modules/programs/dmrconfig.nix
@ -24,7 +24,7 @@ in {
      package = mkOption {
        default = pkgs.dmrconfig;
        type = types.package;
-        defaultText = "pkgs.dmrconfig";
+        defaultText = literalExpression "pkgs.dmrconfig";
        description = "dmrconfig derivation to use";
      };
    };
--- a/nixos/modules/programs/feedbackd.nix
+++ b/nixos/modules/programs/feedbackd.nix
@ -18,6 +18,7 @@ in {
        '';
        type = types.package;
        default = pkgs.feedbackd;
+        defaultText = literalExpression "pkgs.feedbackd";
      };
    };
  };
--- a/nixos/modules/programs/firejail.nix
+++ b/nixos/modules/programs/firejail.nix
@ -40,13 +40,13 @@ in {
          executable = mkOption {
            type = types.path;
            description = "Executable to run sandboxed";
-            example = literalExample "''${lib.getBin pkgs.firefox}/bin/firefox";
+            example = literalExpression ''"''${lib.getBin pkgs.firefox}/bin/firefox"'';
          };
          profile = mkOption {
            type = types.nullOr types.path;
            default = null;
            description = "Profile to use";
-            example = literalExample "''${pkgs.firejail}/etc/firejail/firefox.profile";
+            example = literalExpression ''"''${pkgs.firejail}/etc/firejail/firefox.profile"'';
          };
          extraArgs = mkOption {
            type = types.listOf types.str;
@ -57,7 +57,7 @@ in {
        };
      }));
      default = {};
-      example = literalExample ''
+      example = literalExpression ''
        {
          firefox = {
            executable = "''${lib.getBin pkgs.firefox}/bin/firefox";
--- a/nixos/modules/programs/flexoptix-app.nix
+++ b/nixos/modules/programs/flexoptix-app.nix
@ -13,7 +13,7 @@ in {
        description = "FLEXOPTIX app package to use";
        type = types.package;
        default = pkgs.flexoptix-app;
-        defaultText = "\${pkgs.flexoptix-app}";
+        defaultText = literalExpression "pkgs.flexoptix-app";
      };
    };
  };
--- a/nixos/modules/programs/freetds.nix
+++ b/nixos/modules/programs/freetds.nix
@ -17,7 +17,7 @@ in
    environment.freetds = mkOption {
      type = types.attrsOf types.str;
      default = {};
-      example = literalExample ''
+      example = literalExpression ''
        { MYDATABASE = '''
            host = 10.0.2.100
            port = 1433
--- a/nixos/modules/programs/gamemode.nix
+++ b/nixos/modules/programs/gamemode.nix
@ -23,7 +23,7 @@ in
          System-wide configuration for GameMode (/etc/gamemode.ini).
          See gamemoded(8) man page for available settings.
        '';
-        example = literalExample ''
+        example = literalExpression ''
          {
            general = {
              renice = 10;
--- a/nixos/modules/programs/git.nix
+++ b/nixos/modules/programs/git.nix
@ -14,8 +14,8 @@ in
      package = mkOption {
        type = types.package;
        default = pkgs.git;
-        defaultText = "pkgs.git";
-        example = literalExample "pkgs.gitFull";
+        defaultText = literalExpression "pkgs.git";
+        example = literalExpression "pkgs.gitFull";
        description = "The git package to use";
      };

--- a/nixos/modules/programs/gnupg.nix
+++ b/nixos/modules/programs/gnupg.nix
@ -27,7 +27,7 @@ in
    package = mkOption {
      type = types.package;
      default = pkgs.gnupg;
-      defaultText = "pkgs.gnupg";
+      defaultText = literalExpression "pkgs.gnupg";
      description = ''
        The gpg package that should be used.
      '';
--- a/nixos/modules/programs/java.nix
+++ b/nixos/modules/programs/java.nix
@ -34,7 +34,7 @@ in

      package = mkOption {
        default = pkgs.jdk;
-        defaultText = "pkgs.jdk";
+        defaultText = literalExpression "pkgs.jdk";
        description = ''
          Java package to install. Typical values are pkgs.jdk or pkgs.jre.
        '';
--- a/nixos/modules/programs/kdeconnect.nix
+++ b/nixos/modules/programs/kdeconnect.nix
@ -13,9 +13,9 @@ with lib;
    '';
    package = mkOption {
      default = pkgs.kdeconnect;
-      defaultText = "pkgs.kdeconnect";
+      defaultText = literalExpression "pkgs.kdeconnect";
      type = types.package;
-      example = literalExample "pkgs.gnomeExtensions.gsconnect";
+      example = literalExpression "pkgs.gnomeExtensions.gsconnect";
      description = ''
        The package providing the implementation for kdeconnect.
      '';
--- a/nixos/modules/programs/less.nix
+++ b/nixos/modules/programs/less.nix
@ -40,7 +40,7 @@ in
      configFile = mkOption {
        type = types.nullOr types.path;
        default = null;
-        example = literalExample "\${pkgs.my-configs}/lesskey";
+        example = literalExpression ''"''${pkgs.my-configs}/lesskey"'';
        description = ''
          Path to lesskey configuration file.

@ -91,6 +91,7 @@ in
      lessopen = mkOption {
        type = types.nullOr types.str;
        default = "|${pkgs.lesspipe}/bin/lesspipe.sh %s";
+        defaultText = literalExpression ''"|''${pkgs.lesspipe}/bin/lesspipe.sh %s"'';
        description = ''
          Before less opens a file, it first gives your input preprocessor a chance to modify the way the contents of the file are displayed.
        '';
--- a/nixos/modules/programs/mtr.nix
+++ b/nixos/modules/programs/mtr.nix
@ -20,6 +20,7 @@ in {
      package = mkOption {
        type = types.package;
        default = pkgs.mtr;
+        defaultText = literalExpression "pkgs.mtr";
        description = ''
          The package to use.
        '';
--- a/nixos/modules/programs/neovim.nix
+++ b/nixos/modules/programs/neovim.nix
@ -47,18 +47,18 @@ in {
    configure = mkOption {
      type = types.attrs;
      default = {};
-      example = literalExample ''
-        configure = {
-            customRC = $''''
+      example = literalExpression ''
+        {
+          customRC = '''
            " here your custom configuration goes!
-            $'''';
-            packages.myVimPackage = with pkgs.vimPlugins; {
-              # loaded on launch
-              start = [ fugitive ];
-              # manually loadable by calling `:packadd $plugin-name`
-              opt = [ ];
-            };
+          ''';
+          packages.myVimPackage = with pkgs.vimPlugins; {
+            # loaded on launch
+            start = [ fugitive ];
+            # manually loadable by calling `:packadd $plugin-name`
+            opt = [ ];
          };
+        }
      '';
      description = ''
        Generate your init file from your list of plugins and custom commands.
@ -69,7 +69,7 @@ in {
    package = mkOption {
      type = types.package;
      default = pkgs.neovim-unwrapped;
-      defaultText = literalExample "pkgs.neovim-unwrapped";
+      defaultText = literalExpression "pkgs.neovim-unwrapped";
      description = "The package to use for the neovim binary.";
    };

@ -82,8 +82,8 @@ in {

    runtime = mkOption {
      default = {};
-      example = literalExample ''
-        runtime."ftplugin/c.vim".text = "setlocal omnifunc=v:lua.vim.lsp.omnifunc";
+      example = literalExpression ''
+        { "ftplugin/c.vim".text = "setlocal omnifunc=v:lua.vim.lsp.omnifunc"; }
      '';
      description = ''
        Set of files that have to be linked in <filename>runtime</filename>.
--- a/nixos/modules/programs/noisetorch.nix
+++ b/nixos/modules/programs/noisetorch.nix
@ -10,6 +10,7 @@ in {
    package = mkOption {
      type = types.package;
      default = pkgs.noisetorch;
+      defaultText = literalExpression "pkgs.noisetorch";
      description = ''
        The noisetorch package to use.
      '';
--- a/nixos/modules/programs/npm.nix
+++ b/nixos/modules/programs/npm.nix
@ -14,10 +14,11 @@ in
      enable = mkEnableOption "<command>npm</command> global config";

      package = mkOption {
-        type = types.path;
+        type = types.package;
        description = "The npm package version / flavor to use";
        default = pkgs.nodePackages.npm;
-        example = literalExample "pkgs.nodePackages_13_x.npm";
+        defaultText = literalExpression "pkgs.nodePackages.npm";
+        example = literalExpression "pkgs.nodePackages_13_x.npm";
      };

      npmrc = mkOption {
--- a/nixos/modules/programs/proxychains.nix
+++ b/nixos/modules/programs/proxychains.nix
@ -120,7 +120,7 @@ in {
          Proxies to be used by proxychains.
        '';

-        example = literalExample ''
+        example = literalExpression ''
          { myproxy =
            { type = "socks4";
              host = "127.0.0.1";
--- a/nixos/modules/programs/shadow.nix
+++ b/nixos/modules/programs/shadow.nix
@ -66,7 +66,7 @@ in
        This must not be a store path, since the path is
        used outside the store (in particular in /etc/passwd).
      '';
-      example = literalExample "pkgs.zsh";
+      example = literalExpression "pkgs.zsh";
      type = types.either types.path types.shellPackage;
    };

--- a/nixos/modules/programs/spacefm.nix
+++ b/nixos/modules/programs/spacefm.nix
@ -29,11 +29,13 @@ in
          terminal_su = "${pkgs.sudo}/bin/sudo";
          graphical_su = "${pkgs.gksu}/bin/gksu";
        };
-        example = literalExample ''{
-          tmp_dir = "/tmp";
-          terminal_su = "''${pkgs.sudo}/bin/sudo";
-          graphical_su = "''${pkgs.gksu}/bin/gksu";
-        }'';
+        defaultText = literalExpression ''
+          {
+            tmp_dir = "/tmp";
+            terminal_su = "''${pkgs.sudo}/bin/sudo";
+            graphical_su = "''${pkgs.gksu}/bin/gksu";
+          }
+        '';
        description = ''
          The system-wide spacefm configuration.
          Parameters to be written to <filename>/etc/spacefm/spacefm.conf</filename>.
--- a/nixos/modules/programs/ssh.nix
+++ b/nixos/modules/programs/ssh.nix
@ -36,6 +36,7 @@ in
      askPassword = mkOption {
        type = types.str;
        default = "${pkgs.x11_ssh_askpass}/libexec/x11-ssh-askpass";
+        defaultText = literalExpression ''"''${pkgs.x11_ssh_askpass}/libexec/x11-ssh-askpass"'';
        description = "Program used by SSH to ask for passwords.";
      };

@ -113,7 +114,7 @@ in
      agentPKCS11Whitelist = mkOption {
        type = types.nullOr types.str;
        default = null;
-        example = "\${pkgs.opensc}/lib/opensc-pkcs11.so";
+        example = literalExpression ''"''${pkgs.opensc}/lib/opensc-pkcs11.so"'';
        description = ''
          A pattern-list of acceptable paths for PKCS#11 shared libraries
          that may be used with the -s option to ssh-add.
@ -123,7 +124,7 @@ in
      package = mkOption {
        type = types.package;
        default = pkgs.openssh;
-        defaultText = "pkgs.openssh";
+        defaultText = literalExpression "pkgs.openssh";
        description = ''
          The package used for the openssh client and daemon.
        '';
@ -180,7 +181,7 @@ in
        description = ''
          The set of system-wide known SSH hosts.
        '';
-        example = literalExample ''
+        example = literalExpression ''
          {
            myhost = {
              hostNames = [ "myhost" "myhost.mydomain.com" "10.10.1.4" ];
--- a/nixos/modules/programs/ssmtp.nix
+++ b/nixos/modules/programs/ssmtp.nix
@ -54,7 +54,7 @@ in
          <citerefentry><refentrytitle>ssmtp</refentrytitle><manvolnum>5</manvolnum></citerefentry> configuration. Refer
          to <link xlink:href="https://linux.die.net/man/5/ssmtp.conf"/> for details on supported values.
        '';
-        example = literalExample ''
+        example = literalExpression ''
          {
            Debug = true;
            FromLineOverride = false;
--- a/nixos/modules/programs/sway.nix
+++ b/nixos/modules/programs/sway.nix
@ -92,10 +92,10 @@ in {
      default = with pkgs; [
        swaylock swayidle alacritty dmenu
      ];
-      defaultText = literalExample ''
+      defaultText = literalExpression ''
        with pkgs; [ swaylock swayidle alacritty dmenu ];
      '';
-      example = literalExample ''
+      example = literalExpression ''
        with pkgs; [
          i3status i3status-rust
          termite rofi light
--- a/nixos/modules/programs/tsm-client.nix
+++ b/nixos/modules/programs/tsm-client.nix
@ -5,7 +5,7 @@ let
  inherit (builtins) length map;
  inherit (lib.attrsets) attrNames filterAttrs hasAttr mapAttrs mapAttrsToList optionalAttrs;
  inherit (lib.modules) mkDefault mkIf;
-  inherit (lib.options) literalExample mkEnableOption mkOption;
+  inherit (lib.options) literalExpression mkEnableOption mkOption;
  inherit (lib.strings) concatStringsSep optionalString toLower;
  inherit (lib.types) addCheck attrsOf lines nullOr package path port str strMatching submodule;

@ -123,7 +123,7 @@ let
    };
    options.text = mkOption {
      type = lines;
-      example = literalExample
+      example = literalExpression
        ''lib.modules.mkAfter "compression no"'';
      description = ''
        Additional text lines for the server stanza.
@ -218,8 +218,8 @@ let
    package = mkOption {
      type = package;
      default = pkgs.tsm-client;
-      defaultText = "pkgs.tsm-client";
-      example = literalExample "pkgs.tsm-client-withGui";
+      defaultText = literalExpression "pkgs.tsm-client";
+      example = literalExpression "pkgs.tsm-client-withGui";
      description = ''
        The TSM client derivation to be
        added to the system environment.
--- a/nixos/modules/programs/vim.nix
+++ b/nixos/modules/programs/vim.nix
@ -18,8 +18,8 @@ in {
    package = mkOption {
      type = types.package;
      default = pkgs.vim;
-      defaultText = "pkgs.vim";
-      example = "pkgs.vimHugeX";
+      defaultText = literalExpression "pkgs.vim";
+      example = literalExpression "pkgs.vimHugeX";
      description = ''
        vim package to use.
      '';
--- a/nixos/modules/programs/wireshark.nix
+++ b/nixos/modules/programs/wireshark.nix
@ -19,7 +19,7 @@ in {
      package = mkOption {
        type = types.package;
        default = pkgs.wireshark-cli;
-        defaultText = "pkgs.wireshark-cli";
+        defaultText = literalExpression "pkgs.wireshark-cli";
        description = ''
          Which Wireshark package to install in the global environment.
        '';
--- a/nixos/modules/programs/xonsh.nix
+++ b/nixos/modules/programs/xonsh.nix
@ -27,7 +27,8 @@ in
      package = mkOption {
        type = types.package;
        default = pkgs.xonsh;
-        example = literalExample "pkgs.xonsh.override { configFile = \"/path/to/xonshrc\"; }";
+        defaultText = literalExpression "pkgs.xonsh";
+        example = literalExpression "pkgs.xonsh.override { configFile = \"/path/to/xonshrc\"; }";
        description = ''
          xonsh package to use.
        '';
--- a/nixos/modules/programs/xss-lock.nix
+++ b/nixos/modules/programs/xss-lock.nix
@ -11,7 +11,8 @@ in

    lockerCommand = mkOption {
      default = "${pkgs.i3lock}/bin/i3lock";
-      example = literalExample "\${pkgs.i3lock-fancy}/bin/i3lock-fancy";
+      defaultText = literalExpression ''"''${pkgs.i3lock}/bin/i3lock"'';
+      example = literalExpression ''"''${pkgs.i3lock-fancy}/bin/i3lock-fancy"'';
      type = types.separatedString " ";
      description = "Locker to be used with xsslock";
    };
--- a/nixos/modules/programs/xwayland.nix
+++ b/nixos/modules/programs/xwayland.nix
@ -16,9 +16,8 @@ in
      type = types.str;
      default = optionalString config.fonts.fontDir.enable
        "/run/current-system/sw/share/X11/fonts";
-      defaultText = literalExample ''
-        optionalString config.fonts.fontDir.enable
-          "/run/current-system/sw/share/X11/fonts";
+      defaultText = literalExpression ''
+        optionalString config.fonts.fontDir.enable "/run/current-system/sw/share/X11/fonts"
      '';
      description = ''
        Default font path. Setting this option causes Xwayland to be rebuilt.
@ -30,10 +29,10 @@ in
      default = pkgs.xwayland.override (oldArgs: {
        inherit (cfg) defaultFontPath;
      });
-      defaultText = literalExample ''
+      defaultText = literalExpression ''
        pkgs.xwayland.override (oldArgs: {
          inherit (config.programs.xwayland) defaultFontPath;
-        });
+        })
      '';
      description = "The Xwayland package to use.";
    };
--- a/nixos/modules/programs/yabar.nix
+++ b/nixos/modules/programs/yabar.nix
@ -45,7 +45,8 @@ in

      package = mkOption {
        default = pkgs.yabar-unstable;
-        example = literalExample "pkgs.yabar";
+        defaultText = literalExpression "pkgs.yabar-unstable";
+        example = literalExpression "pkgs.yabar";
        type = types.package;

        # `yabar-stable` segfaults under certain conditions.
--- a/nixos/modules/programs/zsh/oh-my-zsh.nix
+++ b/nixos/modules/programs/zsh/oh-my-zsh.nix
@ -48,7 +48,7 @@ in

        package = mkOption {
          default = pkgs.oh-my-zsh;
-          defaultText = "pkgs.oh-my-zsh";
+          defaultText = literalExpression "pkgs.oh-my-zsh";
          description = ''
            Package to install for `oh-my-zsh` usage.
          '';
--- a/nixos/modules/programs/zsh/zsh-autoenv.nix
+++ b/nixos/modules/programs/zsh/zsh-autoenv.nix
@ -10,7 +10,7 @@ in {
      enable = mkEnableOption "zsh-autoenv";
      package = mkOption {
        default = pkgs.zsh-autoenv;
-        defaultText = "pkgs.zsh-autoenv";
+        defaultText = literalExpression "pkgs.zsh-autoenv";
        description = ''
          Package to install for `zsh-autoenv` usage.
        '';
--- a/nixos/modules/programs/zsh/zsh-autosuggestions.nix
+++ b/nixos/modules/programs/zsh/zsh-autosuggestions.nix
@ -40,7 +40,7 @@ in
      type = with types; attrsOf str;
      default = {};
      description = "Attribute set with additional configuration values";
-      example = literalExample ''
+      example = literalExpression ''
        {
          "ZSH_AUTOSUGGEST_BUFFER_MAX_SIZE" = "20";
        }
--- a/nixos/modules/programs/zsh/zsh-syntax-highlighting.nix
+++ b/nixos/modules/programs/zsh/zsh-syntax-highlighting.nix
@ -42,7 +42,7 @@ in
        default = {};
        type = types.attrsOf types.str;

-        example = literalExample ''
+        example = literalExpression ''
          {
            "rm -rf *" = "fg=white,bold,bg=red";
          }
@ -59,7 +59,7 @@ in
        default = {};
        type = types.attrsOf types.str;

-        example = literalExample ''
+        example = literalExpression ''
          {
            "alias" = "fg=magenta,bold";
          }
--- a/nixos/modules/security/acme.nix
+++ b/nixos/modules/security/acme.nix
@ -486,7 +486,7 @@ let
      extraDomainNames = mkOption {
        type = types.listOf types.str;
        default = [];
-        example = literalExample ''
+        example = literalExpression ''
          [
            "example.org"
            "mydomain.org"
@ -656,7 +656,7 @@ in {
          to those units if they rely on the certificates being present,
          or trigger restarts of the service if certificates get renewed.
        '';
-        example = literalExample ''
+        example = literalExpression ''
          {
            "example.com" = {
              webroot = "/var/lib/acme/acme-challenge/";
--- a/nixos/modules/security/ca.nix
+++ b/nixos/modules/security/ca.nix
@ -24,7 +24,7 @@ in
    security.pki.certificateFiles = mkOption {
      type = types.listOf types.path;
      default = [];
-      example = literalExample "[ \"\${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt\" ]";
+      example = literalExpression ''[ "''${pkgs.cacert}/etc/ssl/certs/ca-bundle.crt" ]'';
      description = ''
        A list of files containing trusted root certificates in PEM
        format. These are concatenated to form
@ -37,7 +37,7 @@ in
    security.pki.certificates = mkOption {
      type = types.listOf types.str;
      default = [];
-      example = literalExample ''
+      example = literalExpression ''
        [ '''
            NixOS.org
            =========
--- a/nixos/modules/security/dhparams.nix
+++ b/nixos/modules/security/dhparams.nix
@ -53,7 +53,7 @@ in {
          coerce = bits: { inherit bits; };
        in attrsOf (coercedTo int coerce (submodule paramsSubmodule));
        default = {};
-        example = lib.literalExample "{ nginx.bits = 3072; }";
+        example = lib.literalExpression "{ nginx.bits = 3072; }";
        description = ''
          Diffie-Hellman parameters to generate.

--- a/nixos/modules/security/doas.nix
+++ b/nixos/modules/security/doas.nix
@ -77,7 +77,7 @@ in
        You can use <code>mkBefore</code> and/or <code>mkAfter</code> to ensure
        this is the case when configuration options are merged.
      '';
-      example = literalExample ''
+      example = literalExpression ''
        [
          # Allow execution of any command by any user in group doas, requiring
          # a password and keeping any previously-defined environment variables.
--- a/nixos/modules/security/pam.nix
+++ b/nixos/modules/security/pam.nix
@ -586,7 +586,7 @@ in
    };

    security.pam.services = mkOption {
-      default = [];
+      default = {};
      type = with types; attrsOf (submodule pamOpts);
      description =
        ''
--- a/nixos/modules/security/pam_mount.nix
+++ b/nixos/modules/security/pam_mount.nix
@ -33,7 +33,7 @@ in
      additionalSearchPaths = mkOption {
        type = types.listOf types.package;
        default = [];
-        example = literalExample "[ pkgs.bindfs ]";
+        example = literalExpression "[ pkgs.bindfs ]";
        description = ''
          Additional programs to include in the search path of pam_mount.
          Useful for example if you want to use some FUSE filesystems like bindfs.
@ -43,7 +43,7 @@ in
      fuseMountOptions = mkOption {
        type = types.listOf types.str;
        default = [];
-        example = literalExample ''
+        example = literalExpression ''
          [ "nodev" "nosuid" "force-user=%(USER)" "gid=%(USERGID)" "perms=0700" "chmod-deny" "chown-deny" "chgrp-deny" ]
        '';
        description = ''
--- a/nixos/modules/security/sudo.nix
+++ b/nixos/modules/security/sudo.nix
@ -45,7 +45,7 @@ in
    security.sudo.package = mkOption {
      type = types.package;
      default = pkgs.sudo;
-      defaultText = "pkgs.sudo";
+      defaultText = literalExpression "pkgs.sudo";
      description = ''
        Which package to use for `sudo`.
      '';
@ -91,7 +91,7 @@ in
        this is the case when configuration options are merged.
      '';
      default = [];
-      example = literalExample ''
+      example = literalExpression ''
        [
          # Allow execution of any command by all users in group sudo,
          # requiring a password.
--- a/nixos/modules/security/systemd-confinement.nix
+++ b/nixos/modules/security/systemd-confinement.nix
@ -62,8 +62,8 @@ in {
      options.confinement.binSh = lib.mkOption {
        type = types.nullOr types.path;
        default = toplevelConfig.environment.binsh;
-        defaultText = "config.environment.binsh";
-        example = lib.literalExample "\${pkgs.dash}/bin/dash";
+        defaultText = lib.literalExpression "config.environment.binsh";
+        example = lib.literalExpression ''"''${pkgs.dash}/bin/dash"'';
        description = ''
          The program to make available as <filename>/bin/sh</filename> inside
          the chroot. If this is set to <literal>null</literal>, no
--- a/nixos/modules/security/tpm2.nix
+++ b/nixos/modules/security/tpm2.nix
@ -26,8 +26,7 @@ in {
      '';
      type = lib.types.nullOr lib.types.str;
      default = if cfg.abrmd.enable then "tss" else "root";
-      defaultText = ''"tss" when using the userspace resource manager,'' +
-                    ''"root" otherwise'';
+      defaultText = lib.literalExpression ''if config.security.tpm2.abrmd.enable then "tss" else "root"'';
    };

    tssGroup = lib.mkOption {
@ -57,7 +56,7 @@ in {
        description = "tpm2-abrmd package to use";
        type = lib.types.package;
        default = pkgs.tpm2-abrmd;
-        defaultText = "pkgs.tpm2-abrmd";
+        defaultText = lib.literalExpression "pkgs.tpm2-abrmd";
      };
    };

@ -71,7 +70,7 @@ in {
        description = "tpm2-pkcs11 package to use";
        type = lib.types.package;
        default = pkgs.tpm2-pkcs11;
-        defaultText = "pkgs.tpm2-pkcs11";
+        defaultText = lib.literalExpression "pkgs.tpm2-pkcs11";
      };
    };

--- a/nixos/modules/security/wrappers/default.nix
+++ b/nixos/modules/security/wrappers/default.nix
@ -152,7 +152,7 @@ in
    security.wrappers = lib.mkOption {
      type = lib.types.attrsOf wrapperType;
      default = {};
-      example = lib.literalExample
+      example = lib.literalExpression
        ''
          {
            # a setuid root program
--- a/nixos/modules/services/admin/meshcentral.nix
+++ b/nixos/modules/services/admin/meshcentral.nix
@ -10,7 +10,7 @@ in with lib; {
      description = "MeshCentral package to use. Replacing this may be necessary to add dependencies for extra functionality.";
      type = types.package;
      default = pkgs.meshcentral;
-      defaultText = "pkgs.meshcentral";
+      defaultText = literalExpression "pkgs.meshcentral";
    };
    settings = mkOption {
      description = ''
--- a/nixos/modules/services/admin/oxidized.nix
+++ b/nixos/modules/services/admin/oxidized.nix
@ -33,7 +33,7 @@ in

    configFile = mkOption {
      type = types.path;
-      example = literalExample ''
+      example = literalExpression ''
        pkgs.writeText "oxidized-config.yml" '''
          ---
          debug: true
@ -69,7 +69,7 @@ in

    routerDB = mkOption {
      type = types.path;
-      example = literalExample ''
+      example = literalExpression ''
        pkgs.writeText "oxidized-router.db" '''
          hostname-sw1:powerconnect:username1:password2
          hostname-sw2:procurve:username2:password2
--- a/nixos/modules/services/amqp/activemq/default.nix
+++ b/nixos/modules/services/amqp/activemq/default.nix
@ -33,6 +33,7 @@ in {
      };
      configurationDir = mkOption {
        default = "${activemq}/conf";
+        defaultText = literalExpression ''"''${pkgs.activemq}/conf"'';
        type = types.str;
        description = ''
          The base directory for ActiveMQ's configuration.
@ -64,7 +65,7 @@ in {
      javaProperties = mkOption {
        type = types.attrs;
        default = { };
-        example = literalExample ''
+        example = literalExpression ''
          {
            "java.net.preferIPv4Stack" = "true";
          }
--- a/nixos/modules/services/amqp/rabbitmq.nix
+++ b/nixos/modules/services/amqp/rabbitmq.nix
@ -29,7 +29,7 @@ in
      package = mkOption {
        default = pkgs.rabbitmq-server;
        type = types.package;
-        defaultText = "pkgs.rabbitmq-server";
+        defaultText = literalExpression "pkgs.rabbitmq-server";
        description = ''
          Which rabbitmq package to use.
        '';
@ -82,7 +82,7 @@ in
      configItems = mkOption {
        default = { };
        type = types.attrsOf types.str;
-        example = literalExample ''
+        example = literalExpression ''
          {
            "auth_backends.1.authn" = "rabbit_auth_backend_ldap";
            "auth_backends.1.authz" = "rabbit_auth_backend_internal";
--- a/nixos/modules/services/audio/botamusique.nix
+++ b/nixos/modules/services/audio/botamusique.nix
@ -17,6 +17,7 @@ in
    package = mkOption {
      type = types.package;
      default = pkgs.botamusique;
+      defaultText = literalExpression "pkgs.botamusique";
      description = "The botamusique package to use.";
    };

--- a/nixos/modules/services/audio/jack.nix
+++ b/nixos/modules/services/audio/jack.nix
@ -25,8 +25,8 @@ in {
          internal = true;
          type = types.package;
          default = pkgs.jack2;
-          defaultText = "pkgs.jack2";
-          example = literalExample "pkgs.jack1";
+          defaultText = literalExpression "pkgs.jack2";
+          example = literalExpression "pkgs.jack1";
          description = ''
            The JACK package to use.
          '';
@ -37,7 +37,7 @@ in {
          default = [
            "-dalsa"
          ];
-          example = literalExample ''
+          example = literalExpression ''
            [ "-dalsa" "--device" "hw:1" ];
          '';
          description = ''
--- a/nixos/modules/services/audio/liquidsoap.nix
+++ b/nixos/modules/services/audio/liquidsoap.nix
@ -39,9 +39,9 @@ in
      default = {};

      example = {
-        myStream1 = literalExample "\"/etc/liquidsoap/myStream1.liq\"";
-        myStream2 = literalExample "./myStream2.liq";
-        myStream3 = literalExample "\"out(playlist(\\\"/srv/music/\\\"))\"";
+        myStream1 = "/etc/liquidsoap/myStream1.liq";
+        myStream2 = literalExpression "./myStream2.liq";
+        myStream3 = "out(playlist(\"/srv/music/\"))";
      };

      type = types.attrsOf (types.either types.path types.str);
--- a/nixos/modules/services/audio/mopidy.nix
+++ b/nixos/modules/services/audio/mopidy.nix
@ -39,7 +39,7 @@ in {
      extensionPackages = mkOption {
        default = [];
        type = types.listOf types.package;
-        example = literalExample "[ pkgs.mopidy-spotify ]";
+        example = literalExpression "[ pkgs.mopidy-spotify ]";
        description = ''
          Mopidy extensions that should be loaded by the service.
        '';
--- a/nixos/modules/services/audio/mpd.nix
+++ b/nixos/modules/services/audio/mpd.nix
@ -74,7 +74,7 @@ in {
      musicDirectory = mkOption {
        type = with types; either path (strMatching "(http|https|nfs|smb)://.+");
        default = "${cfg.dataDir}/music";
-        defaultText = "\${dataDir}/music";
+        defaultText = literalExpression ''"''${dataDir}/music"'';
        description = ''
          The directory or NFS/SMB network share where MPD reads music from. If left
          as the default value this directory will automatically be created before
@ -86,7 +86,7 @@ in {
      playlistDirectory = mkOption {
        type = types.path;
        default = "${cfg.dataDir}/playlists";
-        defaultText = "\${dataDir}/playlists";
+        defaultText = literalExpression ''"''${dataDir}/playlists"'';
        description = ''
          The directory where MPD stores playlists. If left as the default value
          this directory will automatically be created before the MPD server starts,
@ -155,7 +155,7 @@ in {
      dbFile = mkOption {
        type = types.nullOr types.str;
        default = "${cfg.dataDir}/tag_cache";
-        defaultText = "\${dataDir}/tag_cache";
+        defaultText = literalExpression ''"''${dataDir}/tag_cache"'';
        description = ''
          The path to MPD's database. If set to <literal>null</literal> the
          parameter is omitted from the configuration.
--- a/nixos/modules/services/audio/slimserver.nix
+++ b/nixos/modules/services/audio/slimserver.nix
@ -22,7 +22,7 @@ in {
      package = mkOption {
        type = types.package;
        default = pkgs.slimserver;
-        defaultText = "pkgs.slimserver";
+        defaultText = literalExpression "pkgs.slimserver";
        description = "Slimserver package to use.";
      };

--- a/nixos/modules/services/audio/snapserver.nix
+++ b/nixos/modules/services/audio/snapserver.nix
@ -206,7 +206,7 @@ in {
                For type <literal>meta</literal>, a list of stream names in the form <literal>/one/two/...</literal>. Don't forget the leading slash.
                For type <literal>alsa</literal>, use an empty string.
              '';
-              example = literalExample ''
+              example = literalExpression ''
                "/path/to/pipe"
                "/path/to/librespot"
                "192.168.1.2:4444"
@ -226,7 +226,7 @@ in {
              description = ''
                Key-value pairs that convey additional parameters about a stream.
              '';
-              example = literalExample ''
+              example = literalExpression ''
                # for type == "pipe":
                {
                  mode = "create";
@ -254,7 +254,7 @@ in {
        description = ''
          The definition for an input source.
        '';
-        example = literalExample ''
+        example = literalExpression ''
          {
            mpd = {
              type = "pipe";
--- a/nixos/modules/services/audio/ympd.nix
+++ b/nixos/modules/services/audio/ympd.nix
@ -26,7 +26,6 @@ in {
          type = types.str;
          default = "localhost";
          description = "The host where MPD is listening.";
-          example = "localhost";
        };

        port = mkOption {
--- a/nixos/modules/services/backup/automysqlbackup.nix
+++ b/nixos/modules/services/backup/automysqlbackup.nix
@ -2,7 +2,7 @@

 let

-  inherit (lib) concatMapStringsSep concatStringsSep isInt isList literalExample;
+  inherit (lib) concatMapStringsSep concatStringsSep isInt isList literalExpression;
  inherit (lib) mapAttrs mapAttrsToList mkDefault mkEnableOption mkIf mkOption optional types;

  cfg = config.services.automysqlbackup;
@ -48,7 +48,7 @@ in
          <filename>''${pkgs.automysqlbackup}/etc/automysqlbackup.conf</filename>
          for details on supported values.
        '';
-        example = literalExample ''
+        example = literalExpression ''
          {
            db_names = [ "nextcloud" "matomo" ];
            table_exclude = [ "nextcloud.oc_users" "nextcloud.oc_whats_new" ];
--- a/nixos/modules/services/backup/borgbackup.nix
+++ b/nixos/modules/services/backup/borgbackup.nix
@ -203,7 +203,7 @@ in {
      See also the chapter about BorgBackup in the NixOS manual.
    '';
    default = { };
-    example = literalExample ''
+    example = literalExpression ''
      { # for a local backup
        rootBackup = {
          paths = "/";
@ -260,7 +260,7 @@ in {
          archiveBaseName = mkOption {
            type = types.strMatching "[^/{}]+";
            default = "${globalConfig.networking.hostName}-${name}";
-            defaultText = "\${config.networking.hostName}-<name>";
+            defaultText = literalExpression ''"''${config.networking.hostName}-<name>"'';
            description = ''
              How to name the created archives. A timestamp, whose format is
              determined by <option>dateFormat</option>, will be appended. The full
@ -326,10 +326,7 @@ in {
              you to specify a <option>passCommand</option>
              or a <option>passphrase</option>.
            '';
-            example = ''
-              encryption.mode = "repokey-blake2" ;
-              encryption.passphrase = "mySecretPassphrase" ;
-            '';
+            example = "repokey-blake2";
          };

          encryption.passCommand = mkOption {
@ -437,7 +434,7 @@ in {
              for the available options.
            '';
            default = { };
-            example = literalExample ''
+            example = literalExpression ''
              {
                within = "1d"; # Keep all archives from the last day
                daily = 7;
@ -455,7 +452,7 @@ in {
              Use <literal>""</literal> to consider all archives.
            '';
            default = config.archiveBaseName;
-            defaultText = "\${archiveBaseName}";
+            defaultText = literalExpression "archiveBaseName";
          };

          environment = mkOption {
--- a/nixos/modules/services/backup/btrbk.nix
+++ b/nixos/modules/services/backup/btrbk.nix
@ -57,7 +57,7 @@ in
        description = "Extra packages for btrbk, like compression utilities for <literal>stream_compress</literal>";
        type = lib.types.listOf lib.types.package;
        default = [ ];
-        example = lib.literalExample "[ pkgs.xz ]";
+        example = lib.literalExpression "[ pkgs.xz ]";
      };
      niceness = lib.mkOption {
        description = "Niceness for local instances of btrbk. Also applies to remote ones connecting via ssh when positive.";
--- a/nixos/modules/services/backup/postgresql-backup.nix
+++ b/nixos/modules/services/backup/postgresql-backup.nix
@ -85,7 +85,7 @@ in {

      backupAll = mkOption {
        default = cfg.databases == [];
-        defaultText = "services.postgresqlBackup.databases == []";
+        defaultText = literalExpression "services.postgresqlBackup.databases == []";
        type = lib.types.bool;
        description = ''
          Backup all databases using pg_dumpall.
--- a/nixos/modules/services/backup/postgresql-wal-receiver.nix
+++ b/nixos/modules/services/backup/postgresql-wal-receiver.nix
@ -7,7 +7,7 @@ let
    options = {
      postgresqlPackage = mkOption {
        type = types.package;
-        example = literalExample "pkgs.postgresql_11";
+        example = literalExpression "pkgs.postgresql_11";
        description = ''
          PostgreSQL package to use.
        '';
@ -15,7 +15,7 @@ let

      directory = mkOption {
        type = types.path;
-        example = literalExample "/mnt/pg_wal/main/";
+        example = literalExpression "/mnt/pg_wal/main/";
        description = ''
          Directory to write the output to.
        '';
@ -88,7 +88,7 @@ let
      extraArgs = mkOption {
        type = with types; listOf str;
        default = [ ];
-        example = literalExample ''
+        example = literalExpression ''
          [
            "--no-sync"
          ]
@ -101,7 +101,7 @@ let
      environment = mkOption {
        type = with types; attrsOf str;
        default = { };
-        example = literalExample ''
+        example = literalExpression ''
          {
            PGPASSFILE = "/private/passfile";
            PGSSLMODE = "require";
@ -121,7 +121,7 @@ in {
      receivers = mkOption {
        type = with types; attrsOf (submodule receiverSubmodule);
        default = { };
-        example = literalExample ''
+        example = literalExpression ''
          {
            main = {
              postgresqlPackage = pkgs.postgresql_11;
--- a/nixos/modules/services/backup/restic-rest-server.nix
+++ b/nixos/modules/services/backup/restic-rest-server.nix
@ -59,7 +59,7 @@ in

    package = mkOption {
      default = pkgs.restic-rest-server;
-      defaultText = "pkgs.restic-rest-server";
+      defaultText = literalExpression "pkgs.restic-rest-server";
      type = types.package;
      description = "Restic REST server package to use.";
    };
--- a/nixos/modules/services/backup/syncoid.nix
+++ b/nixos/modules/services/backup/syncoid.nix
@ -286,7 +286,7 @@ in
        };
      }));
      default = { };
-      example = literalExample ''
+      example = literalExpression ''
        {
          "pool/test".target = "root@target:pool/test";
        }
--- a/Show More
+++ b/Show More