This is basically the second commit in #377170 on steroids, candidate for #346453

Candidates were made using

#!/usr/bin/env nix-shell
#!nix-shell --pure -i bash -p ripgrep sd jq git

git restore .

# convert foobar(1) manpage references to {manpage}`foobar(1)`
while read fname; do
    echo $fname

    # list all found manpage references
    # rg '[a-zA-Z.-]+\([0-9]+\)' "$fname" --json | jq '.data.submatches[]?.match.text' -r | sort -u

    (set -x
        sd ' `([a-zA-Z.-]+\([0-9]+\))`' ' {manpage}`$1`' "$fname"
        sd '\(`([a-zA-Z.-]+\([0-9]+\))`\)' '({manpage}`$1`)' "$fname"
        sd '\b([a-zA-Z.-]+\([0-9]+\))' '{manpage}`$1`' "$fname"
        # undo double manpage tagging
        sd '\{manpage\}`\{manpage\}`([a-zA-Z.-]+\([0-9]+\))``' '{manpage}`$1`' "$fname"
    )

done < <(rg '[a-zA-Z.-]+\([0-9]+\)' -tnix nixos/ -l)

git restore nixos/tests

and picked with GIT_DIFF_OPTS='--unified=20' git add -p for improved context.

The second commit was made using

jq <doc/manpage-urls.json 'to_entries[] | "rg -F \"[\(.key)](\(.value))\" nixos/ -l | xe sd -F \"[\(.key)](\(.value))\" \"{manpage}`\(.key)`\""' -r  | tr \" \' | bash -x

The third commit and onward are manual cleanups and fixes

The next stage is to either (a) expand doc/manpage-urls.json with more urls or (b) add https://linux.die.net/man/ as a fallback, or (c) both. (see #208762.)

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 25.05 Release Notes (or backporting 24.11 and 25.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

Add a 👍 reaction to pull requests you find important.