docs: support and include reference tagfiles

doc/antora.yml

@@ -25,6 +25,17 @@ ext:
       dir: doc/build/generated-files
   cpp-tagfiles:
     files:
+      - file: ./doc/tagfiles/boost-url-doxygen.tag.xml
+        base_url: 'xref:reference:'
       - file: ./doc/tagfiles/boost-system-doxygen.tag.xml
         base_url: https://www.boost.org/doc/libs/master/libs/system/doc/html/
+      - file: ./doc/tagfiles/boost-core-doxygen.tag.xml
+        base_url: https://www.boost.org/doc/libs/master/libs/core/doc/html/
+      - file: ./doc/tagfiles/boost-filesystem-doxygen.tag.xml
+        base_url: https://www.boost.org/doc/libs/master/libs/filesystem/doc/
+    using-namespaces:
+      - boost::urls
+      - boost::urls::grammar
+      - boost::system
+      - boost::core
 

doc/local-playbook.yml

@@ -35,6 +35,9 @@ antora:
       index_latest_only: true
     - '@antora/collector-extension'
     - require: ./lib/cpp-tagfiles.js
+      cpp-tagfiles:
+        using-namespaces:
+          - 'boost::'
 asciidoc:
   attributes:
     # Enable pagination

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

@@ -18,77 +18,77 @@ A __CharSet__ is a unary predicate which is invocable with this equivalent signa
 bool( char ch ) const noexcept;
 ----
 
-The predicate returns `true` if `ch` is a member of the set, or `false` otherwise.
+The predicate returns cpp:true[] if cpp:ch[] is a member of the set, or cpp:false[] otherwise.
 
 == Related Identifiers
 
-`is_charset`,
-`find_if`,
-`find_if_not`.
+cpp:is_charset[],
+cpp:find_if[],
+cpp:find_if_not[].
 
 == Requirements
 
 In this table:
 
-* `T` is a type meeting the requirements of __CharSet__
-* `t` is a `const` value of type `T`
-* `c` is a value of type `char`
-* `first`, `last` are values of type `char const*`
+* cpp:T[] is a type meeting the requirements of __CharSet__
+* cpp:t[] is a cpp:const[] value of type cpp:T[]
+* cpp:c[] is a value of type cpp:char[]
+* cpp:first[], cpp:last[] are values of type cpp:char const*[]
 
 [cols="1,1,3"]
 |===
 // Headers
 |Expression|Type|Semantics, Pre/Post-conditions
 
 // Row 1, Column 1
-|`t(c)`
+|cpp:t(c)[]
 // Row 1, Column 2
 |cpp:bool[]
 // Row 1, Column 3
-|This function returns `true` if `c` is a member of
-the character set, otherwise it returns `false`.
+|This function returns cpp:true[] if cpp:c[] is a member of
+the character set, otherwise it returns cpp:false[].
 
 // Row 2, Column 1
 |
-`t.find_if(first,last)`
+cpp:t.find_if(first,last)[]
 
 // Row 2, Column 2
-|`char const*`
+|cpp:char const*[]
 // Row 2, Column 3
-|This optional member function examines the valid range of characters in `// [first, last)` and returns
+|This optional member function examines the valid range of characters in cpp:// [first, last)[] and returns
 a pointer to the first occurrence of a character
-which is in the set, or returns `last` if no such
+which is in the set, or returns cpp:last[] if no such
 character.
 
-The implementation of `grammar::find_if`
+The implementation of cpp:grammar::find_if[]
 calls this function if provided by the character
 set, allowing optimized or otherwise performant
 implementations to be developed. If this member
 function is not provided, a default implementation
-is used which calls `operator()`.
+is used which calls cpp:operator()[].
 
 // Row 3, Column 1
-|`t.find_if_not(first,last)`
+|cpp:t.find_if_not(first,last)[]
 // Row 3, Column 2
-|`char const*`
+|cpp:char const*[]
 // Row 3, Column 3
 |This optional member function examines the valid
-range of characters in `[first, last)` and returns
+range of characters in cpp:[first, last)[] and returns
 a pointer to the first occurrence of a character
-which is not in the set, or returns `last` if no
+which is not in the set, or returns cpp:last[] if no
 such character.
 
-The implementation of `grammar::find_if_not`
+The implementation of cpp:grammar::find_if_not[]
 calls this function if provided by the character
 set, allowing optimized or otherwise performant
 implementations to be developed. If this member
 function is not provided, a default implementation
-is used which calls `operator()`.
+is used which calls cpp:operator()[].
 |===
 
 == Exemplar
 
-For best results, it is suggested that all constructors and member functions for character sets be marked `constexpr`.
+For best results, it is suggested that all constructors and member functions for character sets be marked cpp:constexpr[].
 
 // code_charset_1
 [source,cpp]
@@ -107,10 +107,10 @@ struct CharSet
 
 == Models
 
-* `grammar::alnum_chars`
-* `grammar::alpha_chars`
-* `grammar::digit_chars`
-* `grammar::hexdig_chars`
-* `grammar::lut_chars`
+* cpp:grammar::alnum_chars[]
+* cpp:grammar::alpha_chars[]
+* cpp:grammar::digit_chars[]
+* cpp:grammar::hexdig_chars[]
+* cpp:grammar::lut_chars[]
 
 

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

@@ -13,38 +13,38 @@
 A __Rule__ defines an algorithm used to match an input buffer of ASCII characters against a set of syntactical specifications.
 Each rule represents either a terminal symbol or a composition in the represented grammar.
 The library comes with a set of rules for productions typically found in RFC documents.
-Rules are not invoked directly; instead, rule variables are used with overloads of `parse` which provide a convenient, uniform front end.
+Rules are not invoked directly; instead, rule variables are used with overloads of cpp:parse[] which provide a convenient, uniform front end.
 
 == Related Identifiers
 
-`is_rule`, `parse`.
+cpp:is_rule[], cpp:parse[].
 
 == Requirements
 
 In this table:
 
-* `T` is a type meeting the requirements of __Rule__
-* `t` is a const value of type `T`
-* `it` is an __lvalue__ with type `char const*`
-* `end` is a value of type `char const*`
+* cpp:T[] is a type meeting the requirements of __Rule__
+* cpp:t[] is a const value of type cpp:T[]
+* cpp:it[] is an __lvalue__ with type cpp:char const*[]
+* cpp:end[] is a value of type cpp:char const*[]
 
 [cols="1,1,3"]
 |===
 // Headers
 |Expression|Type|Semantics, Pre/Post-conditions
 
 // Row 1, Column 1
-|`T(t)`
+|cpp:T(t)[]
 
 // Row 1, Column 2
 | -
 // Row 1, Column 3
-|Copy construction of `T` throws nothing.
+|Copy construction of cpp:T[] throws nothing.
 
-cpp:std::is_nothrow_copy_constructible<T>::value[] == true`
+cpp:std::is_nothrow_copy_constructible<T>::value[] == truecpp:
 
 // Row 2, Column 1
-|`T::value_type`
+|[]T::value_typecpp:
 
 // Row 2, Column 2
 | -
@@ -53,25 +53,25 @@ cpp:std::is_nothrow_copy_constructible<T>::value[] == true`
 parse operation is successful
 
 // Row 3, Column 1
-|`t.parse(it,end)`
+|[]t.parse(it,end)cpp:
 
 // Row 3, Column 2
-|`result<T::value_type>`
+|[]result<T::value_type>cpp:
 // Row 3, Column 3
 |Attempt to parse the buffer of characters defined by
-the range `// [it,end)`. Upon success, the return result
+the range []// [it,end)cpp:. Upon success, the return result
 holds an instance of the rule's value type, and
-the reference parameter `it` is modified to point
+the reference parameter []itcpp: is modified to point
 to the first unconsumed character. Otherwise, upon
 failure the result holds an error. In this case
 the implementation defines if and how the reference
-parameter `it` is modified.
+parameter []itcpp: is modified.
 
 |===
 
 == Exemplar
 
-For best results, it is suggested that all constructors for rules be marked `constexpr`.
+For best results, it is suggested that all constructors for rules be marked []constexprcpp:.
 
 [source,cpp]
 ----
@@ -90,12 +90,12 @@ constexpr Rule rule{};
 
 == Model
 
-* `grammar::dec_octet_rule`
-* `grammar::delim_rule`
-* `grammar::not_empty_rule`
-* `grammar::optional_rule`
-* `grammar::range_rule`
-* `grammar::token_rule`
-* `grammar::tuple_rule`
-* `grammar::unsigned_rule`
-* `grammar::variant_rule`
+* []grammar::dec_octet_rulecpp:
+* []grammar::delim_rulecpp:
+* []grammar::not_empty_rulecpp:
+* []grammar::optional_rulecpp:
+* []grammar::range_rulecpp:
+* []grammar::token_rulecpp:
+* []grammar::tuple_rulecpp:
+* []grammar::unsigned_rulecpp:
+* []grammar::variant_rule`

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

@@ -17,9 +17,9 @@ A string token cannot be copied, moved, or assigned, and must be destroyed when
 
 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 cpp:std::size_t[]
+* cpp:T[] is a type meeting the requirements of __StringToken__
+* cpp:t[] is an rvalue reference of type T
+* cpp:n[] is a value of type cpp:std::size_t[]
 
 [cols="1,1,3"]
 |===
@@ -31,15 +31,15 @@ In this table:
 cpp:std::derived_from<T,string_token::arg>[]
 
 // Row 1, Column 2
-|`true`
+|cpp:true[]
 
 // Row 1, Column 3
 |All string tokens must be publicly and
 unambiguously derived from
-`string_token::arg`.
+cpp:string_token::arg[].
 
 // Row 2, Column 1
-|`T::result_type`
+|cpp:T::result_type[]
 
 // Row 2, Column 2
 |
@@ -48,26 +48,26 @@ unambiguously derived from
 which accept a string token.
 
 // Row 3, Column 1
-|`t.prepare(n);`
+|cpp:t.prepare(n);[]
 
 // Row 3, Column 2
-|`char*`
+|cpp:char*[]
 
 // Row 3, Column 3
 |This function overrides the virtual function in the base.
 It must return a pointer to a character buffer of at least
-size `n`, otherwise throw an exception.
+size cpp:n[], otherwise throw an exception.
 
 // Row 4, Column 1
-|`t.result();`
+|cpp:t.result();[]
 
 // Row 4, Column 3
-|`T::result_type`
+|cpp:T::result_type[]
 
 // Row 4, Column 5
 |This function is invoked by the algorithm to receive the result
 from the string token.
-It is only invoked if `prepare` returned successfuly and the
+It is only invoked if cpp:prepare[] returned successfuly and the
 string token was not destroyed.
 
 |===
@@ -76,8 +76,8 @@ string token was not destroyed.
 
 When an algorithm accepts a string token, it must meet these requirements:
 
-* `prepare` is called only once or not at all,
-* `result` is only called after `prepare` returns successfully, and
+* cpp:prepare[] is called only once or not at all,
+* cpp:result[] is only called after cpp:prepare[] returns successfully, and
 * The string token is destroyed when the algorithm completes or if an exception is thrown.
 
 String tokens cannot be reused.
@@ -112,7 +112,7 @@ void algorithm_impl( string_token::arg& token )
 {
     std::size_t n = 0;
 
-    // calculate space needed in `n`
+    // calculate space needed in cpp:n[]
 
     // acquire a destination buffer
     char* dest = token.prepare( n );
@@ -141,9 +141,9 @@ algorithm( StringToken&& token = {} ) ->
 
 Models
 
-* `string_token::return_string`
-* `string_token::assign_to`
-* `string_token::preserve_size`
-* `string_token::return_string`
+* cpp:string_token::return_string[]
+* cpp:string_token::assign_to[]
+* cpp:string_token::preserve_size[]
+* cpp:string_token::return_string[]