doc: make manpage URLs configurable based on release type

Add configurable documentation URLs that change based on whether this is
an official release or development build:

- Nix builds:
  - Development (officialRelease = false): Use /latest/ URLs
  - Official releases (officialRelease = true): Use versioned URLs with
    MAJOR.MINOR only (e.g., /2.33/ instead of /2.33.0/)
- Plain meson builds: Default to versioned URLs (official-release = true)

Changes:
- Add --doc-url parameter to expand-includes.py
- Add meson option 'official-release' (defaults to true for Meson builds)
- Compute doc_url in meson.build based on version and official-release
- Forward Nix officialRelease variable to Meson in package.nix
- Update render-manpage.sh to pass doc-url parameter

This allows distros (Fedora, etc.) to have stable versioned URLs by default,
while Nix development builds point to /latest/ for up-to-date documentation.

doc/manual/expand-includes.py

@@ -91,7 +91,7 @@ def expand_includes(
     return ''.join(lines)
 
 
-def resolve_docroot(content: str, current_file: Path, source_root: Path) -> str:
+def resolve_docroot(content: str, current_file: Path, source_root: Path, docroot_url: str) -> str:
     """
     Replace @docroot@ with nix.dev URL and convert .md to .html.
 
@@ -99,10 +99,6 @@ def resolve_docroot(content: str, current_file: Path, source_root: Path) -> str:
     manpages are viewed standalone. lowdown will display these as proper
     references in the manpage output.
     """
-    # Use the latest nix.dev documentation URL
-    # This matches what users would actually want to reference from a manpage
-    docroot_url = "https://nix.dev/manual/nix/latest"
-
     # Replace @docroot@ with the base URL
     content = content.replace("@docroot@", docroot_url)
 
@@ -126,6 +122,7 @@ def process_file(
     input_file: Path,
     source_root: Path,
     generated_root: Path | None,
+    docroot_url: str,
 ) -> str:
     """Process a single markdown file."""
     content = input_file.read_text()
@@ -134,7 +131,7 @@ def process_file(
     content = expand_includes(content, input_file, source_root, generated_root)
 
     # Resolve @docroot@ references
-    content = resolve_docroot(content, input_file, source_root)
+    content = resolve_docroot(content, input_file, source_root, docroot_url)
 
     # Resolve @_at_ escapes
     content = resolve_at_escapes(content)
@@ -181,6 +178,12 @@ Examples:
         type=Path,
         help="Output file (default: stdout)",
     )
+    parser.add_argument(
+        "-u", "--doc-url",
+        type=str,
+        default="https://nix.dev/manual/nix/latest",
+        help="Base URL for documentation links (default: https://nix.dev/manual/nix/latest)",
+    )
 
     args = parser.parse_args()
 
@@ -199,7 +202,7 @@ Examples:
 
     try:
         # Process the file
-        output = process_file(args.input_file, args.source_root, args.generated_root)
+        output = process_file(args.input_file, args.source_root, args.generated_root, args.doc_url)
 
         # Write output
         if args.output:

doc/manual/meson.build

@@ -5,6 +5,20 @@ project(
   license : 'LGPL-2.1-or-later',
 )
 
+# Compute documentation URL based on version and release type
+version = meson.project_version()
+official_release = get_option('official-release')
+
+if official_release
+  # For official releases, use versioned URL (dropping patch version)
+  version_parts = version.split('.')
+  major_minor = '@0@.@1@'.format(version_parts[0], version_parts[1])
+  doc_url = 'https://nix.dev/manual/nix/@0@'.format(major_minor)
+else
+  # For development builds, use /latest
+  doc_url = 'https://nix.dev/manual/nix/latest'
+endif
+
 nix = find_program('nix', native : true)
 
 mdbook = find_program('mdbook', native : true)
@@ -215,6 +229,7 @@ foreach command : nix_nested_manpages
         section,
         meson.current_source_dir() / 'source',
         meson.current_build_dir() / 'source',
+        doc_url,
         meson.current_source_dir() / 'source/command-ref' / command[0] / (page + '.md'),
         '@OUTPUT0@',
       ],
@@ -334,6 +349,7 @@ foreach page : nix3_manpages
       section,
       meson.current_source_dir() / 'source',
       meson.current_build_dir() / 'source',
+      doc_url,
       meson.current_build_dir() / 'source/command-ref/new-cli/@0@.md'.format(
         page,
       ),
@@ -390,6 +406,7 @@ foreach entry : nix_manpages
       section,
       meson.current_source_dir() / 'source',
       meson.current_build_dir() / 'source',
+      doc_url,
       input_file,
       '@OUTPUT@',
     ],

doc/manual/meson.options

@@ -0,0 +1,6 @@
+option(
+  'official-release',
+  type : 'boolean',
+  value : true,
+  description : 'Whether this is an official release build (affects documentation URLs)',
+)

doc/manual/package.nix

@@ -81,6 +81,10 @@ mkMesonDerivation (finalAttrs: {
     changelog-d
   ];
 
+  mesonFlags = [
+    (lib.mesonBool "official-release" officialRelease)
+  ];
+
   preConfigure = ''
     chmod u+w ./.version
     echo ${finalAttrs.version} > ./.version

doc/manual/render-manpage.sh

@@ -15,20 +15,22 @@ if [ "$1" = --out-no-smarty ]; then
     shift
 fi
 
-[ "$#" = 6 ] || {
+[ "$#" = 7 ] || {
     cat >&2 <<EOF
-Usage: $0 [--out-no-smarty] <title> <section> <source-root> <generated-root> <infile> <outfile>
+Usage: $0 [--out-no-smarty] <title> <section> <source-root> <generated-root> <doc-url> <infile> <outfile>
 
 Arguments:
   title           - Manpage title (e.g., "nix-env --install")
   section         - Manpage section number (1, 5, 8, etc.)
   source-root     - Root directory of markdown sources
   generated-root  - Root directory of generated markdown files
+  doc-url         - Base URL for documentation links
   infile          - Input markdown file (relative to build directory)
   outfile         - Output manpage file
 
 Examples:
   $0 "nix-store --query" 1 doc/manual/source build/doc/manual/source \\
+     https://nix.dev/manual/nix/latest \\
      build/doc/manual/source/command-ref/nix-store/query.md nix-store-query.1
 EOF
     exit 1
@@ -38,8 +40,9 @@ title="$1"
 section="$2"
 source_root="$3"
 generated_root="$4"
-infile="$5"
-outfile="$6"
+doc_url="$5"
+infile="$6"
+outfile="$7"
 
 # Expand includes and pipe to lowdown
 (
@@ -47,5 +50,6 @@ outfile="$6"
     python3 "$script_dir/expand-includes.py" \
         --source-root "$source_root" \
         --generated-root "$generated_root" \
+        --doc-url "$doc_url" \
         "$infile"
 ) | lowdown -sT man --nroff-nolinks $lowdown_args -M section="$section" -o "$outfile"