doc: add a troubleshooting page

CLAUDE.md

@@ -97,6 +97,18 @@ silently unchecked test cannot slip through. So is a marker containing a `;`:
 and the test would pass on either half. Write `.*` in its place. The glob has no `CONFIGURE_DEPENDS` (matching the
 `test_*.cpp` glob above it), so a new file needs a manual re-run of `cmake`.
 
+The same glob, in both `test/CMakeLists.txt` and `test/Jamfile`, also picks up
+`doc/modules/ROOT/examples/troubleshooting/compile_fail_*.cpp`: the compile errors shown on the
+troubleshooting page are tests, so the messages it quotes cannot drift from the library's. They
+sit in a subdirectory because `doc/modules/ROOT/examples/CMakeLists.txt` builds every top-level
+`*.cpp` as an ordinary example. Match a gcc curly quote (`‘postfix’`) with `.*`, not `.`: it is
+three bytes, and the regex works on bytes.
+
+The tested sources behind the reference's `include:` markers live in
+`doc/modules/ROOT/examples/snippets/`, inside Antora's `examples` family, so that pages can include
+them too (`include::example$snippets/...`). Antora ignores any directory of a module that is not
+a family, so a page cannot reach files outside one.
+
 Where the expected wording differs across compilers, match the common substring and say why in a
 comment above the marker - `no matching` (clang/gcc "no matching function for call to" vs MSVC "no
 matching overloaded function found"), `deleted function` (gcc "use of a", clang "call to", MSVC

CMakeLists.txt

@@ -327,7 +327,7 @@ if (BOOST_OPENMETHOD_BUILD_TESTS)
     if (BOOST_OPENMETHOD_BUILD_EXAMPLES)
         add_subdirectory(doc/modules/ROOT/examples)
         # Sources behind the `include:` markers in the reference doc comments.
-        add_subdirectory(doc/modules/ROOT/snippets)
+        add_subdirectory(doc/modules/ROOT/examples/snippets)
         # Examples published on Compiler Explorer, see ce/README.md.
         add_subdirectory(ce)
     endif ()

doc/modules/ROOT/examples/troubleshooting/compile_fail_call_non_polymorphic.cpp

@@ -0,0 +1,38 @@
+// Copyright (c) 2017-2026 Jean-Louis Leroy
+// 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)
+
+// Shown on the troubleshooting page, and checked like test/compile_fail_*.cpp.
+// No static_assert names this mistake, so match the head of the compiler's own
+// message: gcc and clang say "no matching function for call to 'postfix'", MSVC
+// "'postfix': no matching overloaded function found".
+// Expected diagnostic, as a CMake regex (see test/CMakeLists.txt).
+// expected-error: no matching function for call to .*postfix|postfix.*: no matching overloaded function found
+
+// tag::content[]
+#include <iostream>
+
+#include <boost/openmethod.hpp>
+#include <boost/openmethod/initialize.hpp>
+
+using boost::openmethod::virtual_ptr;
+
+struct Node {};
+
+struct Plus : Node {};
+
+BOOST_OPENMETHOD(postfix, (virtual_ptr<Node>, std::ostream&), void);
+
+BOOST_OPENMETHOD_OVERRIDE(
+    postfix, (virtual_ptr<Plus>, std::ostream& os), void) {
+    os << "+";
+}
+
+int main() {
+    boost::openmethod::initialize();
+
+    Plus plus;
+    postfix(plus, std::cout);
+}
+// end::content[]

doc/modules/ROOT/examples/troubleshooting/compile_fail_override_private_base.cpp

@@ -0,0 +1,30 @@
+// Copyright (c) 2017-2026 Jean-Louis Leroy
+// 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)
+
+// Shown on the troubleshooting page, and checked like test/compile_fail_*.cpp.
+// Expected diagnostic, as a CMake regex (see test/CMakeLists.txt).
+// expected-error: cannot find 'postfix' method that accepts the same arguments as the overrider
+
+// tag::content[]
+#include <iostream>
+
+#include <boost/openmethod.hpp>
+
+using boost::openmethod::virtual_ptr;
+
+class Node {
+  public:
+    virtual ~Node() = default;
+};
+
+class Plus : Node {};
+
+BOOST_OPENMETHOD(postfix, (virtual_ptr<Node>, std::ostream&), void);
+
+BOOST_OPENMETHOD_OVERRIDE(
+    postfix, (virtual_ptr<Plus>, std::ostream& os), void) {
+    os << "+";
+}
+// end::content[]

doc/modules/ROOT/examples/troubleshooting/compile_fail_overrider_discards_const.cpp

@@ -0,0 +1,29 @@
+// Copyright (c) 2017-2026 Jean-Louis Leroy
+// 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)
+
+// Shown on the troubleshooting page, and checked like test/compile_fail_*.cpp.
+// Expected diagnostic, as a CMake regex (see test/CMakeLists.txt).
+// expected-error: overrider parameter discards const qualifier
+
+// tag::content[]
+#include <iostream>
+
+#include <boost/openmethod.hpp>
+
+using boost::openmethod::virtual_ptr;
+
+struct Node {
+    virtual ~Node() = default;
+};
+
+struct Plus : Node {};
+
+BOOST_OPENMETHOD(postfix, (virtual_ptr<const Node>, std::ostream&), void);
+
+BOOST_OPENMETHOD_OVERRIDE(
+    postfix, (virtual_ptr<Plus>, std::ostream& os), void) {
+    os << "+";
+}
+// end::content[]

doc/modules/ROOT/nav.adoc

@@ -16,6 +16,7 @@
 ** xref:interop_any.adoc[Interoperation with `any`]
 ** xref:interop_type_erasure.adoc[Interoperation with Boost.TypeErasure]
 ** xref:shared_libraries.adoc[Shared Libraries]
+* xref:troubleshooting.adoc[Troubleshooting]
 * Reference
 ** xref:ref_headers.adoc[Headers]
 ** xref:ref_macros.adoc[Macros]

doc/modules/ROOT/pages/basics.adoc

@@ -1,4 +1,3 @@
-:exampledir: ../example
 
 [#basics]