Update Antora Reference

.github/workflows/ci.yml

@@ -374,19 +374,9 @@ jobs:
           compiler: clang
           version: 18
 
-      - name: Set environment variables
-        run: |
-          set -x
-          clangpp_path="$(which clang++-18)"
-          clang_path="$(which clang-18)"
-          echo "CXX_COMPILER=$clangpp_path" >> $GITHUB_ENV
-          echo "CXX=$clang_path" >> $GITHUB_ENV
-          echo "C_COMPILER=$clang_path" >> $GITHUB_ENV
-          echo "CC=$clang_path" >> $GITHUB_ENV
-          git config --global --add safe.directory "$(pwd)"
-
       - name: Build Antora Docs
         run: |
+          git config --global --add safe.directory "$(pwd)"
           cd doc
           bash ./build_antora.sh
           

CMakeLists.txt

@@ -34,6 +34,7 @@ set(__ignore__ ${CMAKE_C_COMPILER})
 option(BOOST_URL_BUILD_TESTS "Build boost::url tests even if BUILD_TESTING is OFF" OFF)
 option(BOOST_URL_BUILD_FUZZERS "Build boost::url fuzzers" OFF)
 option(BOOST_URL_BUILD_EXAMPLES "Build boost::url examples" ${BOOST_URL_IS_ROOT})
+option(BOOST_URL_MRDOCS_BUILD "Build the target for MrDocs: see mrdocs.yml" OFF)
 option(BOOST_URL_DISABLE_THREADS "Disable threads" OFF)
 option(BOOST_URL_WARNINGS_AS_ERRORS "Treat warnings as errors" OFF)
 set(BOOST_SRC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/../.." CACHE STRING "Boost source dir to use when running CMake from this directory")
@@ -63,11 +64,13 @@ foreach (BOOST_URL_DEPENDENCY ${BOOST_URL_DEPENDENCIES})
     endif ()
 endforeach ()
 # Conditional dependencies
-if (BUILD_TESTING OR BOOST_URL_BUILD_TESTS)
-    set(BOOST_URL_UNIT_TEST_LIBRARIES container filesystem unordered)
-endif()
-if (BOOST_URL_BUILD_EXAMPLES)
-    set(BOOST_URL_EXAMPLE_LIBRARIES json regex beast)
+if (NOT BOOST_URL_MRDOCS_BUILD)
+    if (BUILD_TESTING OR BOOST_URL_BUILD_TESTS)
+        set(BOOST_URL_UNIT_TEST_LIBRARIES container filesystem unordered)
+    endif()
+    if (BOOST_URL_BUILD_EXAMPLES)
+        set(BOOST_URL_EXAMPLE_LIBRARIES json regex beast)
+    endif()
 endif()
 # Complete dependency list
 set(BOOST_INCLUDE_LIBRARIES ${BOOST_URL_INCLUDE_LIBRARIES} ${BOOST_URL_UNIT_TEST_LIBRARIES} ${BOOST_URL_EXAMPLE_LIBRARIES})
@@ -141,10 +144,20 @@ function(boost_url_setup_properties target)
     target_compile_definitions(${target} PRIVATE BOOST_URL_SOURCE)
     target_compile_options(${target} PUBLIC $<$<CXX_COMPILER_ID:MSVC>:/EHsc>)
 endfunction()
+
+if (BOOST_URL_MRDOCS_BUILD)
+    file(WRITE "${CMAKE_CURRENT_BINARY_DIR}/mrdocs.cpp" "#include <boost/url.hpp>\n")
+    add_library(boost_url_mrdocs "${CMAKE_CURRENT_BINARY_DIR}/mrdocs.cpp")
+    boost_url_setup_properties(boost_url_mrdocs)
+    target_compile_definitions(boost_url_mrdocs PUBLIC BOOST_URL_MRDOCS BOOST_URL_NO_SSE2)
+    return()
+endif()
+
 add_library(boost_url ${BOOST_URL_HEADERS} ${BOOST_URL_SOURCES})
 add_library(Boost::url ALIAS boost_url)
 boost_url_setup_properties(boost_url)
 
+
 #-------------------------------------------------
 #
 # Tests
@@ -165,3 +178,5 @@ endif ()
 if (BOOST_URL_BUILD_EXAMPLES)
     add_subdirectory(example)
 endif ()
+
+

doc/Jamfile

@@ -27,7 +27,16 @@ docca.reference reference.qbk
         <doxygen:param>DISTRIBUTE_GROUP_DOC=YES
         <doxygen:param>MACRO_EXPANSION=YES
         <doxygen:param>EXPAND_ONLY_PREDEF=YES
-        <doxygen:param>EXCLUDE_SYMBOLS=boost::urls::detail::*
+        <doxygen:param>"EXCLUDE_SYMBOLS= \\
+                        boost::urls::detail::* \\
+                        boost::urls::implementation_defined::* \\
+                        boost::urls::see_below::* \\
+                        boost::urls::grammar::detail::* \\
+                        boost::urls::grammar::implementation_defined::* \\
+                        boost::urls::grammar::see_below::* \\
+                        boost::urls::string_token::detail::* \\
+                        boost::urls::string_token::implementation_defined::* \\
+                        boost::urls::string_token::see_below::*"
         <doxygen:param>"PREDEFINED=\\
             BOOST_SYMBOL_VISIBLE \\
             BOOST_URL_DOCS \\

doc/generate-files.mjs

@@ -36,13 +36,74 @@ function findExecutable(executableName) {
         }
         return undefined
     }
-    try {
-        const whichCommand = (process.platform === 'win32') ? 'where' : 'which';
-        const cmd = `${whichCommand} ${executableName}`
-        return execSync(cmd, {encoding: 'utf-8'}).trim()
-    } catch (error) {
-        return undefined
+
+    const isWin = process.platform === 'win32';
+    const pathDirs = process.env.PATH.split(isWin ? ';' : ':');
+    const extensions = isWin ? ['.exe', '.bat', '.cmd'] : [''];
+
+    function isExecutable(filePath) {
+        try {
+            if (!isWin) {
+                fs.accessSync(filePath, fs.constants.X_OK);
+            }
+            return true;
+        } catch (error) {
+            return false;
+        }
+    }
+
+    // Try to find the exact executable first
+    for (const dir of pathDirs) {
+        for (const ext of extensions) {
+            const fullPath = path.join(dir, executableName + ext);
+            if (fs.existsSync(fullPath) && isExecutable(fullPath)) {
+                return fullPath;
+            }
+        }
+    }
+
+    function escapeRegExp(string) {
+        // Escape special characters for use in regex
+        return string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    }
+
+    // If the exact executable is not found, search for versioned executables
+    const versionedExecutables = [];
+    const escapedExecutableName = escapeRegExp(executableName);
+    const versionRegex = new RegExp(`${escapedExecutableName}-(\\d+)$`);
+
+    for (const dir of pathDirs) {
+        try {
+            const files = fs.readdirSync(dir);
+            for (const file of files) {
+                if (!extensions.some(ext => file.endsWith(ext))) {
+                    continue
+                }
+                const fullPath = path.join(dir, file);
+                if (!isExecutable(fullPath)) {
+                    continue
+                }
+                const ext = path.extname(file);
+                const basename = path.basename(file, ext);
+                const match = basename.match(versionRegex);
+                if (match) {
+                    versionedExecutables.push({
+                        path: fullPath,
+                        version: parseInt(match[1], 10)
+                    });
+                }
+            }
+        } catch (error) {
+            // Ignore errors from reading directories
+        }
     }
+
+    if (versionedExecutables.length > 0) {
+        versionedExecutables.sort((a, b) => b.version - a.version);
+        return versionedExecutables[0].path;
+    }
+
+    return undefined;
 }
 
 function mkTmpDir() {
@@ -104,6 +165,9 @@ if (cxxCompiler === undefined) {
     console.error('Could not find a C++ compiler. Please set the CXX_COMPILER environment variable.')
     process.exit(1)
 }
+process.env.CMAKE_CXX_COMPILER = cxxCompiler
+process.env.CXX = cxxCompiler
+
 const cxxCompilerName = path.basename(cxxCompiler).replace(/\.exe$/, '')
 let cCompiler = findExecutable(['clang', 'gcc', 'cl']) || process.env.C_COMPILER || process.env.CC
 if (cCompiler && process.platform === "win32") {
@@ -115,19 +179,15 @@ if (cCompiler === undefined) {
     process.exit(1)
 }
 const cCompilerName = path.basename(cCompiler).replace(/\.exe$/, '')
+process.env.CMAKE_C_COMPILER = cCompiler
+process.env.CC = cCompiler
 
 console.log(`C++ compiler: ${cxxCompilerName} (${cxxCompiler})`)
 console.log(`C compiler: ${cCompilerName} (${cCompiler})`)
 
-/*
-    Extract CMAKE_CXX_IMPLICIT_INCLUDE_DIRECTORIES
- */
-
-
 /*
     Download Boost
  */
-
 function isBoostDir(dir) {
     if (!fs.existsSync(dir)) {
         return false
@@ -193,11 +253,11 @@ if (isBoostDir(cwdParentParent)) {
 
     Install MrDocs with:
         - Linux:
-            wget https://github.com/cppalliance/mrdocs/releases/download/develop-release/MrDocs-1.0.0-Linux.tar.gz
-            sudo tar -xzf MrDocs-1.0.0-Linux.tar.gz -C /usr/local --strip-components=1
+            wget https://github.com/cppalliance/mrdocs/releases/download/develop-release/MrDocs-0.0.1-Linux.tar.gz
+            sudo tar -xzf MrDocs-0.0.1-Linux.tar.gz -C /usr/local --strip-components=1
         - Windows (Powershell):
-            Invoke-WebRequest -Uri 'https://github.com/cppalliance/mrdocs/releases/download/develop-release/MrDocs-1.0.0-win64.7z' -OutFile 'MrDocs-1.0.0-win64.7z'
-            7z x -o"C:\Users\$env:USERNAME\Applications" 'MrDocs-1.0.0-win64.7z'
+            Invoke-WebRequest -Uri 'https://github.com/cppalliance/mrdocs/releases/download/develop-release/MrDocs-0.0.1-win64.7z' -OutFile 'MrDocs-0.0.1-win64.7z'
+            7z x -o"C:\Users\$env:USERNAME\Applications" 'MrDocs-0.0.1-win64.7z'
             ( Adapt the destination path as needed )
 
  */
@@ -215,11 +275,21 @@ if (!mrDocsExec) {
     })
     const releasesInfo = JSON.parse(releasesResponse.getBody('utf-8'))
     console.log(`Found ${releasesInfo.length} MrDocs releases`)
-    const latestRelease = releasesInfo[0]
-    console.log(`Latest release: ${latestRelease['tag_name']}`)
-    const latestAssets = latestRelease['assets'].map(asset => asset['browser_download_url'])
-    console.log(`Latest assets: ${latestAssets}`)
-    const downloadUrl = process.platform === "win32" ? latestAssets.find(asset => asset.endsWith('win64.7z')) : latestAssets.find(asset => asset.endsWith('Linux.tar.gz'))
+    let downloadUrl = undefined
+    for (const latestRelease of releasesInfo) {
+        console.log(`Latest release: ${latestRelease['tag_name']}`)
+        const latestAssets = latestRelease['assets'].map(asset => asset['browser_download_url'])
+        console.log(`Latest assets: ${latestAssets}`)
+        downloadUrl = process.platform === "win32" ? latestAssets.find(asset => asset.endsWith('win64.7z')) : latestAssets.find(asset => asset.endsWith('Linux.tar.gz'))
+        if (downloadUrl) {
+            break
+        }
+        console.warn(`Could not find MrDocs binaries in ${latestRelease['tag_name']} release for ${process.platform}`)
+    }
+    if (!downloadUrl) {
+        console.error(`Could not find MrDocs binaries for ${process.platform}`)
+        process.exit(1)
+    }
     const downloadFilename = path.basename(downloadUrl)
     console.log(`Downloading ${downloadUrl} to ${path.join(tempDir, downloadFilename)}...`)
     downloadAndDecompress(
@@ -254,13 +324,17 @@ let mrDocsExitCode = 0
 try {
     const mrDocsOutput = execSync(mrDocsCmd)
     console.log(mrDocsOutput.toString())
+    console.log(`Generated documentation at ${mrDocsOutputDir}`)
 } catch (error) {
+    console.error('Failed to run MrDocs')
     console.error(error.stdout.toString())
     mrDocsExitCode = error.status
 }
 if (tempDir) {
     console.log(`Deleting temporary directory ${tempDir}`)
     execSync(`rm -rf ${tempDir}`)
 }
-console.log(`Generated documentation at ${mrDocsOutputDir}`)
+if (mrDocsExitCode !== 0) {
+    console.log(`Exiting with code ${mrDocsExitCode}`)
+}
 process.exit(mrDocsExitCode)

doc/lib/boost-link-inline-macro.js

@@ -70,9 +70,10 @@ module.exports = function (registry) {
     registry.inlineMacro('boost', function () {
         const self = this;
         self.process(function (parent, target, attr) {
-            let title = attr.$positional ? attr.$positional[0] : `Boost.${toPascalCase(target)}`;
-            let is_tool = ['auto_index', 'bcp', 'boostbook', 'boostdep', 'boost_install', 'build', 'check_build', 'cmake', 'docca', 'inspect', 'litre', 'quickbook'].includes(toSnakeCase(target));
-            let text = `https://www.boost.org/${is_tool ? 'tools' : 'libs'}/${toSnakeCase(target)}[${title}]`;
+            const title = attr.$positional ? attr.$positional[0] : `Boost.${toPascalCase(target)}`;
+            const boost_tools = ['auto_index', 'bcp', 'boostbook', 'boostdep', 'boost_install', 'build', 'check_build', 'cmake', 'docca', 'inspect', 'litre', 'quickbook'];
+            const is_tool = boost_tools.includes(toSnakeCase(target));
+            const text = `https://www.boost.org/${is_tool ? 'tools' : 'libs'}/${toSnakeCase(target)}[${title}]`;
             return self.createInline(parent, 'quoted', text);
         });
     });

doc/lib/cpp.js

@@ -18,7 +18,7 @@ const DOMParser = require('xmldom').DOMParser;
     Default tag files come from the cpp_tags directory.
     We still need to implement other strategies and sources for tag files.
 
-    To include cppreference tags you can get them from
+    To generate cppreference tags, you can get them from
     https://en.cppreference.com/w/Cppreference:Archives or generate a
     more recent version using the following commands:
 
@@ -79,6 +79,15 @@ module.exports = function (registry) {
         throw new Error('registry must be defined');
     }
 
+    // Try to convert this into an antora extension so that it can receive
+    // parameters just like mermaid can receive parameters:
+    // https://github.com/snt/antora-mermaid-extension/blob/master/lib/extension.js
+    //
+    // From these parameters, we can already determine other tag files to load
+    // according to the component.
+    // Here's how the components set these tagfiles:
+    // https://gitlab.com/antora/antora-collector-extension/-/tree/main/packages/collector-extension?ref_type=heads
+
     /**
      * Processes the "cpp" inline macro.
      * If the "title" attribute is specified, it is used as the link text.

doc/modules/ROOT/nav.adoc

@@ -14,10 +14,6 @@
 ** xref:grammar/combinators.adoc[]
 ** xref:grammar/range.adoc[]
 ** xref:grammar/rfc3986.adoc[]
-* Concepts
-** xref:concepts/CharSet.adoc[]
-** xref:concepts/Rule.adoc[]
-** xref:concepts/StringToken.adoc[]
 * Examples
 ** xref:examples/qrcode.adoc[]
 ** xref:examples/finicky.adoc[]
@@ -26,5 +22,10 @@
 ** xref:examples/file-router.adoc[]
 ** xref:examples/router.adoc[]
 ** xref:examples/sanitize.adoc[]
-* xref:reference:boost/urls.adoc[Reference]
-* xref:HelpCard.adoc[]
+* Reference
+** xref:reference.adoc[Index]
+** Concepts
+*** xref:concepts/CharSet.adoc[]
+*** xref:concepts/Rule.adoc[]
+*** xref:concepts/StringToken.adoc[]
+** xref:HelpCard.adoc[]