docs: cpp Antora extension

doc/antora.yml

@@ -8,8 +8,8 @@
 #
 
 name: url
-title: Boost.URL
 version: ~
+title: Boost.URL
 start_page: index.adoc
 asciidoc:
   attributes:

doc/lib/cpp.js

@@ -0,0 +1,109 @@
+/*
+    Copyright (c) 2023 Alan de Freitas (alandefreitas@gmail.com)
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+    Official repository: https://github.com/boostorg/site-docs
+*/
+
+const path = require('path');
+const fs = require('fs');
+const xpath = require('xpath');
+const DOMParser = require('xmldom').DOMParser;
+
+/*
+    Load tag files
+
+    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
+    https://en.cppreference.com/w/Cppreference:Archives or generate a
+    more recent version using the following commands:
+
+    ```
+    git clone https://github.com/PeterFeicht/cppreference-doc
+    cd cppreference-doc
+    make source
+    make doc_doxygen
+    ```
+
+    The result will be in ./output.
+ */
+let tagDocs = {}
+// Read all files in __dirname
+const defaultTagsDir = path.join(__dirname, 'cpp_tags');
+fs.readdirSync(defaultTagsDir).forEach(file => {
+    if (file.endsWith('.tag.xml')) {
+        const tagFile = path.join(defaultTagsDir, file);
+        const xml = fs.readFileSync(tagFile, 'utf8');
+        tagDocs[file.replace('.tag.xml', '')] = new DOMParser().parseFromString(xml, 'text/xml');
+    }
+})
+
+/**
+ * Gets the URL for a symbol.
+ *
+ * @param doc - The XML document containing the symbols.
+ * @param symbolName - The name of the symbol.
+ * @returns {undefined|string} The URL for the symbol, or undefined if the symbol is not found.
+ */
+function getSymbolLink(doc, symbolName) {
+    const select = xpath.useNamespaces({'ns': 'http://www.w3.org/1999/xhtml'})
+    let result = select(`//compound[name="${symbolName}"]`, doc)
+    if (result.length > 0) {
+        const symbolNode = result[0]
+        const symbolName = symbolNode.getElementsByTagName('name')[0].textContent
+        const symbolFilename = symbolNode.getElementsByTagName('filename')[0].textContent
+        return `https://en.cppreference.com/w/${symbolFilename}[${symbolName},window="_blank"]`
+    }
+    return undefined
+}
+
+/**
+ * Registers an inline macro named "cpp" with the given Asciidoctor registry.
+ * This macro creates a link to the corresponding Boost C++ symbol using the
+ * provided Doxygen tag files.
+ *
+ * @param {Object} registry - The Asciidoctor registry to register the macro with.
+ * @throws {Error} If registry is not defined.
+ * @example
+ * const asciidoctor = require('asciidoctor');
+ * const registry = asciidoctor.Extensions.create();
+ * registerBoostMacro(registry);
+ */
+module.exports = function (registry) {
+    // Make sure registry is defined
+    if (!registry) {
+        throw new Error('registry must be defined');
+    }
+
+    /**
+     * Processes the "cpp" inline macro.
+     * If the "title" attribute is specified, it is used as the link text.
+     * Otherwise, the monospace code target is used as the link text.
+     * The link URL is constructed based on the snake_case version of the target.
+     *
+     * @param {Object} parent - The parent node of the inline macro.
+     * @param {string} target - The target of the inline macro.
+     * @param {Object} attr - The attributes of the inline macro.
+     * @returns {Object} An inline node representing the link.
+     */
+    registry.inlineMacro('cpp', function () {
+        const self = this;
+        self.process(function (parent, target, attr) {
+            for (const [tag, doc] of Object.entries(tagDocs)) {
+                const link = getSymbolLink(doc, target)
+                if (link) {
+                    return self.createInline(parent, 'quoted', link, {type: 'monospaced'})
+                }
+            }
+            if (['bool', 'char', 'char8_t', 'char16_t', 'char32_t', 'wchar_t', 'int', 'signed', 'unsigned', 'short', 'long', 'float', 'true', 'false', 'double', 'void'].includes(target)) {
+                return self.createInline(parent, 'quoted', `https://en.cppreference.com/w/cpp/language/types[${target},window=_blank]`, {type: 'monospaced'})
+            }
+            return self.createInline(parent, 'quoted', target, {type: 'monospaced'})
+        })
+    })
+}
+

doc/local-playbook.yml

@@ -36,4 +36,5 @@ antora:
 asciidoc:
   extensions:
     - ./lib/boost-link-inline-macro.js
+    - ./lib/cpp.js
     - '@asciidoctor/tabs'

doc/modules/ROOT/pages/concepts/CharSet.adoc

@@ -43,7 +43,7 @@ In this table:
 // Row 1, Column 1
 |`t(c)`
 // Row 1, Column 2
-|`bool`
+|cpp:bool[]
 // Row 1, Column 3
 |This function returns `true` if `c` is a member of
 the character set, otherwise it returns `false`.

doc/modules/ROOT/pages/concepts/StringToken.adoc

@@ -19,7 +19,7 @@ In this table:
 
 * `T` is a type meeting the requirements of __StringToken__
 * `t` is an rvalue reference of type T
-* `n` is a value of type `std::size_t`
+* `n` is a value of type cpp:std::size_t[]
 
 [cols="1,1,3"]
 |===
@@ -28,7 +28,7 @@ In this table:
 
 // Row 1, Column 1
 |
-`std::derived_from<T,string_token::arg>`
+cpp:std::derived_from<T,string_token::arg>[]
 
 // Row 1, Column 2
 |`true`
@@ -123,7 +123,7 @@ void algorithm_impl( string_token::arg& token )
 } // detail
 
 // public interface is a function template,
-// defaulting to return `std::string`.
+// defaulting to return cpp:std::string[].
 
 template< class StringToken = string_token::return_string >
 auto

doc/modules/ROOT/pages/grammar/combinators.adoc

@@ -33,7 +33,7 @@ The folllowing defines a sequence using some character literals and two decimal
 include::example$unit/doc_grammar.cpp[tag=code_grammar_3_1,indent=0]
 ----
 
-This rule has a value type of `std::tuple`, whose types correspond to the value type of each rule specified upon construction.
+This rule has a value type of cpp:std::tuple[], whose types correspond to the value type of each rule specified upon construction.
 The decimal octets are represented by the `dec_octet_rule` which stores its result in an `unsigned char`:
 
 [source,cpp]
@@ -41,7 +41,7 @@ The decimal octets are represented by the `dec_octet_rule` which stores its resu
 include::example$unit/doc_grammar.cpp[tag=code_grammar_3_2,indent=0]
 ----
 
-To extract elements from `std::tuple` the function https://en.cppreference.com/w/cpp/utility/tuple/get[`std::get`,window=blank_]
+To extract elements from cpp:std::tuple[] the function cpp:std::get[]
 must be used.
 In this case, we don't care to know the value for the matching character literals.
 The `tuple_rule` discards match results whose value type is `void`.
@@ -53,7 +53,7 @@ compound rule to convert a matching value type to `void`, and reformulate our ru
 include::example$unit/doc_grammar.cpp[tag=code_grammar_3_3,indent=0]
 ----
 
-When all but one of the value types is `void`, the `std::tuple` is elided and the remaining value type is promoted to the result of the match:
+When all but one of the value types is `void`, the cpp:std::tuple[] is elided and the remaining value type is promoted to the result of the match:
 
 [source,cpp]
 ----

doc/modules/ROOT/pages/grammar/index.adoc

@@ -27,7 +27,7 @@ facilities for processing low-ASCII character strings, and makes
 public the interface to useful rules found in rfc3986. The design
 goals of these facilities are:
 
-* No use of `std::locale` or `std::char_traits`
+* No use of cpp:std::locale[] or cpp:std::char_traits[]
 * No exotic character types, just low-ASCII `char`
 * No memory allocation (or bounded allocation)
 * Flexible composition with non-terminal rules

doc/modules/ROOT/pages/quicklook.adoc

@@ -52,7 +52,7 @@ include::example$unit/snippets.cpp[tag=code_urls_parsing_1,indent=0]
 ----
 
 In this example, `string_view` is an alias to `boost::core::string_view`, a
-`string_view` implementation that is implicitly convertible to `std::string_view`.
+`string_view` implementation that is implicitly convertible to cpp:std::string_view[].
 The library namespace includes the aliases `string_view`, `error_code`, and
 `result`.
 
@@ -389,7 +389,7 @@ include::example$unit/snippets.cpp[tag=snippet_quicklook_modifying_1b,indent=0]
 ----
 
 Objects of type `url` are https://en.cppreference.com/w/cpp/concepts/regular[std::regular,window=blank_].
-Similarly to built-in types, such as `int`, a `url` is copyable, movable, assignable, default constructible, and equality comparable.
+Similarly to built-in types, such as cpp:int[], a `url` is copyable, movable, assignable, default constructible, and equality comparable.
 They support all the inspection functions of
 `url_view`, and also provide functions to modify all components of the URL.
 

doc/modules/ROOT/pages/urls/containers.adoc

@@ -68,7 +68,7 @@ These members are used to inspect and modify the scheme:
 // Row 1, Column 1
 |`has_scheme`
 // Row 1, Column 2
-|`bool`
+|cpp:bool[]
 // Row 1, Column 3
 |Return `true` if a scheme is present.
 
@@ -140,7 +140,7 @@ These members are used to inspect and modify the authority as a whole string:
 // Row 1, Column 1
 |`has_authority`
 // Row 1, Column 2
-|`bool`
+|cpp:bool[]
 // Row 1, Column 3
 |Return `true` if an authority is present.
 
@@ -270,35 +270,35 @@ These members are used to inspect and modify the userinfo:
 // Row 1, Column 1
 |`has_userinfo`
 // Row 1, Column 2
-|`bool`
+|cpp:bool[]
 // Row 1, Column 3
 |Return `true` if a userinfo is present.
 
 // Row 2, Column 1
 |`has_password`
 // Row 2, Column 2
-|`bool`
+|cpp:bool[]
 // Row 2, Column 3
 |Return `true` if a password is present.
 
 // Row 3, Column 1
 |`user`
 // Row 3, Column 2
-|https://en.cppreference.com/w/cpp/string/basic_string[`std::string`,window=blank_]
+|cpp:std::string[]
 // Row 3, Column 3
 |Return the user as a decoded string.
 
 // Row 4, Column 1
 |`password`
 // Row 4, Column 2
-|https://en.cppreference.com/w/cpp/string/basic_string[`std::string`,window=blank_]
+|cpp:std::string[]
 // Row 4, Column 3
 |Return the password as a decoded string.
 
 // Row 5, Column 1
 |`userinfo`
 // Row 5, Column 2
-|https://en.cppreference.com/w/cpp/string/basic_string[`std::string`,window=blank_]
+|cpp:std::string[]
 // Row 5, Column 3
 |Return the userinfo as a decoded string.
 
@@ -421,7 +421,7 @@ If there is no authority, this is the value
 // Row 2, Column 1
 |`host`
 // Row 2, Column 2
-|https://en.cppreference.com/w/cpp/string/basic_string[`std::string`,window=blank_]
+|cpp:std::string[]
 // Row 2, Column 3
 |Return the host as a decoded string, or an empty string if there is
 no authority.
@@ -429,7 +429,7 @@ no authority.
 // Row 3, Column 1
 |`host_address`
 // Row 3, Column 2
-|https://en.cppreference.com/w/cpp/string/basic_string[`std::string`,window=blank_]
+|cpp:std::string[]
 // Row 3, Column 3
 |Return the host as a decoded string.
 If the host type is
@@ -440,7 +440,7 @@ the enclosing brackets are removed.
 // Row 4, Column 1
 |`host_name`
 // Row 4, Column 2
-|https://en.cppreference.com/w/cpp/string/basic_string[`std::string`,window=blank_]
+|cpp:std::string[]
 // Row 4, Column 3
 |Return the host name as a decoded string, or the empty string if
 the host type is not
@@ -644,7 +644,7 @@ These members are used to inspect and modify the port:
 // Row 1, Column 1
 |`has_port`
 // Row 1, Column 2
-|`bool`
+|cpp:bool[]
 // Row 1, Column 3
 |Return `true` if a port is present.
 
@@ -658,7 +658,7 @@ These members are used to inspect and modify the port:
 // Row 3, Column 1
 |`port_number`
 // Row 3, Column 2
-|`std::uint16_t`
+|cpp:std::uint16_t[]
 // Row 3, Column 3
 |Return the port as an unsigned integer. If the number would be
 greater than 65535, then zero is returned.
@@ -682,7 +682,7 @@ an exception is thrown.
 // Row 2, Column 1
 |`set_port_number`
 // Row 2, Column 2
-|`std::uint16_t`
+|cpp:std::uint16_t[]
 // Row 2, Column 3
 |Set the port to a number.
 
@@ -711,14 +711,14 @@ These members are used to inspect and modify the path:
 // Row 1, Column 1
 |`is_path_absolute`
 // Row 1, Column 2
-|`bool`
+|cpp:bool[]
 // Row 1, Column 3
 |Return `true` if the path starts with a forward slash ("/").
 
 // Row 2, Column 1
 |`path`
 // Row 2, Column 2
-|https://en.cppreference.com/w/cpp/string/basic_string[`std::string`,window=blank_]
+|cpp:std::string[]
 // Row 2, Column 3
 |Return the path as a decoded string.
 
@@ -761,7 +761,7 @@ Reserved characters are percent-escaped automatically.
 // Row 2, Column 1
 |`set_path_absolute`
 // Row 2, Column 2
-|`bool`
+|cpp:bool[]
 // Row 2, Column 3
 |Set whether the path is absolute.
 
@@ -809,14 +809,14 @@ These members are used to inspect and modify the query:
 // Row 1, Column 1
 |`has_query`
 // Row 1, Column 2
-|`bool`
+|cpp:bool[]
 // Row 1, Column 3
 |Return `true` if a query is present.
 
 // Row 2, Column 1
 |`query`
 // Row 2, Column 2
-|https://en.cppreference.com/w/cpp/string/basic_string[`std::string`,window=blank_]
+|cpp:std::string[]
 // Row 2, Column 3
 |Return the query as a decoded string.
 
@@ -907,14 +907,14 @@ These members are used to inspect and modify the fragment:
 // Row 1, Column 1
 |`has_fragment`
 // Row 1, Column 2
-|`bool`
+|cpp:bool[]
 // Row 1, Column 3
 |Return `true` if a fragment is present.
 
 // Row 2, Column 1
 |`fragment`
 // Row 2, Column 2
-|https://en.cppreference.com/w/cpp/string/basic_string[`std::string`,window=blank_]
+|cpp:std::string[]
 // Row 2, Column 3
 |Return the fragment as a decoded string.
 

doc/modules/ROOT/pages/urls/formatting.adoc

@@ -20,7 +20,7 @@ function to construct an absolute URL:
 include::example$unit/snippets.cpp[tag=snippet_format_1,indent=0]
 ----
 
-The rules for a format URL string are the same as for a https://en.cppreference.com/w/cpp/utility/format/basic_format_string[`std::format_string`,window=blank_], where replacement fields are delimited by curly braces.
+The rules for a format URL string are the same as for a cpp:std::format_string[], where replacement fields are delimited by curly braces.
 The URL type is inferred from the format string.
 
 The URL components to which replacement fields belong are identified before replacement is applied and any invalid characters for that formatted argument are percent-escaped:
@@ -55,7 +55,7 @@ The function `format_to` can be used to format URLs into any modifiable URL cont
 include::example$unit/snippets.cpp[tag=snippet_format_4,indent=0]
 ----
 
-As with https://en.cppreference.com/w/cpp/utility/format/format[`std::format`,window=blank_], positional and named arguments are supported.
+As with cpp:std::format[], positional and named arguments are supported.
 
 
 [source,cpp]
@@ -71,7 +71,7 @@ The `arg` function can be used to associate names with arguments:
 include::example$unit/snippets.cpp[tag=snippet_format_5b,indent=0]
 ----
 
-A second overload based on https://en.cppreference.com/w/cpp/utility/initializer_list[`std::initializer_list`,window=blank_]
+A second overload based on cpp:std::initializer_list[]
 is provided for both `format` and `format_to`.
 These overloads can help with lists of named arguments:
 

doc/modules/ROOT/pages/urls/params.adoc

@@ -80,7 +80,7 @@ To represent individual params the library uses these types, distinguished by th
 // Row 1, Column 1
 |`param`
 // Row 1, Column 2
-|https://en.cppreference.com/w/cpp/string/basic_string[`std::string`,window=blank_]
+|cpp:std::string[]
 // Row 1, Column 3
 |A key-value pair with ownership of the strings.
 This can be used to hold decoded strings, or to

doc/modules/ROOT/pages/urls/parsing.adoc

@@ -33,7 +33,7 @@ invalid URL.
 The caller is responsible for ensuring that the lifetime
 of the character buffer extends until it is no longer
 referenced by the view. These are the same semantics
-as that of `std::string_view`.
+as that of cpp:std::string_view[].
 ====
 
 For convenience, a URL view can be constructed directly from the character

doc/modules/ROOT/pages/urls/segments.adoc

@@ -53,8 +53,8 @@ First we observe these invariants about paths and segments:
 * A path is absolute, relative, or empty
 * Paths starting with "/" are absolute
 * A relative path can never follow an authority
-* Every path maps to a unique range of segments, plus a `bool` indicating if the path is absolute.
-* Every range of segments, plus a `bool` indicating if the path is absolute, maps to a unique path.
+* Every path maps to a unique range of segments, plus a cpp:bool[] indicating if the path is absolute.
+* Every range of segments, plus a cpp:bool[] indicating if the path is absolute, maps to a unique path.
 
 The following URL contains a path with three segments: "path", "to", and "file.txt":
 

doc/modules/ROOT/pages/urls/stringtoken.adoc

@@ -9,8 +9,7 @@
 
 = String Token
 
-Functions which perform percent-decoding return values using
-https://en.cppreference.com/w/cpp/string/basic_string[`std::string`,window=blank_] when called without special arguments.
+Functions which perform percent-decoding return values using cpp:std::string[] when called without special arguments.
 This is the best default for ergonomics, and a good enough default for performance considering that many decoded strings fit in the small buffer available to most standard implementations.
 Some use-cases may desire more control over how these algorithms acquire and store data in strings, for example:
 

doc/package-lock.json

@@ -7,7 +7,9 @@
       "dependencies": {
         "@antora/lunr-extension": "^1.0.0-alpha.8",
         "@asciidoctor/tabs": "^1.0.0-beta.3",
-        "asciidoctor": "^2.2.6"
+        "asciidoctor": "^2.2.6",
+        "xmldom": "^0.6.0",
+        "xpath": "^0.0.33"
       },
       "devDependencies": {
         "@antora/cli": "3.1.3",
@@ -2731,6 +2733,22 @@
         "node": ">=4"
       }
     },
+    "node_modules/xmldom": {
+      "version": "0.6.0",
+      "resolved": "https://registry.npmjs.org/xmldom/-/xmldom-0.6.0.tgz",
+      "integrity": "sha512-iAcin401y58LckRZ0TkI4k0VSM1Qg0KGSc3i8rU+xrxe19A/BN1zHyVSJY7uoutVlaTSzYyk/v5AmkewAP7jtg==",
+      "engines": {
+        "node": ">=10.0.0"
+      }
+    },
+    "node_modules/xpath": {
+      "version": "0.0.33",
+      "resolved": "https://registry.npmjs.org/xpath/-/xpath-0.0.33.tgz",
+      "integrity": "sha512-NNXnzrkDrAzalLhIUc01jO2mOzXGXh1JwPgkihcLLzw98c0WgYDmmjSh1Kl3wzaxSVWMuA+fe0WTWOBDWCBmNA==",
+      "engines": {
+        "node": ">=0.6.0"
+      }
+    },
     "node_modules/xtend": {
       "version": "4.0.2",
       "resolved": "https://registry.npmjs.org/xtend/-/xtend-4.0.2.tgz",

doc/package.json

@@ -1,12 +1,14 @@
 {
   "devDependencies": {
-    "antora": "3.1.3",
     "@antora/cli": "3.1.3",
-    "@antora/site-generator": "3.1.3"
+    "@antora/site-generator": "3.1.3",
+    "antora": "3.1.3"
   },
   "dependencies": {
     "@antora/lunr-extension": "^1.0.0-alpha.8",
     "@asciidoctor/tabs": "^1.0.0-beta.3",
-    "asciidoctor": "^2.2.6"
+    "asciidoctor": "^2.2.6",
+    "xmldom": "^0.6.0",
+    "xpath": "^0.0.33"
   }
-}
+}