meson: flip the switch!!

This commit makes Meson the default buildsystem for Lix. The Make buildsystem is now deprecated and will be removed soon, but has not yet, which will be done in a later commit when all seems good. The mesonBuild jobs have been removed, and have not been replaced with equivalent jobs to ensure the Make buildsystem still works. The full, new commands in a development shell are: $ meson setup ./build "--prefix=$out" $mesonFlags (A simple `meson setup ./build` will also build, but will do a different thing, not having the settings from package.nix applied.) $ meson compile -C build $ meson test -C build --suite=check $ meson install -C build $ meson test -C build --suite=installcheck (Check and installcheck may both be done after install, allowing you to omit the --suite argument entirely, but this is the order package.nix runs them in.) If tests fail and Meson helpfully has no output for why, use the `--print-error-logs` option to `meson test`. Why this is not the default I cannot explain. If you change a setting in the buildsystem, most cases will automatically regenerate the Meson configuration, but some cases, like trying to build a specific target whose name is new to the buildsystem (e.g. `meson compile -C build src/libmelt/libmelt.dylib`, when `libmelt.dylib` did not exist as a target the last time the buildsystem was generated), then you can reconfigure using new settings but existing options, and only recompiling stuff affected by the changes: $ meson setup --reconfigure build Note that changes to the default values in `meson.options` or in the `default_options :` argument to project() are NOT propagated with `--reconfigure`. If you want a totally clean build, you can use: $ meson setup --wipe build That will work regardless of if `./build` exists or not. Specific, named targets may be addressed in `meson build -C build <target>` with "target ID" if there is one, which is the first string argument passed to target functions that have one, and unrelated to the variable name, e.g.: libexpr_dylib = library('nixexpr', …) can be addressed with: $ meson compile -C build nixexpr All targets may be addressed as their output, relative to the build directory, e.g.: $ meson compile -C build src/libexpr/libnixexpr.so But Meson does not consider intermediate files like object files targets. To build a specific object file, use Ninja directly and specify the output file relative to the build directory: $ ninja -C build src/libexpr/libnixexpr.so.p/nixexpr.cc.o To inspect the canonical source of truth on what the state of the buildsystem configuration is, use: $ meson introspect Have fun! Change-Id: Ia3e7b1e6fae26daf3162e655b4ded611a5cd57ad
meson: correctly embed sandbox shell when asked
2024-04-18 16:15:58 -06:00 · 2024-04-18 16:15:58 -06:00 · 2024-04-18 20:09:19 +00:00 · 2024-04-18 10:45:27 -06:00 · 2024-04-18 10:45:27 -06:00 · 2024-04-17 21:48:25 +00:00
288 changed files with 6052 additions and 1905 deletions
--- a/.gitignore
+++ b/.gitignore
@ -21,15 +21,9 @@ perl/Makefile.config
 /doc/manual/conf-file.json
 /doc/manual/language.json
 /doc/manual/xp-features.json
-/doc/manual/src/SUMMARY.md
-/doc/manual/src/SUMMARY-rl-next.md
-/doc/manual/src/command-ref/new-cli
-/doc/manual/src/command-ref/conf-file.md
 /doc/manual/src/command-ref/experimental-features-shortlist.md
 /doc/manual/src/contributing/experimental-feature-descriptions.md
-/doc/manual/src/language/builtins.md
-/doc/manual/src/language/builtin-constants.md
-/doc/manual/src/release-notes/rl-next.md
+/doc/manual/src/release-notes/rl-next-generated.md

 # /scripts/
 /scripts/nix-profile.sh
--- a/Makefile.config.in
+++ b/Makefile.config.in
@ -19,6 +19,7 @@ LIBBROTLI_LIBS = @LIBBROTLI_LIBS@
 LIBCURL_LIBS = @LIBCURL_LIBS@
 LIBSECCOMP_LIBS = @LIBSECCOMP_LIBS@
 LOWDOWN_LIBS = @LOWDOWN_LIBS@
+NIXDOC_LIBS = -llix_doc
 OPENSSL_LIBS = @OPENSSL_LIBS@
 PACKAGE_NAME = @PACKAGE_NAME@
 PACKAGE_VERSION = @PACKAGE_VERSION@
--- a/bench/.gitignore
+++ b/bench/.gitignore
@ -0,0 +1,3 @@
+bench-*.json
+bench-*.md
+nixpkgs
--- a/bench/README.md
+++ b/bench/README.md
@ -0,0 +1,91 @@
+# Benchmarking scripts for Lix
+
+These are very much WIP, and have a few clumsy assumptions that we would
+somewhat rather be fixed, but we have committed them to let others be able to
+do benchmarking in the mean time.
+
+## Benchmarking procedure
+
+Build some Lixes you want to compare, by whichever means you wish.
+
+Get a computer that is not busy and *strongly preferably* is bare-metal or at
+least not a cloud VM (e.g. go make coffee when running benchmarks).
+
+From the root of a Lix checkout, run `./bench/bench.sh resultlink-one
+resultlink-two`, where `resultlink-one` and `resultlink-two` are the result
+links from the builds you want to test (they can be any directory with bin/nix
+in it, however).
+
+To get the summary again, run `./bench/summarize.jq bench/bench-*.json`.
+
+## Example results
+
+(vim tip: `:r !bench/summarize.jq bench/bench-*.json` to dump it directly into
+your editor)
+
+```
+result-asserts/bin/nix --extra-experimental-features 'nix-command flakes' search --no-eval-cache github:nixos/nixpkgs/e1fa12d4f6
+c6fe19ccb59cac54b5b3f25e160870 hello
+  mean:     15.993s ± 0.081s
+            user: 13.321s | system: 1.865s
+  median:   15.994s
+  range:    15.829s ... 16.096s
+  relative: 1
+result/bin/nix --extra-experimental-features 'nix-command flakes' search --no-eval-cache github:nixos/nixpkgs/e1fa12d4f6c6fe19cc
+b59cac54b5b3f25e160870 hello
+  mean:     15.897s ± 0.075s
+            user: 13.248s | system: 1.843s
+  median:   15.88s
+  range:    15.807s ... 16.047s
+  relative: 0.994
+
+---
+
+result/bin/nix --extra-experimental-features 'nix-command flakes' eval -f bench/nixpkgs/pkgs/development/haskell-modules/hackage-packages.nix
+  mean:     0.4s ± 0.024s
+            user: 0.335s | system: 0.046s
+  median:   0.386s
+  range:    0.379s ... 0.43s
+  relative: 1
+
+result-asserts/bin/nix --extra-experimental-features 'nix-command flakes' eval -f bench/nixpkgs/pkgs/development/haskell-modules/hackage-packages.nix
+  mean:     0.404s ± 0.024s
+            user: 0.338s | system: 0.046s
+  median:   0.386s
+  range:    0.384s ... 0.436s
+  relative: 1.008
+
+---
+
+result-asserts/bin/nix --extra-experimental-features 'nix-command flakes' eval --raw --impure --expr 'with import <nixpkgs/nixos> {}; system'
+  mean:     5.838s ± 0.023s
+            user: 5.083s | system: 0.464s
+  median:   5.845s
+  range:    5.799s ... 5.867s
+  relative: 1
+
+result/bin/nix --extra-experimental-features 'nix-command flakes' eval --raw --impure --expr 'with import <nixpkgs/nixos> {}; system'
+  mean:     5.788s ± 0.044s
+            user: 5.056s | system: 0.439s
+  median:   5.79s
+  range:    5.715s ... 5.876s
+  relative: 0.991
+
+---
+
+GC_INITIAL_HEAP_SIZE=10g result-asserts/bin/nix eval --extra-experimental-features 'nix-command flakes' --raw --impure --expr 'with import <nixpkgs/nixos> {}; system'
+  mean:     4.147s ± 0.021s
+            user: 3.457s | system: 0.487s
+  median:   4.147s
+  range:    4.123s ... 4.195s
+  relative: 1
+
+GC_INITIAL_HEAP_SIZE=10g result/bin/nix eval --extra-experimental-features 'nix-command flakes' --raw --impure --expr 'with import <nixpkgs/nixos> {}; system'
+  mean:     4.149s ± 0.027s
+            user: 3.483s | system: 0.456s
+  median:   4.142s
+  range:    4.126s ... 4.215s
+  relative: 1
+
+---
+```
--- a/bench/bench.sh
+++ b/bench/bench.sh
@ -0,0 +1,62 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+shopt -s inherit_errexit
+
+scriptdir=$(cd "$(dirname -- "$0")" ; pwd -P)
+cd "$scriptdir/.."
+
+if [[ $# -lt 2 ]]; then
+    # FIXME(jade): it is a reasonable use case to want to run a benchmark run
+    # on just one build. However, since we are using hyperfine in comparison
+    # mode, we would have to combine the JSON ourselves to support that, which
+    # would probably be better done by writing a benchmarking script in
+    # not-bash.
+    echo "Fewer than two result dirs given, nothing to compare!" >&2
+    echo "Pass some directories (with names indicating which alternative they are) with bin/nix in them" >&2
+    echo "Usage: ./bench/bench.sh result-1 result-2 [result-3...]" >&2
+    exit 1
+fi
+
+_exit=""
+trap "$_exit" EXIT
+
+# XXX: yes this is very silly. flakes~!!
+nix build --impure --expr '(builtins.getFlake "git+file:.").inputs.nixpkgs.outPath' -o bench/nixpkgs
+
+export NIX_REMOTE="$(mktemp -d)"
+_exit='rm -rfv "$NIX_REMOTE"; $_exit'
+export NIX_PATH="nixpkgs=bench/nixpkgs:nixos-config=bench/configuration.nix"
+
+builds=("$@")
+
+flake_args="--extra-experimental-features 'nix-command flakes'"
+
+hyperfineArgs=(
+    --parameter-list BUILD "$(IFS=,; echo "${builds[*]}")"
+    --warmup 2 --runs 10
+)
+
+declare -A cases
+cases=(
+    [search]="{BUILD}/bin/nix $flake_args search --no-eval-cache github:nixos/nixpkgs/e1fa12d4f6c6fe19ccb59cac54b5b3f25e160870 hello"
+    [rebuild]="{BUILD}/bin/nix $flake_args eval --raw --impure --expr 'with import <nixpkgs/nixos> {}; system'"
+    [rebuild-lh]="GC_INITIAL_HEAP_SIZE=10g {BUILD}/bin/nix eval $flake_args --raw --impure --expr 'with import <nixpkgs/nixos> {}; system'"
+    [parse]="{BUILD}/bin/nix $flake_args eval -f bench/nixpkgs/pkgs/development/haskell-modules/hackage-packages.nix"
+)
+
+benches=(
+    rebuild
+    rebuild-lh
+    search
+    parse
+)
+
+for k in "${benches[@]}"; do
+    taskset -c 2,3 \
+        chrt -f 50 \
+        hyperfine "${hyperfineArgs[@]}"  --export-json="bench/bench-${k}.json" --export-markdown="bench/bench-${k}.md" "${cases[$k]}"
+done
+
+echo "Benchmarks summary (from ./bench/summarize.jq bench/bench-*.json)"
+bench/summarize.jq bench/*.json
--- a/bench/configuration.nix
+++ b/bench/configuration.nix
@ -0,0 +1,325 @@
+{
+  config,
+  pkgs,
+  lib,
+  ...
+}:
+
+{
+  boot = {
+    initrd = {
+      availableKernelModules = [
+        "xhci_pci"
+        "ahci"
+      ];
+      kernelModules = [ "dm-snapshot" ];
+      luks.devices = {
+        croot = {
+          device = "/dev/sdb";
+          allowDiscards = true;
+        };
+      };
+    };
+    kernelModules = [ "kvm-intel" ];
+    kernelPackages = pkgs.linuxPackages_latest;
+
+    loader = {
+      systemd-boot.enable = true;
+      efi.canTouchEfiVariables = true;
+    };
+  };
+
+  hardware = {
+    enableRedistributableFirmware = true;
+    cpu.intel.updateMicrocode = true;
+    opengl.driSupport32Bit = true;
+    opengl.extraPackages = with pkgs; [
+      vaapiIntel
+      intel-media-driver
+      intel-compute-runtime
+    ];
+  };
+
+  fileSystems = {
+    "/" = {
+      device = "/dev/sda2";
+      fsType = "xfs";
+      options = [ "noatime" ];
+    };
+
+    "/boot" = {
+      device = "/dev/sda1";
+      fsType = "vfat";
+    };
+
+    "/nas" = {
+      device = "nas:/";
+      fsType = "nfs4";
+      options = [
+        "ro"
+        "x-systemd.automount"
+      ];
+    };
+  };
+  swapDevices = [ { device = "/dev/swap"; } ];
+
+  networking = {
+    useDHCP = false;
+    hostName = "host";
+    wireless = {
+      enable = true;
+      interfaces = [ "eth1" ];
+    };
+    interfaces = {
+      eth0.useDHCP = true;
+      eth1.useDHCP = true;
+    };
+    wg-quick.interfaces = {
+      wg0 = {
+        address = [ "2001:db8::1" ];
+        privateKeyFile = "/etc/secrets/wg0.key";
+        peers = [
+          {
+            publicKey = "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=";
+            endpoint = "[2001:db8::2]:61021";
+            allowedIPs = [ "2001::db8:1::/64" ];
+          }
+        ];
+      };
+    };
+
+    firewall.allowedUDPPorts = [ 4567 ];
+  };
+
+  i18n = {
+    defaultLocale = "en_US.UTF-8";
+    inputMethod.enabled = "ibus";
+  };
+
+  services = {
+    xserver = {
+      enable = true;
+      layout = "us";
+      xkbVariant = "altgr-intl";
+      xkbOptions = "ctrl:nocaps";
+      libinput.enable = true;
+      wacom.enable = true;
+      videoDrivers = [ "modesetting" ];
+      modules = [ pkgs.xf86_input_wacom ];
+
+      displayManager.sx.enable = true;
+      windowManager.i3.enable = true;
+    };
+
+    udev.extraHwdb = ''
+      # not like this mattered at all
+      # we're not running udev from here
+    '';
+
+    udev.extraRules = ''
+      # ACTION=="add", SUBSYSTEM=="input", ...
+    '';
+  };
+
+  sound.enable = true;
+  hardware.pulseaudio = {
+    enable = true;
+    package = pkgs.pulseaudioFull;
+    daemon.config = {
+      lock-memory = "yes";
+      realtime-scheduling = "yes";
+      rlimit-rtprio = "-1";
+    };
+  };
+
+  programs = {
+    light.enable = true;
+    wireshark = {
+      enable = true;
+      package = pkgs.wireshark-qt;
+    };
+    gnupg.agent = {
+      enable = true;
+    };
+  };
+
+  fonts.packages = with pkgs; [
+    font-awesome
+    noto-fonts
+    noto-fonts-cjk
+    noto-fonts-emoji
+    noto-fonts-extra
+    dejavu_fonts
+    powerline-fonts
+    source-code-pro
+    cantarell-fonts
+  ];
+
+  users = {
+    mutableUsers = false;
+
+    users = {
+      user = {
+        isNormalUser = true;
+        group = "user";
+        extraGroups = [
+          "wheel"
+          "video"
+          "audio"
+          "dialout"
+          "users"
+          "kvm"
+          "wireshark"
+        ];
+        password = "unimportant";
+      };
+    };
+
+    groups = {
+      user = { };
+    };
+  };
+
+  security = {
+    pam.loginLimits = [
+      {
+        domain = "@audio";
+        item = "memlock";
+        type = "-";
+        value = "unlimited";
+      }
+      {
+        domain = "@audio";
+        item = "rtprio";
+        type = "-";
+        value = "99";
+      }
+      {
+        domain = "@audio";
+        item = "nofile";
+        type = "soft";
+        value = "99999";
+      }
+      {
+        domain = "@audio";
+        item = "nofile";
+        type = "hard";
+        value = "99999";
+      }
+    ];
+
+    sudo.extraRules = [
+      {
+        users = [ "user" ];
+        commands = [
+          {
+            command = "${pkgs.linuxPackages.cpupower}/bin/cpupower";
+            options = [ "NOPASSWD" ];
+          }
+        ];
+      }
+    ];
+  };
+
+  environment.systemPackages = with pkgs; [
+    a2jmidid
+    age
+    ardour
+    bemenu
+    blender
+    breeze-icons
+    breeze-qt5
+    bubblewrap
+    calf
+    claws-mail
+    darktable
+    duperemove
+    emacs
+    feh
+    file
+    firefox
+    fluidsynth
+    gnome3.adwaita-icon-theme
+    gnuplot
+    graphviz
+    helm
+    i3status-rust
+    inkscape
+    jack2
+    jq
+    krita
+    ldns
+    libqalculate
+    libreoffice
+    man-pages
+    nheko
+    nix-diff
+    nix-index
+    nix-output-monitor
+    open-music-kontrollers.patchmatrix
+    pamixer
+    pavucontrol
+    pciutils
+    picom
+    pwgen
+    redshift
+    ripgrep
+    rlwrap
+    silver-searcher
+    soundfont-fluid
+    whois
+    wol
+    xclip
+    xdot
+    xdotool
+    xorg.xkbcomp
+    yt-dlp
+    zathura
+    borgbackup
+    linuxPackages.cpupower
+    mtr
+    kitty
+    xf86_input_wacom
+  ];
+
+  environment.pathsToLink = [ "/share/soundfonts" ];
+
+  systemd.user.services.run-python = {
+    after = [ "network-online.target" ];
+    script = ''
+      exec ${pkgs.python3}/bin/python
+    '';
+    serviceConfig = {
+      CapabilityBoundingSet = [ "" ];
+      KeyringMode = "private";
+      LockPersonality = true;
+      MemoryDenyWriteExecute = true;
+      NoNewPrivileges = true;
+      PrivateDevices = true;
+      PrivateTmp = true;
+      PrivateUsers = true;
+      ProcSubset = "pid";
+      ProtectClock = true;
+      ProtectControlGroups = true;
+      ProtectHome = true;
+      ProtectHostname = true;
+      ProtectKernelLogs = true;
+      ProtectKernelModules = true;
+      ProtectKernelTunables = true;
+      ProtectProc = "invisible";
+      ProtectSystem = "strict";
+      RestrictAddressFamilies = "AF_INET AF_INET6";
+      RestrictNamespaces = true;
+      RestrictRealtime = true;
+      RestrictSUIDSGID = true;
+      SystemCallArchitectures = "native";
+      SystemCallFilter = [
+        "@system-service"
+        "~ @resources @privileged"
+      ];
+      UMask = "077";
+    };
+  };
+
+  system.stateVersion = "23.11";
+}
--- a/bench/summarize.jq
+++ b/bench/summarize.jq
@ -0,0 +1,22 @@
+#!/usr/bin/env -S jq -Mrf
+
+def round3:
+    . * 1000 | round | . / 1000
+    ;
+
+def stats($first):
+    [
+        "  mean:     \(.mean | round3)s ± \(.stddev | round3)s",
+        "            user: \(.user | round3)s | system: \(.system | round3)s",
+        "  median:   \(.median | round3)s",
+        "  range:    \(.min | round3)s ... \(.max | round3)s",
+        "  relative: \(.mean / $first.mean | round3)"
+    ]
+    | join("\n")
+    ;
+
+def fmt($first):
+    "\(.command)\n" + (. | stats($first))
+    ;
+
+[.results | .[0] as $first | .[] | fmt($first)] | join("\n\n") | (. + "\n\n---\n")
--- a/clang-tidy/.editorconfig
+++ b/clang-tidy/.editorconfig
@ -0,0 +1,4 @@
+# LLVM style code is 2-space indented
+[*.{cc,hh}]
+indent_style = space
+indent_size = 2
--- a/clang-tidy/FixIncludes.cc
+++ b/clang-tidy/FixIncludes.cc
@ -0,0 +1,81 @@
+#include "FixIncludes.hh"
+#include <clang-tidy/ClangTidyCheck.h>
+#include <clang/Basic/Diagnostic.h>
+#include <clang/Basic/SourceManager.h>
+#include <clang/Lex/PPCallbacks.h>
+#include <clang/Lex/Preprocessor.h>
+#include <llvm/ADT/StringRef.h>
+#include <llvm/Support/Debug.h>
+#include <memory>
+#include <set>
+#include <string>
+
+namespace nix::clang_tidy {
+
+using namespace clang;
+using namespace clang::tidy;
+
+class FixIncludesCallbacks : public PPCallbacks {
+public:
+  ClangTidyCheck &Check;
+  Preprocessor &PP;
+  FixIncludesCallbacks(ClangTidyCheck &Check, Preprocessor &PP)
+      : Check(Check), PP(PP) {}
+
+private:
+  bool Ignore = false;
+  virtual void LexedFileChanged(FileID FID, LexedFileChangeReason Reason,
+                                SrcMgr::CharacteristicKind FileType,
+                                FileID PrevFID, SourceLocation Loc) override;
+
+  virtual void InclusionDirective(SourceLocation HashLoc,
+                                  const Token &IncludeTok, StringRef FileName,
+                                  bool IsAngled, CharSourceRange FilenameRange,
+                                  OptionalFileEntryRef File,
+                                  StringRef SearchPath, StringRef RelativePath,
+                                  const Module *Imported,
+                                  SrcMgr::CharacteristicKind FileType) override;
+};
+
+void FixIncludesCallbacks::LexedFileChanged(FileID, LexedFileChangeReason,
+                                            SrcMgr::CharacteristicKind FileType,
+                                            FileID, SourceLocation) {
+  Ignore = FileType != SrcMgr::C_User;
+}
+
+void FixIncludesCallbacks::InclusionDirective(
+    SourceLocation, const Token &, StringRef, bool,
+    CharSourceRange FilenameRange, OptionalFileEntryRef File, StringRef,
+    StringRef, const Module *, SrcMgr::CharacteristicKind) {
+  if (Ignore)
+    return;
+
+  // FIXME: this is kinda evil, but this is a one-time fixup
+  const std::string SourceDir = "src/";
+
+  if (File && File->getNameAsRequested().contains(SourceDir)) {
+    StringRef Name = File->getNameAsRequested();
+    auto Idx = Name.find(SourceDir);
+    assert(Idx != std::string::npos);
+    StringRef Suffix = Name.drop_front(Idx + SourceDir.length());
+
+    if (!Suffix.starts_with("lib")) {
+      llvm::dbgs() << "ignored: " << Suffix << "\n";
+      return;
+    }
+
+    auto Diag = Check.diag(FilenameRange.getBegin(),
+                           "include needs to specify the source subdir");
+
+    Diag << FilenameRange
+         << FixItHint::CreateReplacement(FilenameRange,
+                                         ("\"" + Suffix + "\"").str());
+  }
+}
+
+void FixIncludesCheck::registerPPCallbacks(const SourceManager &,
+                                           Preprocessor *PP, Preprocessor *) {
+  PP->addPPCallbacks(std::make_unique<FixIncludesCallbacks>(*this, *PP));
+}
+
+}; // namespace nix::clang_tidy
--- a/clang-tidy/FixIncludes.hh
+++ b/clang-tidy/FixIncludes.hh
@ -0,0 +1,21 @@
+#pragma once
+///@file
+
+#include <clang-tidy/ClangTidyCheck.h>
+#include <clang/ASTMatchers/ASTMatchFinder.h>
+#include <llvm/ADT/StringRef.h>
+
+namespace nix::clang_tidy {
+
+using namespace clang;
+using namespace clang::tidy;
+
+class FixIncludesCheck : public ClangTidyCheck {
+    public:
+    FixIncludesCheck(StringRef Name, ClangTidyContext *Context)
+            : ClangTidyCheck(Name, Context) {}
+
+    void registerPPCallbacks(const SourceManager &SM, Preprocessor *PP, Preprocessor *ModuleExpanderPP) override;
+};
+
+};
--- a/clang-tidy/LixClangTidyChecks.cc
+++ b/clang-tidy/LixClangTidyChecks.cc
@ -1,5 +1,6 @@
 #include <clang-tidy/ClangTidyModule.h>
 #include <clang-tidy/ClangTidyModuleRegistry.h>
+#include "FixIncludes.hh"
 #include "HasPrefixSuffix.hh"

 namespace nix::clang_tidy {
@ -9,9 +10,10 @@ using namespace clang::tidy;
 class NixClangTidyChecks : public ClangTidyModule {
    public:
        void addCheckFactories(ClangTidyCheckFactories &CheckFactories) override {
-            CheckFactories.registerCheck<HasPrefixSuffixCheck>("nix-hasprefixsuffix");
+            CheckFactories.registerCheck<HasPrefixSuffixCheck>("lix-hasprefixsuffix");
+            CheckFactories.registerCheck<FixIncludesCheck>("lix-fixincludes");
        }
 };

-static ClangTidyModuleRegistry::Add<NixClangTidyChecks> X("nix-module", "Adds nix specific checks");
+static ClangTidyModuleRegistry::Add<NixClangTidyChecks> X("lix-module", "Adds lix specific checks");
 };
--- a/clang-tidy/meson.build
+++ b/clang-tidy/meson.build
@ -1,8 +1,13 @@
-project('nix-clang-tidy', ['cpp', 'c'],
+project('lix-clang-tidy', ['cpp', 'c'],
  version : '0.1',
  default_options : ['warning_level=3', 'cpp_std=c++20'])

 llvm = dependency('Clang', version: '>= 14', modules: ['libclang'])
-sources = ['HasPrefixSuffix.cc', 'NixClangTidyChecks.cc']
-shared_module('nix-clang-tidy', sources,
+sources = files(
+  'HasPrefixSuffix.cc',
+  'LixClangTidyChecks.cc',
+  'FixIncludes.cc',
+)
+
+shared_module('lix-clang-tidy', sources,
  dependencies: llvm)
--- a/default.nix
+++ b/default.nix
@ -1,10 +1,9 @@
-(import
-  (
-    let lock = builtins.fromJSON (builtins.readFile ./flake.lock); in
-    fetchTarball {
-      url = "https://github.com/edolstra/flake-compat/archive/${lock.nodes.flake-compat.locked.rev}.tar.gz";
-      sha256 = lock.nodes.flake-compat.locked.narHash;
-    }
-  )
-  { src = ./.; }
-).defaultNix
+(import (
+  let
+    lock = builtins.fromJSON (builtins.readFile ./flake.lock);
+  in
+  fetchTarball {
+    url = "https://github.com/edolstra/flake-compat/archive/${lock.nodes.flake-compat.locked.rev}.tar.gz";
+    sha256 = lock.nodes.flake-compat.locked.narHash;
+  }
+) { src = ./.; }).defaultNix
--- a/doc/internal-api/doxygen.cfg.in
+++ b/doc/internal-api/doxygen.cfg.in
@ -14,6 +14,8 @@ PROJECT_NAME           = "Nix"

 PROJECT_NUMBER         = @PACKAGE_VERSION@

+OUTPUT_DIRECTORY       = @docdir@
+
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
--- a/doc/internal-api/meson.build
+++ b/doc/internal-api/meson.build
@ -0,0 +1,33 @@
+doxygen_cfg = configure_file(
+  input : 'doxygen.cfg.in',
+  output : 'doxygen.cfg',
+  configuration : {
+    'PACKAGE_VERSION': meson.project_version(),
+    'RAPIDCHECK_HEADERS': rapidcheck_meson.get_variable('includedir'),
+    'docdir' : meson.current_build_dir(),
+  },
+)
+
+internal_api_docs = custom_target(
+  'internal-api-docs',
+  command : [
+    bash,
+    # Meson can you please just give us a `workdir` argument to custom targets...
+    '-c',
+    # We have to prefix the doxygen_cfg path with the project build root
+    # because of the cd in front.
+    'cd @0@ && @1@ @2@/@INPUT0@'.format(
+      meson.project_source_root(),
+      doxygen.full_path(),
+      meson.project_build_root(),
+    ),
+  ],
+  input : [
+    doxygen_cfg,
+  ],
+  output : 'html',
+  install : true,
+  install_dir : datadir / 'doc/nix/internal-api',
+)
+
+alias_target('internal-api-html', internal_api_docs)
--- a/doc/manual/book.toml
+++ b/doc/manual/book.toml
@ -7,10 +7,22 @@ additional-js = ["redirects.js"]
 edit-url-template = "https://github.com/NixOS/nix/tree/master/doc/manual/{path}"
 git-repository-url = "https://github.com/NixOS/nix"

+# Handles replacing @docroot@ with a path to ./src relative to that markdown file,
+# {{#include handlebars}}, and the @generated@ syntax used within these. it mostly
+# but not entirely replaces the links preprocessor (which we cannot simply use due
+# to @generated@ files living in a different directory to make meson happy). we do
+# not want to disable the links preprocessor entirely though because that requires
+# disabling *all* built-in preprocessors and selectively reenabling those we want.
+[preprocessor.substitute]
+command = "python3 doc/manual/substitute.py"
+before = ["anchors", "links"]
+
 [preprocessor.anchors]
 renderers = ["html"]
 command = "jq --from-file doc/manual/anchors.jq"

+[output.markdown]
+
 [output.linkcheck]
 # no Internet during the build (in the sandbox)
 follow-web-links = false
--- a/doc/manual/generate-builtin-constants.nix
+++ b/doc/manual/generate-builtin-constants.nix
@ -5,7 +5,13 @@ in

 builtinsInfo:
 let
-  showBuiltin = name: { doc, type, impure-only }:
+  showBuiltin =
+    name:
+    {
+      doc,
+      type,
+      impure-only,
+    }:
    let
      type' = optionalString (type != null) " (${type})";

--- a/doc/manual/generate-builtins.nix
+++ b/doc/manual/generate-builtins.nix
@ -5,7 +5,14 @@ in

 builtinsInfo:
 let
-  showBuiltin = name: { doc, args, arity, experimental-feature }:
+  showBuiltin =
+    name:
+    {
+      doc,
+      args,
+      arity,
+      experimental-feature,
+    }:
    let
      experimentalNotice = optionalString (experimental-feature != null) ''
        This function is only available if the [${experimental-feature}](@docroot@/contributing/experimental-features.md#xp-feature-${experimental-feature}) experimental feature is enabled.
--- a/doc/manual/generate-deps.py
+++ b/doc/manual/generate-deps.py
@ -0,0 +1,22 @@
+#!/usr/bin/env python3
+
+import glob
+import sys
+
+# meson expects makefile-style dependency declarations, i.e.
+#
+#   target: dependency...
+#
+# meson seems to pass depfiles straight on to ninja even though
+# it also parses the file itself (or at least has code to do so
+# in its tree), so we must live by ninja's rules: only slashes,
+# spaces and octothorpes can be escaped, anything else is taken
+# literally. since the rules for these aren't even the same for
+# all three we will just fail when we encounter any of them (if
+# asserts are off for some reason the depfile will likely point
+# to nonexistant paths, making everything phony and thus fine.)
+for path in glob.glob(sys.argv[1] + '/**', recursive=True):
+    assert '\\' not in path
+    assert ' ' not in path
+    assert '#' not in path
+    print("ignored:", path)
--- a/doc/manual/generate-manpage.nix
+++ b/doc/manual/generate-manpage.nix
@ -1,8 +1,26 @@
 let
  inherit (builtins)
-    attrNames attrValues fromJSON listToAttrs mapAttrs
-    concatStringsSep concatMap length lessThan replaceStrings sort;
-  inherit (import ./utils.nix) concatStrings optionalString filterAttrs trim squash unique showSettings;
+    attrNames
+    attrValues
+    fromJSON
+    listToAttrs
+    mapAttrs
+    concatStringsSep
+    concatMap
+    length
+    lessThan
+    replaceStrings
+    sort
+    ;
+  inherit (import ./utils.nix)
+    concatStrings
+    optionalString
+    filterAttrs
+    trim
+    squash
+    unique
+    showSettings
+    ;
 in

 inlineHTML: commandDump:
@ -11,7 +29,13 @@ let

  commandInfo = fromJSON commandDump;

-  showCommand = { command, details, filename, toplevel }:
+  showCommand =
+    {
+      command,
+      details,
+      filename,
+      toplevel,
+    }:
    let

      result = ''
@ -35,26 +59,27 @@ let
        ${maybeOptions}
      '';

-      showSynopsis = command: args:
+      showSynopsis =
+        command: args:
        let
-          showArgument = arg: "*${arg.label}*" + optionalString (! arg ? arity) "...";
+          showArgument = arg: "*${arg.label}*" + optionalString (!arg ? arity) "...";
          arguments = concatStringsSep " " (map showArgument args);
-        in ''
-         `${command}` [*option*...] ${arguments}
+        in
+        ''
+          `${command}` [*option*...] ${arguments}
        '';

-      maybeSubcommands = optionalString (details ? commands && details.commands != {})
-         ''
-           where *subcommand* is one of the following:
+      maybeSubcommands = optionalString (details ? commands && details.commands != { }) ''
+        where *subcommand* is one of the following:

-           ${subcommands}
-         '';
+        ${subcommands}
+      '';

-      subcommands = if length categories > 1
-        then listCategories
-        else listSubcommands details.commands;
+      subcommands = if length categories > 1 then listCategories else listSubcommands details.commands;

-      categories = sort (x: y: x.id < y.id) (unique (map (cmd: cmd.category) (attrValues details.commands)));
+      categories = sort (x: y: x.id < y.id) (
+        unique (map (cmd: cmd.category) (attrValues details.commands))
+      );

      listCategories = concatStrings (map showCategory categories);

@ -71,11 +96,11 @@ let
      '';

      # TODO: move this confusing special case out of here when implementing #8496
-      maybeStoreDocs = optionalString
-        (details ? doc)
-        (replaceStrings ["@stores@"] [storeDocs] details.doc);
+      maybeStoreDocs = optionalString (details ? doc) (
+        replaceStrings [ "@stores@" ] [ storeDocs ] details.doc
+      );

-      maybeOptions = optionalString (details.flags != {}) ''
+      maybeOptions = optionalString (details.flags != { }) ''
        # Options

        ${showOptions details.flags toplevel.flags}
@ -85,51 +110,70 @@ let
        > See [`man nix.conf`](@docroot@/command-ref/conf-file.md#command-line-flags) for overriding configuration settings with command line flags.
      '';

-      showOptions = options: commonOptions:
+      showOptions =
+        options: commonOptions:
        let
          allOptions = options // commonOptions;
          showCategory = cat: ''
            ${optionalString (cat != "") "**${cat}:**"}

            ${listOptions (filterAttrs (n: v: v.category == cat) allOptions)}
-            '';
+          '';
          listOptions = opts: concatStringsSep "\n" (attrValues (mapAttrs showOption opts));
-          showOption = name: option:
+          showOption =
+            name: option:
            let
              result = trim ''
                - ${item}
                  ${option.description}
              '';
-              item = if inlineHTML
-                then ''<span id="opt-${name}">[`--${name}`](#opt-${name})</span> ${shortName} ${labels}''
-                else "`--${name}` ${shortName} ${labels}";
-              shortName = optionalString
-                (option ? shortName)
-                ("/ `-${option.shortName}`");
-              labels = optionalString
-                (option ? labels)
-                (concatStringsSep " " (map (s: "*${s}*") option.labels));
-            in result;
+              item =
+                if inlineHTML then
+                  ''<span id="opt-${name}">[`--${name}`](#opt-${name})</span> ${shortName} ${labels}''
+                else
+                  "`--${name}` ${shortName} ${labels}";
+              shortName = optionalString (option ? shortName) ("/ `-${option.shortName}`");
+              labels = optionalString (option ? labels) (concatStringsSep " " (map (s: "*${s}*") option.labels));
+            in
+            result;
          categories = sort lessThan (unique (map (cmd: cmd.category) (attrValues allOptions)));
-        in concatStrings (map showCategory categories);
-    in squash result;
+        in
+        concatStrings (map showCategory categories);
+    in
+    squash result;

  appendName = filename: name: (if filename == "nix" then "nix3" else filename) + "-" + name;

-  processCommand = { command, details, filename, toplevel }:
+  processCommand =
+    {
+      command,
+      details,
+      filename,
+      toplevel,
+    }:
    let
      cmd = {
        inherit command;
        name = filename + ".md";
-        value = showCommand { inherit command details filename toplevel; };
+        value = showCommand {
+          inherit
+            command
+            details
+            filename
+            toplevel
+            ;
+        };
      };
-      subcommand = subCmd: processCommand {
-        command = command + " " + subCmd;
-        details = details.commands.${subCmd};
-        filename = appendName filename subCmd;
-        inherit toplevel;
-      };
-    in [ cmd ] ++ concatMap subcommand (attrNames details.commands or {});
+      subcommand =
+        subCmd:
+        processCommand {
+          command = command + " " + subCmd;
+          details = details.commands.${subCmd};
+          filename = appendName filename subCmd;
+          inherit toplevel;
+        };
+    in
+    [ cmd ] ++ concatMap subcommand (attrNames details.commands or { });

  manpages = processCommand {
    command = "nix";
@ -138,14 +182,15 @@ let
    toplevel = commandInfo.args;
  };

-  tableOfContents = let
-    showEntry = page:
-      "    - [${page.command}](command-ref/new-cli/${page.name})";
-    in concatStringsSep "\n" (map showEntry manpages) + "\n";
-
  storeDocs =
    let
-      showStore = name: { settings, doc, experimentalFeature }:
+      showStore =
+        name:
+        {
+          settings,
+          doc,
+          experimentalFeature,
+        }:
        let
          experimentalFeatureNote = optionalString (experimentalFeature != null) ''
            > **Warning**
@ -161,7 +206,8 @@ let
            extra-experimental-features = ${experimentalFeature}
            ```
          '';
-        in ''
+        in
+        ''
          ## ${name}

          ${doc}
@ -172,6 +218,7 @@ let

          ${showSettings { inherit inlineHTML; } settings}
        '';
-    in concatStrings (attrValues (mapAttrs showStore commandInfo.stores));
-
-in (listToAttrs manpages) // { "SUMMARY.md" = tableOfContents; }
+    in
+    concatStrings (attrValues (mapAttrs showStore commandInfo.stores));
+in
+listToAttrs manpages
--- a/doc/manual/generate-xp-features-shortlist.nix
+++ b/doc/manual/generate-xp-features-shortlist.nix
@ -2,8 +2,8 @@ with builtins;
 with import ./utils.nix;

 let
-  showExperimentalFeature = name: doc:
-    ''
-      - [`${name}`](@docroot@/contributing/experimental-features.md#xp-feature-${name})
-    '';
-in xps: indent "  " (concatStrings (attrValues (mapAttrs showExperimentalFeature xps)))
+  showExperimentalFeature = name: doc: ''
+    - [`${name}`](@docroot@/contributing/experimental-features.md#xp-feature-${name})
+  '';
+in
+xps: indent "  " (concatStrings (attrValues (mapAttrs showExperimentalFeature xps)))
--- a/doc/manual/generate-xp-features.nix
+++ b/doc/manual/generate-xp-features.nix
@ -2,10 +2,12 @@ with builtins;
 with import ./utils.nix;

 let
-  showExperimentalFeature = name: doc:
+  showExperimentalFeature =
+    name: doc:
    squash ''
      ## [`${name}`]{#xp-feature-${name}}

      ${doc}
    '';
-in xps: (concatStringsSep "\n" (attrValues (mapAttrs showExperimentalFeature xps)))
+in
+xps: (concatStringsSep "\n" (attrValues (mapAttrs showExperimentalFeature xps)))
--- a/doc/manual/json-to-tree.py
+++ b/doc/manual/json-to-tree.py
@ -0,0 +1,61 @@
+#!/usr/bin/env python3
+
+"""
+This script is a helper for this project's Meson buildsystem, to replace its
+usage of `nix eval --write-to`. Writing a JSON object as a nested directory
+tree is more generic, easier to maintain, and far, far less cursed. Nix
+has 'good' support for JSON output. Let's just use it.
+"""
+
+import argparse
+from pathlib import Path
+import json
+import sys
+
+name = 'json-to-tree.py'
+
+def log(*args, **kwargs):
+    kwargs['file'] = sys.stderr
+    return print(f'{name}:', *args, **kwargs)
+
+def write_dict_to_directory(current_directory: Path, data: dict, files_written=0):
+    current_directory.mkdir(parents=True, exist_ok=True)
+    for key, value in data.items():
+        nested_path = current_directory / key
+        match value:
+            case dict(nested_data):
+                files_written += write_dict_to_directory(nested_path, nested_data)
+
+            case str(content):
+                nested_path.write_text(content)
+                files_written += 1
+
+            case rest:
+                assert False, \
+                    f'should have been called on a dict or string, not {type(rest)=}\n\t{rest=}'
+
+    return files_written
+
+def main():
+    parser = argparse.ArgumentParser(name)
+    parser.add_argument('-i', '--input', type=argparse.FileType('r'), default='-',
+        help='The JSON input to operate on and output as a directory tree',
+    )
+    parser.add_argument('-o', '--output', type=Path, required=True,
+        help='The place to put the directory tree',
+    )
+    args = parser.parse_args()
+
+    json_string = args.input.read()
+
+    try:
+        data = json.loads(json_string)
+    except json.JSONDecodeError:
+        log(f'could not decode JSON from input: {json_string}')
+        raise
+
+
+    files_written = write_dict_to_directory(args.output, data)
+    log(f'wrote {files_written} files')
+
+sys.exit(main())
--- a/doc/manual/local.mk
+++ b/doc/manual/local.mk
@ -17,14 +17,14 @@ man-pages := $(foreach n, \
 	nix-hash.1 nix-copy-closure.1 \
 	nix.conf.5 nix-daemon.8 \
 	nix-profiles.5 \
-, $(d)/$(n))
+, doc/manual/generated/in/$(n))

 # man pages for subcommands
 # convert from `$(d)/src/command-ref/nix-{1}/{2}.md` to `$(d)/nix-{1}-{2}.1`
 # FIXME: unify with how nix3-cli man pages are generated
 man-pages += $(foreach subcommand, \
 	$(filter-out %opt-common.md %env-common.md, $(wildcard $(d)/src/command-ref/nix-*/*.md)), \
-	$(d)/$(subst /,-,$(subst $(d)/src/command-ref/,,$(subst .md,.1,$(subcommand)))))
+	doc/manual/generated/in/$(subst /,-,$(subst $(d)/src/command-ref/,,$(subst .md,.1,$(subcommand)))))

 clean-files += $(d)/*.1 $(d)/*.5 $(d)/*.8

@ -39,81 +39,91 @@ dummy-env = env -i \

 nix-eval = $(dummy-env) $(doc_nix) eval --experimental-features nix-command -I nix/corepkgs=corepkgs --store dummy:// --impure --raw

-$(d)/nix-env-%.1: $(d)/src/command-ref/nix-env/%.md
+doc/manual/generated/in/nix-env-%.1: doc/manual/generated/out
 	$(trace-gen) doc/manual/render-manpage.sh \
-		--unescape-dashes "$(subst nix-env-,nix-env --,$$(basename "$@" .1))" 1 $^ $^.tmp $@
+		--out-no-smarty "$(subst nix-env-,nix-env --,$$(basename "$@" .1))" 1 \
+		doc/manual/generated/out/markdown/command-ref/nix-env/$*.md \
+		$@

-$(d)/nix-store-%.1: $(d)/src/command-ref/nix-store/%.md
+doc/manual/generated/in/nix-store-%.1: doc/manual/generated/out
 	$(trace-gen) doc/manual/render-manpage.sh \
-		--unescape-dashes "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" 1 $^ $^.tmp $@
+		--out-no-smarty "$(subst nix-store-,nix-store --,$$(basename "$@" .1))" 1 \
+		doc/manual/generated/out/markdown/command-ref/nix-store/$*.md \
+		$@


-$(d)/%.1: $(d)/src/command-ref/%.md
-	$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .1)" 1 $^ $^.tmp $@
+doc/manual/generated/in/%.1: doc/manual/generated/out
+	$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .1)" 1 \
+		doc/manual/generated/out/markdown/command-ref/$*.md \
+		$@

-$(d)/%.8: $(d)/src/command-ref/%.md
-	$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .8)" 8 $^ $^.tmp $@
+doc/manual/generated/in/%.8: doc/manual/generated/out
+	$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .8)" 8 \
+		doc/manual/generated/out/markdown/command-ref/$*.md \
+		$@

-$(d)/nix.conf.5: $(d)/src/command-ref/conf-file.md
-	$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 $^ $^.tmp $@
+doc/manual/generated/in/nix.conf.5: doc/manual/generated/out
+	$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 \
+		doc/manual/generated/out/markdown/command-ref/conf-file.md \
+		$@

-$(d)/nix-profiles.5: $(d)/src/command-ref/files/profiles.md
-	$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 $^ $^.tmp $@
+doc/manual/generated/in/nix-profiles.5: doc/manual/generated/out
+	$(trace-gen) doc/manual/render-manpage.sh "$$(basename $@ .5)" 5 \
+		doc/manual/generated/out/markdown/command-ref/files/profiles.md \
+		$@

-$(d)/src/SUMMARY.md: $(d)/src/SUMMARY.md.in $(d)/src/SUMMARY-rl-next.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md
-	@cp $< $@
-	@doc/manual/process-includes.sh $@ $@
-
-$(d)/src/command-ref/new-cli: $(d)/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(doc_nix)
+doc/manual/generated/in/command-ref/new-cli: doc/manual/generated/in/nix.json $(d)/utils.nix $(d)/generate-manpage.nix $(doc_nix)
+	@mkdir -p doc/manual/generated/in/command-ref
 	@rm -rf $@ $@.tmp
 	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-manpage.nix true (builtins.readFile $<)'
 	@mv $@.tmp $@

-$(d)/src/command-ref/conf-file.md: $(d)/conf-file.json $(d)/utils.nix $(d)/src/command-ref/conf-file-prefix.md $(d)/src/command-ref/experimental-features-shortlist.md $(doc_nix)
-	@cat doc/manual/src/command-ref/conf-file-prefix.md > $@.tmp
-	$(trace-gen) $(nix-eval) --expr '(import doc/manual/utils.nix).showSettings { inlineHTML = true; } (builtins.fromJSON (builtins.readFile $<))' >> $@.tmp;
-	@mv $@.tmp $@
+doc/manual/generated/in/command-ref/conf-file.md: doc/manual/generated/in/conf-file.json $(d)/utils.nix doc/manual/generated/in/command-ref/experimental-features-shortlist.md $(doc_nix)
+	@mkdir -p doc/manual/generated/in/command-ref
+	$(trace-gen) $(nix-eval) --expr '(import doc/manual/utils.nix).showSettings { inlineHTML = true; } (builtins.fromJSON (builtins.readFile $<))' >> $@

-$(d)/nix.json: $(doc_nix)
+doc/manual/generated/in/nix.json: $(doc_nix)
+	@mkdir -p doc/manual/generated/in
 	$(trace-gen) $(dummy-env) $(doc_nix) __dump-cli > $@.tmp
 	@mv $@.tmp $@

-$(d)/conf-file.json: $(doc_nix)
+doc/manual/generated/in/conf-file.json: $(doc_nix)
+	@mkdir -p doc/manual/generated/in
 	$(trace-gen) $(dummy-env) $(doc_nix) show-config --json --experimental-features nix-command > $@.tmp
 	@mv $@.tmp $@

-$(d)/src/contributing/experimental-feature-descriptions.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(doc_nix)
+doc/manual/generated/in/contributing/experimental-feature-descriptions.md: doc/manual/generated/in/xp-features.json $(d)/utils.nix $(d)/generate-xp-features.nix $(doc_nix)
+	@mkdir -p doc/manual/generated/in/contributing
 	@rm -rf $@ $@.tmp
 	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features.nix (builtins.fromJSON (builtins.readFile $<))'
 	@mv $@.tmp $@

-$(d)/src/command-ref/experimental-features-shortlist.md: $(d)/xp-features.json $(d)/utils.nix $(d)/generate-xp-features-shortlist.nix $(doc_nix)
+doc/manual/generated/in/command-ref/experimental-features-shortlist.md: doc/manual/generated/in/xp-features.json $(d)/utils.nix $(d)/generate-xp-features-shortlist.nix $(doc_nix)
+	@mkdir -p doc/manual/generated/in/command-ref
 	@rm -rf $@ $@.tmp
 	$(trace-gen) $(nix-eval) --write-to $@.tmp --expr 'import doc/manual/generate-xp-features-shortlist.nix (builtins.fromJSON (builtins.readFile $<))'
 	@mv $@.tmp $@

-$(d)/xp-features.json: $(doc_nix)
+doc/manual/generated/in/xp-features.json: $(doc_nix)
 	$(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(doc_nix) __dump-xp-features > $@.tmp
 	@mv $@.tmp $@

-$(d)/src/language/builtins.md: $(d)/language.json $(d)/generate-builtins.nix $(d)/src/language/builtins-prefix.md $(doc_nix)
-	@cat doc/manual/src/language/builtins-prefix.md > $@.tmp
-	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<)).builtins' >> $@.tmp;
-	@cat doc/manual/src/language/builtins-suffix.md >> $@.tmp
-	@mv $@.tmp $@
+doc/manual/generated/in/language/builtins.md: doc/manual/generated/in/language.json $(d)/generate-builtins.nix $(doc_nix)
+	@mkdir -p doc/manual/generated/in/language
+	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtins.nix (builtins.fromJSON (builtins.readFile $<)).builtins' >> $@

-$(d)/src/language/builtin-constants.md: $(d)/language.json $(d)/generate-builtin-constants.nix $(d)/src/language/builtin-constants-prefix.md $(doc_nix)
-	@cat doc/manual/src/language/builtin-constants-prefix.md > $@.tmp
-	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtin-constants.nix (builtins.fromJSON (builtins.readFile $<)).constants' >> $@.tmp;
-	@cat doc/manual/src/language/builtin-constants-suffix.md >> $@.tmp
-	@mv $@.tmp $@
+doc/manual/generated/in/language/builtin-constants.md: doc/manual/generated/in/language.json $(d)/generate-builtin-constants.nix $(doc_nix)
+	@mkdir -p doc/manual/generated/in/language
+	$(trace-gen) $(nix-eval) --expr 'import doc/manual/generate-builtin-constants.nix (builtins.fromJSON (builtins.readFile $<)).constants' >> $@

-$(d)/language.json: $(doc_nix)
+doc/manual/generated/in/language.json: $(doc_nix)
+	@mkdir -p doc/manual/generated/in
 	$(trace-gen) $(dummy-env) NIX_PATH=nix/corepkgs=corepkgs $(doc_nix) __dump-language > $@.tmp
 	@mv $@.tmp $@

 # Generate "Upcoming release" notes (or clear it and remove from menu)
-$(d)/src/release-notes/rl-next.md: $(d)/rl-next $(d)/rl-next/*
+doc/manual/generated/in/release-notes/rl-next-generated.md: $(d)/rl-next $(d)/rl-next/*
+	@mkdir -p doc/manual/generated/in/release-notes
 	@if type -p build-release-notes > /dev/null; then \
 		echo "  GEN   " $@; \
 		build-release-notes doc/manual/rl-next > $@; \
@ -122,14 +132,6 @@ $(d)/src/release-notes/rl-next.md: $(d)/rl-next $(d)/rl-next/*
 		true > $@; \
 	fi

-$(d)/src/SUMMARY-rl-next.md: $(d)/src/release-notes/rl-next.md
-	$(trace-gen) true
-	@if [ -s $< ]; then \
-		echo '  - [Upcoming release](release-notes/rl-next.md)' > $@; \
-	else \
-	  true > $@; \
-	fi
-
 # Generate the HTML manual.
 .PHONY: manual-html
 manual-html: $(docdir)/manual/index.html
@ -146,9 +148,9 @@ $(mandir)/man1/nix3-manpages: doc/manual/generated/man1/nix3-manpages
 	@mkdir -p $(DESTDIR)$$(dirname $@)
 	$(trace-install) install -m 0644 $$(dirname $<)/* $(DESTDIR)$$(dirname $@)

-doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
+doc/manual/generated/man1/nix3-manpages: doc/manual/generated/out
 	@mkdir -p $(DESTDIR)$$(dirname $@)
-	$(trace-gen) for i in doc/manual/src/command-ref/new-cli/*.md; do \
+	$(trace-gen) for i in doc/manual/generated/out/markdown/command-ref/new-cli/*.md; do \
 		name=$$(basename $$i .md); \
 		tmpFile=$$(mktemp); \
 		if [[ $$name = SUMMARY ]]; then continue; fi; \
@ -159,23 +161,18 @@ doc/manual/generated/man1/nix3-manpages: $(d)/src/command-ref/new-cli
 	done
 	@touch $@

-$(docdir)/manual/index.html: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md $(d)/src/command-ref/new-cli $(d)/src/contributing/experimental-feature-descriptions.md $(d)/src/command-ref/conf-file.md $(d)/src/language/builtins.md $(d)/src/language/builtin-constants.md $(d)/src/release-notes/rl-next.md
+doc/manual/generated/out: $(MANUAL_SRCS) $(d)/book.toml $(d)/anchors.jq $(d)/custom.css $(d)/src/SUMMARY.md doc/manual/generated/in/command-ref/new-cli doc/manual/generated/in/command-ref/experimental-features-shortlist.md doc/manual/generated/in/contributing/experimental-feature-descriptions.md doc/manual/generated/in/command-ref/conf-file.md doc/manual/generated/in/language/builtins.md doc/manual/generated/in/language/builtin-constants.md doc/manual/generated/in/release-notes/rl-next-generated.md $(d)/substitute.py
+	@rm -rf $@
 	$(trace-gen) \
-		tmp="$$(mktemp -d)"; \
-		cp -r doc/manual "$$tmp"; \
-		find "$$tmp" -name '*.md' | while read -r file; do \
-			doc/manual/process-includes.sh $$file $$file; \
-		done; \
-		find "$$tmp" -name '*.md' | while read -r file; do \
-			docroot="$$(realpath --relative-to="$$(dirname "$$file")" $$tmp/manual/src)"; \
-			sed -i "s,@docroot@,$$docroot,g" "$$file"; \
-		done; \
-		set -euo pipefail; \
-		RUST_LOG=warn mdbook build "$$tmp/manual" -d $(DESTDIR)$(docdir)/manual.tmp 2>&1 \
-			| { grep -Fv "because fragment resolution isn't implemented" || :; }; \
-		rm -rf "$$tmp/manual"
+		MDBOOK_SUBSTITUTE_SEARCH=doc/manual/generated/in \
+		RUST_LOG=warn \
+		mdbook build doc/manual -d generated/out 2>&1 \
+			| { grep -Fv "because fragment resolution isn't implemented" || :; }
+	@find $@ -iname meson.build -delete
+
+$(docdir)/manual/index.html: doc/manual/generated/out
+	@mkdir -p $(DESTDIR)$(docdir)
 	@rm -rf $(DESTDIR)$(docdir)/manual
-	@mv $(DESTDIR)$(docdir)/manual.tmp/html $(DESTDIR)$(docdir)/manual
-	@rm -rf $(DESTDIR)$(docdir)/manual.tmp
+	@cp -r $</html $(DESTDIR)$(docdir)/manual

 endif
--- a/doc/manual/meson.build
+++ b/doc/manual/meson.build
@ -7,15 +7,15 @@ nix_env_for_docs = {
 }

 nix_for_docs = [ nix, '--experimental-features', 'nix-command' ]
-nix_eval_for_docs = nix_for_docs + [
+nix_eval_for_docs_common = nix_for_docs + [
  'eval',
  '-I', 'nix/corepkgs=corepkgs',
  '--store', 'dummy://',
  '--impure',
-  '--raw',
 ]
+nix_eval_for_docs = nix_eval_for_docs_common + '--raw'

-nix_conf_file_json = custom_target(
+conf_file_json = custom_target(
  command : nix_for_docs + [ 'show-config', '--json' ],
  capture : true,
  output : 'conf-file.json',
@ -30,7 +30,7 @@ nix_conf_file_md_body = custom_target(
  capture : true,
  input : [
    'utils.nix',
-    nix_conf_file_json,
+    conf_file_json,
  ],
  output : 'conf-file.md.body',
  env : nix_env_for_docs,
@ -40,7 +40,7 @@ nix_conf_file_md = custom_target(
  command : [ 'cat', '@INPUT@' ],
  capture : true,
  input : [
-    'src/command-ref/conf-file-prefix.md',
+    'src/command-ref/conf-file.md',
    nix_conf_file_md_body,
  ],
  output : 'conf-file.md',
@ -51,20 +51,84 @@ nix_exp_features_json = custom_target(
  capture : true,
  output : 'xp-features.json',
 )
-nix_exp_feature_shortlist = custom_target(
-  command : nix_eval_for_docs + [
-    '--expr',
-    'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@))',
-  ],
-  input : [
-    'generate-xp-features-shortlist.nix',
-    nix_exp_features_json,
-  ],
-  output : 'experimental-features-shortlist.md',
+
+language_json = custom_target(
+  command: [nix, '__dump-language'],
+  output : 'language.json',
  capture : true,
  env : nix_env_for_docs,
 )

+nix3_cli_json = custom_target(
+  command : [ nix, '__dump-cli' ],
+  capture : true,
+  output : 'nix.json',
+  env : nix_env_for_docs,
+)
+
+generate_manual_deps = files(
+  'generate-deps.py',
+)
+
+# Generates builtins.md and builtin-constants.md.
+subdir('src/language')
+# Generates new-cli pages, experimental-features-shortlist.md, and conf-file.md.
+subdir('src/command-ref')
+# Generates experimental-feature-descriptions.md.
+subdir('src/contributing')
+# Generates rl-next-generated.md.
+subdir('src/release-notes')
+
+manual = custom_target(
+  'manual',
+  command : [
+    bash,
+    '-euo', 'pipefail',
+    '-c',
+    '''
+        @0@ @INPUT0@ @CURRENT_SOURCE_DIR@ > @DEPFILE@
+        cd @SOURCE_ROOT@
+        @1@ build doc/manual -d @2@ | { grep -Fv "because fragment resolution isn't implemented" || :; }
+        rm -rf @2@/manual
+        mv @2@/html @2@/manual
+        find @2@/manual -iname meson.build -delete
+    '''.format(
+      python.full_path(),
+      mdbook.full_path(),
+      meson.current_build_dir(),
+    ),
+  ],
+  input : [
+    generate_manual_deps,
+    'book.toml',
+    'anchors.jq',
+    'custom.css',
+    nix3_cli_files,
+    experimental_features_shortlist_md,
+    experimental_feature_descriptions_md,
+    conf_file_md,
+    builtins_md,
+    builtin_constants_md,
+    rl_next_generated,
+  ],
+  output : [
+    'manual',
+    'markdown',
+  ],
+  depfile : 'manual.d',
+  env : {
+    'RUST_LOG': 'info',
+    'MDBOOK_SUBSTITUTE_SEARCH': meson.current_build_dir() / 'src',
+  },
+)
+manual_html = manual[0]
+manual_md = manual[1]
+
+install_subdir(
+  manual_html.full_path(),
+  install_dir : datadir / 'doc/nix',
+)
+
 nix_nested_manpages = [
  [ 'nix-env',
    [
@ -109,17 +173,20 @@ nix_nested_manpages = [

 foreach command : nix_nested_manpages
  foreach page : command[1]
+    title = command[0] + ' --' + page
+    section = '1'
    custom_target(
      command : [
        './render-manpage.sh',
-        '--unescape-dashes',
-        command[0] + ' --' + page,
-        '1',
-        '@INPUT@',
-        '@OUTPUT@.tmp',
-        '@OUTPUT@',
+        '--out-no-smarty',
+        title,
+        section,
+        '@INPUT0@/command-ref' / command[0] / (page + '.md'),
+        '@OUTPUT0@',
+      ],
+      input : [
+        manual_md,
      ],
-      input : 'src/command-ref' / command[0] / (page + '.md'),
      output : command[0] + '-' + page + '.1',
      install : true,
      install_dir : mandir / 'man1',
@ -127,25 +194,6 @@ foreach command : nix_nested_manpages
  endforeach
 endforeach

-nix3_cli_json = custom_target(
-  command : [ nix, '__dump-cli' ],
-  capture : true,
-  output : 'nix.json',
-)
-nix3_cli_files = custom_target(
-  command : nix_eval_for_docs + [
-    '--write-to', '@OUTPUT@',
-    '--expr',
-    'import @INPUT1@ true (builtins.readFile @INPUT0@)',
-  ],
-  input : [
-    nix3_cli_json,
-    'generate-manpage.nix',
-    'utils.nix',
-  ],
-  output : 'new-cli',
-)
-
 nix3_manpages = [
  'nix3-build',
  'nix3-bundle',
@ -236,16 +284,20 @@ nix3_manpages = [
 ]

 foreach page : nix3_manpages
+  section = '1'
  custom_target(
    command : [
-      './render-manpage.sh',
+      bash,
+      '@INPUT0@',
      page,
-      '1',
-      '@INPUT0@/' + page + '.md',
-      '@OUTPUT@.tmp',
+      section,
+      '@INPUT1@/command-ref/new-cli/@0@.md'.format(page),
      '@OUTPUT@',
    ],
-    input : nix3_cli_files,
+    input : [
+      'render-manpage.sh',
+      manual_md,
+    ],
    output : page + '.1',
    install : true,
    install_dir : mandir / 'man1',
@ -263,24 +315,30 @@ nix_manpages = [
  [ 'nix-channel', 1 ],
  [ 'nix-hash', 1 ],
  [ 'nix-copy-closure', 1 ],
-  [ 'nix.conf', 5, nix_conf_file_md, nix_exp_feature_shortlist ],
+  [ 'nix.conf', 5, 'conf-file.md' ],
  [ 'nix-daemon', 8 ],
-  [ 'nix-profiles', 5, 'src/command-ref/files/profiles.md', nix_exp_feature_shortlist ],
+  [ 'nix-profiles', 5, 'files/profiles.md' ],
 ]

 foreach entry : nix_manpages
+  title = entry[0]
+  # nix.conf.5 and nix-profiles.5 are based off of conf-file.md and files/profiles.md,
+  # rather than a stem identical to its mdbook source.
+  # Therefore we use an optional third element of this array to override the name pattern
+  md_file = entry.get(2, title + '.md')
+  section = entry[1].to_string()
  custom_target(
    command : [
-      './render-manpage.sh',
-      entry[0],
-      entry[1].to_string(),
+      bash,
      '@INPUT0@',
-      '@OUTPUT@.tmp',
+      title,
+      section,
+      '@INPUT1@/command-ref/@0@'.format(md_file),
      '@OUTPUT@',
-      meson.current_build_dir(),
    ],
    input : [
-      entry.get(2, 'src/command-ref' / (entry[0] + '.md')),
+      'render-manpage.sh',
+      manual_md,
      entry.get(3, []),
    ],
    output : '@0@.@1@'.format(entry[0], entry[1]),
--- a/doc/manual/render-manpage.sh
+++ b/doc/manual/render-manpage.sh
@ -2,26 +2,24 @@

 set -euo pipefail

-unescape_dashes=
+lowdown_args=

-if [ "$1" = --unescape-dashes ]; then
-    unescape_dashes=yes
+if [ "$1" = --out-no-smarty ]; then
+    lowdown_args=--out-no-smarty
    shift
 fi

+[ "$#" = 4 ] || {
+    echo "wrong number of args passed" >&2
+    exit 1
+}
+
 title="$1"
 section="$2"
 infile="$3"
-tmpfile="$4"
-outfile="$5"
+outfile="$4"

-printf "Title: %s\n\n" "$title" > "$tmpfile"
-cat "$infile" >> "$tmpfile"
-"$(dirname "$0")"/process-includes.sh "$infile" "$tmpfile"
-lowdown -sT man --nroff-nolinks -M section="$section" "$tmpfile" -o "$outfile"
-if [ -n "$unescape_dashes" ]; then
-    # fix up `lowdown`'s automatic escaping of `--`
-    # https://github.com/kristapsdz/lowdown/blob/edca6ce6d5336efb147321a43c47a698de41bb7c/entity.c#L202
-    sed -i 's/\e\[u2013\]/--/' "$outfile"
-fi
-rm "$tmpfile"
+(
+    printf "Title: %s\n\n" "$title"
+    cat "$infile"
+) | lowdown -sT man --nroff-nolinks $lowdown_args -M section="$section" -o "$outfile"
--- a/doc/manual/rl-next/better-errors-in-nix-repl.md
+++ b/doc/manual/rl-next/better-errors-in-nix-repl.md
@ -1,6 +1,7 @@
 ---
 synopsis: Concise error printing in `nix repl`
 prs: 9928
+cls: 811
 ---

 Previously, if an element of a list or attribute set threw an error while
--- a/doc/manual/rl-next/new-assertions.md
+++ b/doc/manual/rl-next/new-assertions.md
@ -0,0 +1,23 @@
+---
+synopsis: Lix turns more internal bugs into crashes
+cls: [797, 626]
+---
+
+Lix now enables build options such as trapping on signed overflow and enabling
+libstdc++ assertions by default. These may find new bugs in Lix, which will
+present themselves as Lix processes aborting, potentially without an error
+message.
+
+If Lix processes abort on your machine, this is a bug. Please file a bug,
+ideally with the core dump (or information from it).
+
+On Linux, run `coredumpctl list`, find the crashed process's PID at
+the bottom of the list, then run `coredumpctl info THE-PID`. You can then paste
+the output into a bug report.
+
+On macOS, open the Console app from Applications/Utilities, select Crash
+Reports, select the crash report in question. Right click on it, select Open In
+Finder, then include that file in your bug report. [See the Apple
+documentation][apple-crashreport] for more details.
+
+[apple-crashreport]: https://developer.apple.com/documentation/xcode/acquiring-crash-reports-and-diagnostic-logs#Locate-crash-reports-and-memory-logs-on-the-device
--- a/doc/manual/rl-next/no-cache-eval-errors.md
+++ b/doc/manual/rl-next/no-cache-eval-errors.md
@ -0,0 +1,8 @@
+---
+synopsis: re-evaluate cached evaluation errors
+cls: 771
+---
+
+"cached failure of [expr]" errors have been removed: expressions already in the
+eval cache as a failure will now simply be re-evaluated, removing the need to
+set `--no-eval-cache` or similar to see the error.
--- a/doc/manual/rl-next/repl-doc-command.md
+++ b/doc/manual/rl-next/repl-doc-command.md
@ -0,0 +1,13 @@
+---
+synopsis: Experimental REPL support for documentation comments using `:doc`
+cls: 564
+---
+
+Using `:doc` in the REPL now supports showing documentation comments when defined on a function.
+
+Previously this was only able to document builtins, however it now will show comments defined on a lambda as well.
+
+This support is experimental and relies on an embedded version of [nix-doc](https://github.com/lf-/nix-doc).
+
+The logic also supports limited Markdown formatting of doccomments and should easily support any [RFC 145](https://github.com/NixOS/rfcs/blob/master/rfcs/0145-doc-strings.md)
+compatible documentation comments in addition to simple commented documentation.
--- a/doc/manual/rl-next/repl-overlays.md
+++ b/doc/manual/rl-next/repl-overlays.md
@ -0,0 +1,36 @@
+---
+synopsis: Add `repl-overlays` option
+prs: 10203
+cls: 504
+---
+
+A `repl-overlays` option has been added, which specifies files that can overlay
+and modify the top-level bindings in `nix repl`. For example, with the
+following contents in `~/.config/nix/repl.nix`:
+
+```nix
+info: final: prev: let
+  optionalAttrs = predicate: attrs:
+    if predicate
+    then attrs
+    else {};
+in
+  optionalAttrs (prev ? legacyPackages && prev.legacyPackages ? ${info.currentSystem})
+  {
+    pkgs = prev.legacyPackages.${info.currentSystem};
+  }
+```
+
+We can run `nix repl` and use `pkgs` to refer to `legacyPackages.${currentSystem}`:
+
+```ShellSession
+$ nix repl --repl-overlays ~/.config/nix/repl.nix nixpkgs
+Lix 2.90.0
+Type :? for help.
+Loading installable 'flake:nixpkgs#'...
+Added 5 variables.
+Loading 'repl-overlays'...
+Added 6 variables.
+nix-repl> pkgs.bash
+«derivation /nix/store/g08b5vkwwh0j8ic9rkmd8mpj878rk62z-bash-5.2p26.drv»
+```
--- a/doc/manual/src/SUMMARY.md.in
+++ b/doc/manual/src/SUMMARY.md.in
@ -88,7 +88,92 @@
    - [nix-instantiate](command-ref/nix-instantiate.md)
    - [nix-prefetch-url](command-ref/nix-prefetch-url.md)
  - [Experimental Commands](command-ref/experimental-commands.md)
-{{#include ./command-ref/new-cli/SUMMARY.md}}
+    - [nix](command-ref/new-cli/nix.md)
+    - [nix build](command-ref/new-cli/nix3-build.md)
+    - [nix bundle](command-ref/new-cli/nix3-bundle.md)
+    - [nix copy](command-ref/new-cli/nix3-copy.md)
+    - [nix daemon](command-ref/new-cli/nix3-daemon.md)
+    - [nix derivation](command-ref/new-cli/nix3-derivation.md)
+    - [nix derivation add](command-ref/new-cli/nix3-derivation-add.md)
+    - [nix derivation show](command-ref/new-cli/nix3-derivation-show.md)
+    - [nix develop](command-ref/new-cli/nix3-develop.md)
+    - [nix doctor](command-ref/new-cli/nix3-doctor.md)
+    - [nix edit](command-ref/new-cli/nix3-edit.md)
+    - [nix eval](command-ref/new-cli/nix3-eval.md)
+    - [nix flake](command-ref/new-cli/nix3-flake.md)
+    - [nix flake archive](command-ref/new-cli/nix3-flake-archive.md)
+    - [nix flake check](command-ref/new-cli/nix3-flake-check.md)
+    - [nix flake clone](command-ref/new-cli/nix3-flake-clone.md)
+    - [nix flake info](command-ref/new-cli/nix3-flake-info.md)
+    - [nix flake init](command-ref/new-cli/nix3-flake-init.md)
+    - [nix flake lock](command-ref/new-cli/nix3-flake-lock.md)
+    - [nix flake metadata](command-ref/new-cli/nix3-flake-metadata.md)
+    - [nix flake new](command-ref/new-cli/nix3-flake-new.md)
+    - [nix flake prefetch](command-ref/new-cli/nix3-flake-prefetch.md)
+    - [nix flake show](command-ref/new-cli/nix3-flake-show.md)
+    - [nix flake update](command-ref/new-cli/nix3-flake-update.md)
+    - [nix fmt](command-ref/new-cli/nix3-fmt.md)
+    - [nix hash](command-ref/new-cli/nix3-hash.md)
+    - [nix hash file](command-ref/new-cli/nix3-hash-file.md)
+    - [nix hash path](command-ref/new-cli/nix3-hash-path.md)
+    - [nix hash to-base16](command-ref/new-cli/nix3-hash-to-base16.md)
+    - [nix hash to-base32](command-ref/new-cli/nix3-hash-to-base32.md)
+    - [nix hash to-base64](command-ref/new-cli/nix3-hash-to-base64.md)
+    - [nix hash to-sri](command-ref/new-cli/nix3-hash-to-sri.md)
+    - [nix help](command-ref/new-cli/nix3-help.md)
+    - [nix help-stores](command-ref/new-cli/nix3-help-stores.md)
+    - [nix key](command-ref/new-cli/nix3-key.md)
+    - [nix key convert-secret-to-public](command-ref/new-cli/nix3-key-convert-secret-to-public.md)
+    - [nix key generate-secret](command-ref/new-cli/nix3-key-generate-secret.md)
+    - [nix log](command-ref/new-cli/nix3-log.md)
+    - [nix nar](command-ref/new-cli/nix3-nar.md)
+    - [nix nar cat](command-ref/new-cli/nix3-nar-cat.md)
+    - [nix nar dump-path](command-ref/new-cli/nix3-nar-dump-path.md)
+    - [nix nar ls](command-ref/new-cli/nix3-nar-ls.md)
+    - [nix path-info](command-ref/new-cli/nix3-path-info.md)
+    - [nix print-dev-env](command-ref/new-cli/nix3-print-dev-env.md)
+    - [nix profile](command-ref/new-cli/nix3-profile.md)
+    - [nix profile diff-closures](command-ref/new-cli/nix3-profile-diff-closures.md)
+    - [nix profile history](command-ref/new-cli/nix3-profile-history.md)
+    - [nix profile install](command-ref/new-cli/nix3-profile-install.md)
+    - [nix profile list](command-ref/new-cli/nix3-profile-list.md)
+    - [nix profile remove](command-ref/new-cli/nix3-profile-remove.md)
+    - [nix profile rollback](command-ref/new-cli/nix3-profile-rollback.md)
+    - [nix profile upgrade](command-ref/new-cli/nix3-profile-upgrade.md)
+    - [nix profile wipe-history](command-ref/new-cli/nix3-profile-wipe-history.md)
+    - [nix realisation](command-ref/new-cli/nix3-realisation.md)
+    - [nix realisation info](command-ref/new-cli/nix3-realisation-info.md)
+    - [nix registry](command-ref/new-cli/nix3-registry.md)
+    - [nix registry add](command-ref/new-cli/nix3-registry-add.md)
+    - [nix registry list](command-ref/new-cli/nix3-registry-list.md)
+    - [nix registry pin](command-ref/new-cli/nix3-registry-pin.md)
+    - [nix registry remove](command-ref/new-cli/nix3-registry-remove.md)
+    - [nix repl](command-ref/new-cli/nix3-repl.md)
+    - [nix run](command-ref/new-cli/nix3-run.md)
+    - [nix search](command-ref/new-cli/nix3-search.md)
+    - [nix shell](command-ref/new-cli/nix3-shell.md)
+    - [nix show-config](command-ref/new-cli/nix3-show-config.md)
+    - [nix store](command-ref/new-cli/nix3-store.md)
+    - [nix store add-file](command-ref/new-cli/nix3-store-add-file.md)
+    - [nix store add-path](command-ref/new-cli/nix3-store-add-path.md)
+    - [nix store cat](command-ref/new-cli/nix3-store-cat.md)
+    - [nix store copy-log](command-ref/new-cli/nix3-store-copy-log.md)
+    - [nix store copy-sigs](command-ref/new-cli/nix3-store-copy-sigs.md)
+    - [nix store delete](command-ref/new-cli/nix3-store-delete.md)
+    - [nix store diff-closures](command-ref/new-cli/nix3-store-diff-closures.md)
+    - [nix store dump-path](command-ref/new-cli/nix3-store-dump-path.md)
+    - [nix store gc](command-ref/new-cli/nix3-store-gc.md)
+    - [nix store ls](command-ref/new-cli/nix3-store-ls.md)
+    - [nix store make-content-addressed](command-ref/new-cli/nix3-store-make-content-addressed.md)
+    - [nix store optimise](command-ref/new-cli/nix3-store-optimise.md)
+    - [nix store path-from-hash-part](command-ref/new-cli/nix3-store-path-from-hash-part.md)
+    - [nix store ping](command-ref/new-cli/nix3-store-ping.md)
+    - [nix store prefetch-file](command-ref/new-cli/nix3-store-prefetch-file.md)
+    - [nix store repair](command-ref/new-cli/nix3-store-repair.md)
+    - [nix store sign](command-ref/new-cli/nix3-store-sign.md)
+    - [nix store verify](command-ref/new-cli/nix3-store-verify.md)
+    - [nix upgrade-nix](command-ref/new-cli/nix3-upgrade-nix.md)
+    - [nix why-depends](command-ref/new-cli/nix3-why-depends.md)
  - [Files](command-ref/files.md)
    - [nix.conf](command-ref/conf-file.md)
    - [Profiles](command-ref/files/profiles.md)
@ -109,7 +194,7 @@
  - [CLI guideline](contributing/cli-guideline.md)
  - [C++ style guide](contributing/cxx.md)
 - [Release Notes](release-notes/release-notes.md)
-{{#include ./SUMMARY-rl-next.md}}
+  - [Upcoming release](release-notes/rl-next.md)
  - [Release 2.18 (2023-09-20)](release-notes/rl-2.18.md)
  - [Release 2.17 (2023-07-24)](release-notes/rl-2.17.md)
  - [Release 2.16 (2023-05-31)](release-notes/rl-2.16.md)
--- a/doc/manual/src/command-ref/conf-file-prefix.md
+++ b/doc/manual/src/command-ref/conf-file-prefix.md
@ -17,7 +17,7 @@ By default Nix reads settings from the following places, in that order:

 1. If [`NIX_USER_CONF_FILES`](./env-common.md#env-NIX_USER_CONF_FILES) is set, then each path separated by `:` will be loaded in reverse order.

-   Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS` and [`XDG_CONFIG_HOME`](./env-common.md#env-XDG_CONFIG_HOME).
+   Otherwise it will look for `nix/nix.conf` files in `XDG_CONFIG_DIRS` and `XDG_CONFIG_HOME`.
   If unset, `XDG_CONFIG_DIRS` defaults to `/etc/xdg`, and `XDG_CONFIG_HOME` defaults to `$HOME/.config` as per [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html).

 1. If [`NIX_CONFIG`](./env-common.md#env-NIX_CONFIG) is set, its contents are treated as the contents of a configuration file.
@ -67,3 +67,5 @@ Configuration options can be set on the command line, overriding the values set
 The `extra-` prefix is supported for settings that take a list of items (e.g. `--extra-trusted users alice` or `--option extra-trusted-users alice`).

 # Available settings
+
+{{#include @generated@/command-ref/conf-file.md}}
--- a/doc/manual/src/command-ref/env-common.md
+++ b/doc/manual/src/command-ref/env-common.md
@ -115,9 +115,9 @@ For backwards compatibility, Nix commands will follow the standard only when [`u

 The following environment variables are used to determine locations of various state and configuration files:

- [`XDG_CONFIG_HOME`]{#env-XDG_CONFIG_HOME} (default `~/.config`)
- [`XDG_STATE_HOME`]{#env-XDG_STATE_HOME} (default `~/.local/state`)
- [`XDG_CACHE_HOME`]{#env-XDG_CACHE_HOME} (default `~/.cache`)
+- `XDG_CONFIG_HOME` (default `~/.config`)
+- `XDG_STATE_HOME` (default `~/.local/state`)
+- `XDG_CACHE_HOME` (default `~/.cache`)


 [XDG Base Directory Specification]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
--- a/doc/manual/src/command-ref/meson.build
+++ b/doc/manual/src/command-ref/meson.build
@ -0,0 +1,66 @@
+xp_features_json = custom_target(
+  command : [nix, '__dump-xp-features'],
+  capture : true,
+  output : 'xp-features.json',
+)
+
+experimental_features_shortlist_md = custom_target(
+  command : nix_eval_for_docs + [
+    '--expr',
+    'import @INPUT0@ (builtins.fromJSON (builtins.readFile @INPUT1@))',
+  ],
+  input : [
+    '../../generate-xp-features-shortlist.nix',
+    xp_features_json,
+  ],
+  capture : true,
+  output : 'experimental-features-shortlist.md',
+  env : nix_env_for_docs,
+)
+
+# Intermediate step for manpage generation.
+# This splorks the output of generate-manpage.nix as JSON,
+# which gets written as a directory tree below.
+nix3_cli_files_json = custom_target(
+  command : nix_eval_for_docs_common + [
+    '--json',
+    '--expr',
+    'import @INPUT0@ true (builtins.readFile @INPUT1@)',
+  ],
+  input : [
+    '../../generate-manpage.nix',
+    nix3_cli_json,
+  ],
+  capture : true,
+  output : 'new-cli.json',
+  env : nix_env_for_docs,
+)
+nix3_cli_files = custom_target(
+  command : [
+    python,
+    '@INPUT0@',
+    '-i', '@INPUT1@',
+    '-o', '@OUTPUT@',
+  ],
+  input : [
+    '../../json-to-tree.py',
+    nix3_cli_files_json,
+  ],
+  output : 'new-cli',
+)
+
+conf_file_md = custom_target(
+  command : [
+    nix_eval_for_docs,
+    '--expr',
+    '(import @INPUT0@).showSettings { inlineHTML = true; } (builtins.fromJSON (builtins.readFile @INPUT1@))',
+  ],
+  capture : true,
+  input : [
+    '../../utils.nix',
+    conf_file_json,
+    experimental_features_shortlist_md,
+  ],
+  output : 'conf-file.md',
+  env : nix_env_for_docs,
+)
--- a/doc/manual/src/command-ref/new-cli/nix.md
+++ b/doc/manual/src/command-ref/new-cli/nix.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-build.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-build.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-build.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-bundle.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-bundle.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-bundle.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-copy.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-copy.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-copy.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-daemon.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-daemon.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-daemon.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-derivation-add.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-derivation-add.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-derivation-add.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-derivation-show.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-derivation-show.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-derivation-show.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-derivation.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-derivation.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-derivation.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-develop.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-develop.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-develop.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-doctor.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-doctor.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-doctor.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-edit.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-edit.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-edit.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-eval.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-eval.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-eval.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-flake-archive.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-flake-archive.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-flake-archive.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-flake-check.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-flake-check.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-flake-check.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-flake-clone.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-flake-clone.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-flake-clone.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-flake-info.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-flake-info.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-flake-info.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-flake-init.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-flake-init.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-flake-init.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-flake-lock.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-flake-lock.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-flake-lock.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-flake-metadata.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-flake-metadata.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-flake-metadata.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-flake-new.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-flake-new.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-flake-new.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-flake-prefetch.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-flake-prefetch.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-flake-prefetch.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-flake-show.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-flake-show.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-flake-show.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-flake-update.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-flake-update.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-flake-update.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-flake.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-flake.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-flake.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-fmt.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-fmt.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-fmt.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-hash-file.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-hash-file.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-hash-file.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-hash-path.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-hash-path.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-hash-path.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-hash-to-base16.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-hash-to-base16.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-hash-to-base16.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-hash-to-base32.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-hash-to-base32.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-hash-to-base32.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-hash-to-base64.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-hash-to-base64.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-hash-to-base64.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-hash-to-sri.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-hash-to-sri.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-hash-to-sri.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-hash.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-hash.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-hash.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-help-stores.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-help-stores.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-help-stores.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-help.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-help.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-help.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-key-convert-secret-to-public.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-key-convert-secret-to-public.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-key-convert-secret-to-public.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-key-generate-secret.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-key-generate-secret.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-key-generate-secret.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-key.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-key.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-key.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-log.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-log.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-log.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-nar-cat.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-nar-cat.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-nar-cat.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-nar-dump-path.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-nar-dump-path.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-nar-dump-path.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-nar-ls.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-nar-ls.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-nar-ls.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-nar.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-nar.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-nar.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-path-info.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-path-info.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-path-info.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-print-dev-env.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-print-dev-env.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-print-dev-env.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-profile-diff-closures.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-profile-diff-closures.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-profile-diff-closures.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-profile-history.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-profile-history.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-profile-history.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-profile-install.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-profile-install.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-profile-install.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-profile-list.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-profile-list.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-profile-list.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-profile-remove.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-profile-remove.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-profile-remove.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-profile-rollback.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-profile-rollback.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-profile-rollback.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-profile-upgrade.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-profile-upgrade.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-profile-upgrade.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-profile-wipe-history.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-profile-wipe-history.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-profile-wipe-history.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-profile.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-profile.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-profile.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-realisation-info.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-realisation-info.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-realisation-info.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-realisation.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-realisation.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-realisation.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-registry-add.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-registry-add.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-registry-add.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-registry-list.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-registry-list.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-registry-list.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-registry-pin.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-registry-pin.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-registry-pin.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-registry-remove.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-registry-remove.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-registry-remove.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-registry.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-registry.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-registry.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-repl.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-repl.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-repl.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-run.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-run.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-run.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-search.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-search.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-search.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-shell.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-shell.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-shell.md}}
--- a/doc/manual/src/command-ref/new-cli/nix3-show-config.md
+++ b/doc/manual/src/command-ref/new-cli/nix3-show-config.md
@ -0,0 +1 @@
+{{#include @generated@/command-ref/new-cli/nix3-show-config.md}}
--- a/Show more
+++ b/Show more
				`@ -0,0 +1 @@`
				`{{#include @generated@/command-ref/new-cli/nix.md}}`