Build and package all language manuals with offline HTML links

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

7 files changed, 68 insertions, 26 deletions

diff --git a/AGENTS/ARCH.md b/AGENTS/ARCH.md
index 25faaa5..30c4a3b 100644
--- a/AGENTS/ARCH.md
+++ b/AGENTS/ARCH.md
@@ -102,7 +102,7 @@ do not require Pandoc; `doc`, installation and release packaging do. The modular
 `cmake/Manual.cmake` target defers Pandoc discovery until manual generation, prefers
 the extracted executable, and sets its local runtime/data paths as needed. System
 Pandoc remains the fallback.
-`make -C build release` packages the executable, manual, installer and license
+`make -C build release` packages the executable, all manuals, installer and license
 as `build/cpsc-VERSION-SYSTEM-ARCH.tar.xz`, retaining the configured execution mode.
 `cmake/Release.cmake` reads HEAD at packaging time; VERSION is the commit's UTC
 timestamp (`yyyy-mm-dd-hh-mm-ss`) followed by its short ID. Git is only required
@@ -116,7 +116,11 @@ per-user Start Menu help shortcut. `-SourceDir` selects the artifact directory;
 Windows PowerShell 5.1; its Windows actions have only been reviewed statically.
 The `doc` target uses CMake's `WIN32` target-platform detection: Windows generates
 standalone HTML with inline styles at `build/doc/cpsc.html`; other platforms
-generate `build/doc/cpsc.1`. Both render the same `doc/cpsc.1.md` using Pandoc.
+generate `build/doc/cpsc.1`. The section 1 source is `doc/cpsc.1.md`; section 7 sources are
+`doc/language/cpsc-*.7.md`. `doc` builds every page, preserving the language
+subdirectory, as `.7` on Unix or `.html` on Windows. Sources are discovered with
+CONFIGURE_DEPENDS; per-page commands regenerate only changed pages.
+`cmake/ManualLinks.lua` renders cross-references as man names or local HTML links.
 Windows `mingw32-make -C build install` builds the HTML manual and invokes
 `install.ps1` through Windows PowerShell with the build directory and
 `CMAKE_INSTALL_PREFIX`. The default Windows prefix is the per-user Programs
@@ -125,7 +129,7 @@ The release target explicitly passes the configured Windows flag to
 `cmake/Release.cmake`, since a standalone CMake script otherwise describes the
 host platform. Windows packages `cpsc.exe`, `doc/cpsc.html`, `install.ps1` and
 `LICENSE` as `build/cpsc-VERSION-Windows-ARCH.zip` using CMake's default Deflate
-compression. Unix retains `.tar.xz`, the POSIX installer and the man page.
+compression. Unix retains `.tar.xz`, the POSIX installer and the man pages.
 Linux smoke tests can configure an isolated build with `-DWIN32=TRUE` to exercise
 HTML/ZIP packaging; the resulting renamed Linux executable is only a test fixture,
 not a usable Windows release.
diff --git a/cmake/GenerateManual.cmake.in b/cmake/GenerateManual.cmake.in
index b6bf853..8874c82 100644
--- a/cmake/GenerateManual.cmake.in
+++ b/cmake/GenerateManual.cmake.in
@@ -6,7 +6,9 @@ message(STATUS "Using Pandoc: ${pandoc}")
 
 set(arguments --standalone --from=markdown --to=@cpsc_manual_format@)
 if("@cpsc_manual_format@" STREQUAL "html5")
-    list(APPEND arguments --metadata "title=cpsc manual")
+    get_filename_component(title "${CPSC_MANUAL_SOURCE}" NAME)
+    string(REGEX REPLACE "\\.[17]\\.md$" "" title "${title}")
+    list(APPEND arguments --metadata "title=${title}")
 endif()
 if(pandoc_LOCAL AND IS_DIRECTORY "@CPSC_DEPS_ROOT@/usr/share/pandoc/data")
     list(APPEND arguments "--data-dir=@CPSC_DEPS_ROOT@/usr/share/pandoc/data")
@@ -22,12 +24,14 @@ elseif(pandoc_LOCAL AND UNIX AND NOT APPLE)
     set(ENV{LD_LIBRARY_PATH} "${libraries}")
 endif()
 
-file(MAKE_DIRECTORY "@CMAKE_CURRENT_BINARY_DIR@/doc")
+get_filename_component(output_dir "${CPSC_MANUAL_OUTPUT}" DIRECTORY)
+file(MAKE_DIRECTORY "${output_dir}")
+list(APPEND arguments "--lua-filter=@CMAKE_CURRENT_SOURCE_DIR@/cmake/ManualLinks.lua")
 execute_process(
-    COMMAND "${pandoc}" ${arguments} "@CMAKE_CURRENT_SOURCE_DIR@/doc/cpsc.1.md"
-        --output "@cpsc_manual_file@"
+    COMMAND "${pandoc}" ${arguments} "${CPSC_MANUAL_SOURCE}"
+        --output "${CPSC_MANUAL_OUTPUT}"
     RESULT_VARIABLE result
 )
 if(NOT result EQUAL 0)
-    message(FATAL_ERROR "Pandoc failed to generate @cpsc_manual_file@ (${result})")
+    message(FATAL_ERROR "Pandoc failed to generate ${CPSC_MANUAL_OUTPUT} (${result})")
 endif()
diff --git a/cmake/Manual.cmake b/cmake/Manual.cmake
index 3c20f12..689c91e 100644
--- a/cmake/Manual.cmake
+++ b/cmake/Manual.cmake
@@ -1,24 +1,40 @@
 if(WIN32)
-    set(cpsc_manual_file "${CMAKE_CURRENT_BINARY_DIR}/doc/cpsc.html")
     set(cpsc_manual_format html5)
 else()
-    set(cpsc_manual_file "${CMAKE_CURRENT_BINARY_DIR}/doc/cpsc.1")
     set(cpsc_manual_format man)
 endif()
 
 configure_file("${CMAKE_CURRENT_LIST_DIR}/GenerateManual.cmake.in"
     "${CMAKE_CURRENT_BINARY_DIR}/GenerateManual.cmake" @ONLY)
-set(cpsc_manual_dependencies "${CMAKE_CURRENT_SOURCE_DIR}/doc/cpsc.1.md"
+file(GLOB cpsc_language_sources CONFIGURE_DEPENDS
+    "${CMAKE_CURRENT_SOURCE_DIR}/doc/language/cpsc-*.7.md")
+set(cpsc_manual_sources "${CMAKE_CURRENT_SOURCE_DIR}/doc/cpsc.1.md"
+    ${cpsc_language_sources})
+set(cpsc_manual_dependencies
     "${CMAKE_CURRENT_BINARY_DIR}/GenerateManual.cmake"
+    "${CMAKE_CURRENT_SOURCE_DIR}/cmake/ManualLinks.lua"
     "${CPSC_DEPS_MODULE_DIR}/FindDependency.cmake")
 if(EXISTS "${CPSC_DEPS_DIR}/packages.sha256")
     list(APPEND cpsc_manual_dependencies "${CPSC_DEPS_DIR}/packages.sha256")
 endif()
-add_custom_command(
-    OUTPUT "${cpsc_manual_file}"
-    COMMAND "${CMAKE_COMMAND}" -P "${CMAKE_CURRENT_BINARY_DIR}/GenerateManual.cmake"
-    DEPENDS ${cpsc_manual_dependencies}
-    COMMENT "Generating cpsc manual (${cpsc_manual_format})"
-    VERBATIM
-)
-add_custom_target(doc DEPENDS "${cpsc_manual_file}")
+set(cpsc_manual_outputs)
+foreach(source IN LISTS cpsc_manual_sources)
+    file(RELATIVE_PATH relative "${CMAKE_CURRENT_SOURCE_DIR}/doc" "${source}")
+    if(WIN32)
+        string(REGEX REPLACE "\\.[17]\\.md$" ".html" relative "${relative}")
+    else()
+        string(REGEX REPLACE "\\.md$" "" relative "${relative}")
+    endif()
+    set(output "${CMAKE_CURRENT_BINARY_DIR}/doc/${relative}")
+    add_custom_command(
+        OUTPUT "${output}"
+        COMMAND "${CMAKE_COMMAND}" "-DCPSC_MANUAL_SOURCE=${source}"
+            "-DCPSC_MANUAL_OUTPUT=${output}"
+            -P "${CMAKE_CURRENT_BINARY_DIR}/GenerateManual.cmake"
+        DEPENDS "${source}" ${cpsc_manual_dependencies}
+        COMMENT "Generating ${relative} (${cpsc_manual_format})"
+        VERBATIM
+    )
+    list(APPEND cpsc_manual_outputs "${output}")
+endforeach()
+add_custom_target(doc DEPENDS ${cpsc_manual_outputs})
diff --git a/cmake/ManualLinks.lua b/cmake/ManualLinks.lua
new file mode 100644
index 0000000..0fddef5
--- /dev/null
+++ b/cmake/ManualLinks.lua
@@ -0,0 +1,8 @@
+-- Markdown sources share links; render local HTML links or man-page names.
+function Link(link)
+    if FORMAT == 'man' then
+        return link.content
+    end
+    link.target = link.target:gsub('%.[17]%.md$', '.html')
+    return link
+end
diff --git a/cmake/Release.cmake b/cmake/Release.cmake
index 49dee98..59a1d79 100644
--- a/cmake/Release.cmake
+++ b/cmake/Release.cmake
@@ -21,6 +21,7 @@ if(CPSC_WINDOWS)
     set(cpsc_binary_name cpsc.exe)
     set(cpsc_installer install.ps1)
     set(cpsc_manual cpsc.html)
+    set(cpsc_language_pattern "${CPSC_BINARY_DIR}/doc/language/cpsc-*.html")
     set(cpsc_tar_flags cf)
     set(cpsc_archive_format zip)
 else()
@@ -28,6 +29,7 @@ else()
     set(cpsc_binary_name cpsc)
     set(cpsc_installer install.sh)
     set(cpsc_manual cpsc.1)
+    set(cpsc_language_pattern "${CPSC_BINARY_DIR}/doc/language/cpsc-*.7")
     set(cpsc_tar_flags cJf)
     set(cpsc_archive_format gnutar)
 endif()
@@ -38,6 +40,11 @@ configure_file("${CPSC_EXECUTABLE}" "${cpsc_package_dir}/${cpsc_binary_name}" CO
 file(COPY "${CPSC_SOURCE_DIR}/${cpsc_installer}" "${CPSC_SOURCE_DIR}/LICENSE"
     DESTINATION "${cpsc_package_dir}")
 file(COPY "${CPSC_BINARY_DIR}/doc/${cpsc_manual}" DESTINATION "${cpsc_package_dir}/doc")
+file(GLOB cpsc_language_manuals "${cpsc_language_pattern}")
+if(NOT cpsc_language_manuals)
+    message(FATAL_ERROR "Language manuals are missing; build the doc target first")
+endif()
+file(COPY ${cpsc_language_manuals} DESTINATION "${cpsc_package_dir}/doc/language")
 execute_process(
     COMMAND "${CMAKE_COMMAND}" -E tar "${cpsc_tar_flags}" "${cpsc_archive}"
         "--format=${cpsc_archive_format}" "${cpsc_package_name}"
diff --git a/doc/build.md b/doc/build.md
index ce87eb6..ee335fd 100644
--- a/doc/build.md
+++ b/doc/build.md
@@ -185,7 +185,8 @@ export PATH="$PWD/build/deps/root/opt/llvm@18/bin:$PATH"
 
 ## Manual
 
-The quick reference is in [cpsc.1.md](cpsc.1.md). Pandoc is required only for the
+The command-line reference is in [cpsc.1.md](cpsc.1.md); the
+[language overview](language/cpsc-language-overview.7.md) links to the syntax manuals. Pandoc is required only for the
 `doc`, installation and release targets. Recommended local downloads follow;
 an existing system Pandoc works with the same manual-generation command.
 
@@ -224,11 +225,13 @@ cmake --build build --target doc
 ```
 
 CMake selects local Pandoc first, sets its local runtime/data paths as needed,
-and falls back to Pandoc in the system PATH. The output is `build/doc/cpsc.1` on
-Unix and `build/doc/cpsc.html` on Windows. It is regenerated when the source or
-downloaded packages change.
+and falls back to Pandoc in the system PATH. The outputs are `build/doc/cpsc.1` and `build/doc/language/*.7` on Unix,
+or `build/doc/cpsc.html` and `build/doc/language/*.html` on Windows. Each page
+is regenerated when its source, rendering configuration or downloaded packages
+change. New language pages are discovered automatically during the build.
 
-On Unix, open it with `man ./build/doc/cpsc.1`. On Windows, open the standalone,
+On Unix, open the command manual with `man ./build/doc/cpsc.1`, or a syntax
+page with `man ./build/doc/language/cpsc-keyword-if.7`. On Windows, open the standalone,
 offline HTML from PowerShell:
 
 ```powershell
diff --git a/doc/install.md b/doc/install.md
index 8101684..ef4c3f6 100644
--- a/doc/install.md
+++ b/doc/install.md
@@ -43,7 +43,7 @@ make -C build release
 The output is `build/cpsc-VERSION-SYSTEM-ARCH.tar.xz`. `VERSION` uses HEAD's commit
 time in UTC followed by its short ID: `yyyy-mm-dd-hh-mm-ss-commit`.
 The version is read each time packaging runs. The package uses the current build's
-execution mode and contains `cpsc`, `doc/cpsc.1`, `install.sh` and `LICENSE`.
+execution mode and contains `cpsc`, `doc/cpsc.1`, `doc/language/*.7`, `install.sh` and `LICENSE`.
 Packaging builds the compiler and manual automatically; it requires Git and Pandoc.
 Use `EMBEDDED` when recipients should not need LLVM or `lli` at run time.
 
@@ -96,7 +96,7 @@ cmake --build build --target release
 This is equivalent to `mingw32-make -C build release`. Windows produces
 `build/cpsc-VERSION-Windows-ARCH.zip`, using the same UTC commit version as Unix
 and retaining the configured execution mode. The ZIP contains `cpsc.exe`,
-`doc/cpsc.html`, `install.ps1` and `LICENSE` under one top-level directory.
+`doc/cpsc.html`, `doc/language/*.html`, `install.ps1` and `LICENSE` under one top-level directory.
 It uses CMake's default Deflate compression and needs no additional compression
 tool; packaging requires Git and Pandoc, just as on Unix.