Merge pull request #18 from Progmasoft/build/catch3-identity

Give Catch3 its own build names and headers

33 files changed, 228 insertions, 286 deletions

diff --git a/docs/Readme.md b/docs/Readme.md
index 65268c99..18bdf927 100644
--- a/docs/Readme.md
+++ b/docs/Readme.md
@@ -6,14 +6,14 @@ Catch3 keeps Catch2's API for writing tests, runs them with
 extensions. Start with the [tutorial](tutorial.md#top), then read
 [the runner](progmasoft-runner.md#top), [what Catch3 adds](progmasoft-catch3.md),
 [native property testing](progmasoft-properties.md), [the roadmap](progmasoft-roadmap.md) and
-[why the two API families remain distinct](why-catch3.md). The compatibility
-pages below retain real `catch2/` include paths, `Catch2::` CMake targets,
-and upstream version history; renaming those would make examples incorrect.
-
-The Progmasoft extension API lives under `Progmasoft/Catch3/...` and the
-`Progmasoft::Catch3` namespace. Its built library is separate from the
-upstream-compatible engine. The compatibility pages are about the bundled
-engine, not a claim that Catch3 is an official Catch2 release.
+[why Catch3 exists](why-catch3.md).
+
+Every header is under `Progmasoft/Catch3/`, and the library is
+`Catch3::Catch3` (`find_package(Catch3)`, `//:catch3` in Bazel). The pages
+marked as compatibility references describe the test-writing API Catch3
+shares with Catch2: the macros and the `Catch::` namespace. Progmasoft's own
+API lives in the `Progmasoft::Catch3` namespace. Catch3 is not an official
+Catch2 release.
 
 ## Reference
 
diff --git a/docs/assertions.md b/docs/assertions.md
index 9cc8d0ed..3ac48f30 100644
--- a/docs/assertions.md
+++ b/docs/assertions.md
@@ -1,6 +1,6 @@
 <a id="top"></a>
 
-> **Catch3 compatibility reference:** This page describes the bundled Catch2-compatible API. Names such as `Catch2`, `catch2/`, and `Catch2::Catch2WithMain` remain where they are actual compatibility interfaces. See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
+> **Catch3 compatibility reference:** This page describes the test-writing API Catch3 shares with Catch2: the macros, such as `TEST_CASE` and `REQUIRE`, and the `Catch::` namespace keep Catch2's names. Headers and build names are Catch3's own (`<Progmasoft/Catch3/TestMacros.hpp>`, `find_package(Catch3)`, `Catch3::Catch3WithMain`). See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
 
 # Assertion Macros
 
diff --git a/docs/benchmarks.md b/docs/benchmarks.md
index bc1e19da..d970d7a1 100644
--- a/docs/benchmarks.md
+++ b/docs/benchmarks.md
@@ -1,6 +1,6 @@
 <a id="top"></a>
 
-> **Catch3 compatibility reference:** This page describes the bundled Catch2-compatible API. Names such as `Catch2`, `catch2/`, and `Catch2::Catch2WithMain` remain where they are actual compatibility interfaces. See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
+> **Catch3 compatibility reference:** This page describes the test-writing API Catch3 shares with Catch2: the macros, such as `TEST_CASE` and `REQUIRE`, and the `Catch::` namespace keep Catch2's names. Headers and build names are Catch3's own (`<Progmasoft/Catch3/TestMacros.hpp>`, `find_package(Catch3)`, `Catch3::Catch3WithMain`). See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
 
 # Authoring benchmarks
 
diff --git a/docs/ci-and-misc.md b/docs/ci-and-misc.md
index 9932ccbc..a899c69f 100644
--- a/docs/ci-and-misc.md
+++ b/docs/ci-and-misc.md
@@ -1,6 +1,6 @@
 <a id="top"></a>
 
-> **Catch3 compatibility reference:** This page describes the bundled Catch2-compatible API. Names such as `Catch2`, `catch2/`, and `Catch2::Catch2WithMain` remain where they are actual compatibility interfaces. See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
+> **Catch3 compatibility reference:** This page describes the test-writing API Catch3 shares with Catch2: the macros, such as `TEST_CASE` and `REQUIRE`, and the `Catch::` namespace keep Catch2's names. Headers and build names are Catch3's own (`<Progmasoft/Catch3/TestMacros.hpp>`, `find_package(Catch3)`, `Catch3::Catch3WithMain`). See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
 
 # Tooling integration (CI, test runners and so on)
 
diff --git a/docs/cmake-integration.md b/docs/cmake-integration.md
index d3d45dfe..01c9905a 100644
--- a/docs/cmake-integration.md
+++ b/docs/cmake-integration.md
@@ -1,6 +1,6 @@
 <a id="top"></a>
 
-> **Catch3 compatibility reference:** This page describes the bundled Catch2-compatible API. Names such as `Catch2`, `catch2/`, and `Catch2::Catch2WithMain` remain where they are actual compatibility interfaces. See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
+> **Catch3 compatibility reference:** This page describes the test-writing API Catch3 shares with Catch2: the macros, such as `TEST_CASE` and `REQUIRE`, and the `Catch::` namespace keep Catch2's names. Headers and build names are Catch3's own (`<Progmasoft/Catch3/TestMacros.hpp>`, `find_package(Catch3)`, `Catch3::Catch3WithMain`). See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
 
 # CMake integration
 
@@ -9,68 +9,61 @@
 [Automatic test registration](#automatic-test-registration)<br>
 [CMake project options](#cmake-project-options)<br>
 [`CATCH_CONFIG_*` customization options in CMake](#catch_config_-customization-options-in-cmake)<br>
-[Using Progmasoft Catch3 from a checkout](#using-progmasoft-catch3-from-a-checkout)<br>
+[Using Catch3 from a checkout](#using-catch3-from-a-checkout)<br>
 [Using an installed Catch3 package](#using-an-installed-catch3-package)<br>
-[Upstream Catch2 packages](#upstream-catch2-packages)<br>
+[Catch3 next to Catch2](#catch3-next-to-catch2)<br>
 
-Catch3 builds its Progmasoft C++20 extension library alongside the
-Catch2-compatible C++14 engine. CMake exposes both API families:
+Catch3's CMake package is `Catch3`. It exports two targets:
 
-1. `Progmasoft::Catch3` contains the new compiled extensions and depends on
-   `Catch2::Catch2`.
-2. `Catch2::Catch2WithMain` supplies the existing test runner and `main`.
-3. The bundled Catch2 scripts register `TEST_CASE`s with CTest.
+1. `Catch3::Catch3`, the library: the Catch2-compatible engine, the Catch3
+   runner, property testing and snapshots. It is built as C++20; code that
+   includes only the engine's headers needs C++14.
+2. `Catch3::Catch3WithMain`, the library with the default `main`.
 
-Do not use the upstream `catchorg/Catch2` checkout or its vcpkg/Bazel package
-when you need `Progmasoft::Catch3`; those packages do not contain this fork's
-extensions.
+`Catch3.cmake` registers each `TEST_CASE` with CTest.
 
 ## CMake targets
 
-The fork exports `Progmasoft::Catch3`, `Catch2::Catch2`, and
-`Catch2::Catch2WithMain`. Link the Progmasoft target when using extension
-headers; link `Catch2::Catch2WithMain` unless you provide a custom `main`.
-For a CMake-installed fork:
+Link `Catch3::Catch3WithMain` unless you provide a custom `main`. For an
+installed Catch3:
 
 ```cmake
-find_package(Catch2 3.16 CONFIG REQUIRED)
-find_package(ProgmasoftCatch3 3.16 CONFIG REQUIRED)
+find_package(Catch3 0.3 CONFIG REQUIRED)
 add_executable(tests test.cpp)
-target_link_libraries(tests PRIVATE Progmasoft::Catch3 Catch2::Catch2WithMain)
+target_link_libraries(tests PRIVATE Catch3::Catch3WithMain)
 
 add_executable(custom-main-tests test.cpp test-main.cpp)
-target_link_libraries(custom-main-tests PRIVATE Progmasoft::Catch3)
+target_link_libraries(custom-main-tests PRIVATE Catch3::Catch3)
 ```
 
-If the fork is checked out in `external/catch3`, build it as a subdirectory:
+If Catch3 is checked out in `external/catch3`, build it as a subdirectory:
 
 ```cmake
 add_subdirectory(external/catch3)
 add_executable(tests test.cpp)
-target_link_libraries(tests PRIVATE Progmasoft::Catch3 Catch2::Catch2WithMain)
+target_link_libraries(tests PRIVATE Catch3::Catch3WithMain)
 ```
 
 
 ## Automatic test registration
 
-Catch2's repository also contains three CMake scripts that help users
-with automatically registering their `TEST_CASE`s with CTest. They
-can be found in the `extras` folder, and are
+Catch3 also contains two CMake scripts that register `TEST_CASE`s with
+CTest. They are in the `extras` folder:
 
-1) `Catch.cmake` (and its dependency `CatchAddTests.cmake`)
-2) `ParseAndAddCatchTests.cmake` (deprecated)
-3) `CatchShardTests.cmake` (and its dependency `CatchShardTestsImpl.cmake`)
+1) `Catch3.cmake` (and its dependency `Catch3AddTests.cmake`)
+2) `Catch3ShardTests.cmake` (and its dependency `Catch3ShardTestsImpl.cmake`)
 
-If Catch2 has been installed in system, both of these can be used after
-doing `find_package(Catch2 REQUIRED)`. Otherwise you need to add them
-to your CMake module path.
+If Catch3 is installed, both can be used after `find_package(Catch3 REQUIRED)`.
+Otherwise add the `extras` folder to your CMake module path. Their names, and
+the names of the functions they define, start with `Catch3`/`catch3_`, so they
+do not meet Catch2's `Catch.cmake` in a project that uses both.
 
-<a id="catch_discover_tests"></a>
-### `Catch.cmake` and `CatchAddTests.cmake`
+<a id="catch3_discover_tests"></a>
+### `Catch3.cmake` and `Catch3AddTests.cmake`
 
-`Catch.cmake` provides function `catch_discover_tests` to get tests from
+`Catch3.cmake` provides function `catch3_discover_tests` to get tests from
 a target. This function works by running the resulting executable with
-`--list-test` flag, and then parsing the output to find all existing tests.
+`--list=json`, and then reading the listing to find all existing tests.
 
 #### Usage
 ```cmake
@@ -78,32 +71,32 @@ cmake_minimum_required(VERSION 3.16)
 
 project(baz LANGUAGES CXX VERSION 0.0.1)
 
-find_package(Catch2 REQUIRED)
+find_package(Catch3 REQUIRED)
 add_executable(tests test.cpp)
-target_link_libraries(tests PRIVATE Catch2::Catch2)
+target_link_libraries(tests PRIVATE Catch3::Catch3)
 
 include(CTest)
-include(Catch)
-catch_discover_tests(tests)
+include(Catch3)
+catch3_discover_tests(tests)
 ```
 
-When using `FetchContent`, `include(Catch)` will fail unless
+When using `FetchContent`, `include(Catch3)` will fail unless
 `CMAKE_MODULE_PATH` is explicitly updated to include the extras
 directory.
 
 ```cmake
 # ... FetchContent ...
 #
-list(APPEND CMAKE_MODULE_PATH ${catch2_SOURCE_DIR}/extras)
+list(APPEND CMAKE_MODULE_PATH ${catch3_SOURCE_DIR}/extras)
 include(CTest)
-include(Catch)
-catch_discover_tests(tests)
+include(Catch3)
+catch3_discover_tests(tests)
 ```
 
 #### Customization
-`catch_discover_tests` can be given several extra arguments:
+`catch3_discover_tests` can be given several extra arguments:
 ```cmake
-catch_discover_tests(target
+catch3_discover_tests(target
                      [TEST_SPEC arg1...]
                      [EXTRA_ARGS arg1...]
                      [WORKING_DIRECTORY dir]
@@ -142,7 +135,7 @@ option is not provided, the current binary directory is used.
 
 Specifies a _prefix_ to be added to the name of each discovered test case.
 This can be useful when the same test executable is being used in multiple
-calls to `catch_discover_tests()`, with different `TEST_SPEC` or `EXTRA_ARGS`.
+calls to `catch3_discover_tests()`, with different `TEST_SPEC` or `EXTRA_ARGS`.
 
 
 * `TEST_SUFFIX suffix`
@@ -154,14 +147,14 @@ Both `TEST_PREFIX` and `TEST_SUFFIX` can be specified at the same time.
 * `PROPERTIES name1 value1...`
 
 Specifies additional properties to be set on all tests discovered by this
-invocation of `catch_discover_tests`.
+invocation of `catch3_discover_tests`.
 
 
 * `TEST_LIST var`
 
 Make the list of tests available in the variable `var`, rather than the
 default `<target>_TESTS`.  This can be useful when the same test
-executable is being used in multiple calls to `catch_discover_tests()`.
+executable is being used in multiple calls to `catch3_discover_tests()`.
 Note that this variable is only available in CTest.
 
 * `REPORTER reporter`
@@ -196,12 +189,12 @@ For a value of `POST_BUILD` (default) test discovery is performed at build time.
 For a value of `PRE_TEST` test discovery is delayed until just prior to test
 execution (useful e.g. in cross-compilation environments).
 ``DISCOVERY_MODE`` defaults to the value of the
-``CMAKE_CATCH_DISCOVER_TESTS_DISCOVERY_MODE`` variable if it is not passed when
-calling ``catch_discover_tests``. This provides a mechanism for globally
+``CMAKE_CATCH3_DISCOVER_TESTS_DISCOVERY_MODE`` variable if it is not passed when
+calling ``catch3_discover_tests``. This provides a mechanism for globally
 selecting a preferred test discovery behavior.
 
 _Note that on Apple Silicon with the Xcode generator you must use `PRE_TEST`,
-e.g. `catch_discover_tests(tests DISCOVERY_MODE PRE_TEST)`. With the default
+e.g. `catch3_discover_tests(tests DISCOVERY_MODE PRE_TEST)`. With the default
 `POST_BUILD` mode the build fails with `Result: Subprocess killed`, because
 macOS on Apple Silicon refuses to run unsigned binaries and Xcode code-signs
 the test executable only **after** the post-build script that `POST_BUILD`
@@ -220,73 +213,10 @@ Skipped tests will be marked as failed instead.
 Add the tags from tests as labels to CTest.
 
 
-### `ParseAndAddCatchTests.cmake`
+### `Catch3ShardTests.cmake`
 
-⚠ This script is [deprecated](https://github.com/catchorg/Catch2/pull/2120)
-in Catch2 2.13.4 and superseded by the above approach using `catch_discover_tests`.
-See [#2092](https://github.com/catchorg/Catch2/issues/2092) for details.
-
-`ParseAndAddCatchTests` works by parsing all implementation files
-associated with the provided target, and registering them via CTest's
-`add_test`. This approach has some limitations, such as the fact that
-commented-out tests will be registered anyway. More serious, only a
-subset of the assertion macros currently available in Catch can be
-detected by this script and tests with any macros that cannot be
-parsed are *silently ignored*.
-
-
-#### Usage
-
-```cmake
-cmake_minimum_required(VERSION 3.16)
-
-project(baz LANGUAGES CXX VERSION 0.0.1)
-
-find_package(Catch2 REQUIRED)
-add_executable(tests test.cpp)
-target_link_libraries(tests PRIVATE Catch2::Catch2)
-
-include(CTest)
-include(ParseAndAddCatchTests)
-ParseAndAddCatchTests(tests)
-```
-
-
-#### Customization
-
-`ParseAndAddCatchTests` provides some customization points:
-* `PARSE_CATCH_TESTS_VERBOSE` -- When `ON`, the script prints debug
-messages. Defaults to `OFF`.
-* `PARSE_CATCH_TESTS_NO_HIDDEN_TESTS` -- When `ON`, hidden tests (tests
-tagged with either of `[.]` or `[.foo]`) will not be registered.
-Defaults to `OFF`.
-* `PARSE_CATCH_TESTS_ADD_FIXTURE_IN_TEST_NAME` -- When `ON`, adds fixture
-class name to the test name in CTest. Defaults to `ON`.
-* `PARSE_CATCH_TESTS_ADD_TARGET_IN_TEST_NAME` -- When `ON`, adds target
-name to the test name in CTest. Defaults to `ON`.
-* `PARSE_CATCH_TESTS_ADD_TO_CONFIGURE_DEPENDS` -- When `ON`, adds test
-file to `CMAKE_CONFIGURE_DEPENDS`. This means that the CMake configuration
-step will be re-ran when the test files change, letting new tests be
-automatically discovered. Defaults to `OFF`.
-
-
-Optionally, one can specify a launching command to run tests by setting the
-variable `OptionalCatchTestLauncher` before calling `ParseAndAddCatchTests`. For
-instance to run some tests using `MPI` and other sequentially, one can write
-```cmake
-set(OptionalCatchTestLauncher ${MPIEXEC} ${MPIEXEC_NUMPROC_FLAG} ${NUMPROC})
-ParseAndAddCatchTests(mpi_foo)
-unset(OptionalCatchTestLauncher)
-ParseAndAddCatchTests(bar)
-```
-
-
-### `CatchShardTests.cmake`
-
-> `CatchShardTests.cmake` was introduced in Catch2 3.1.0.
-
-`CatchShardTests.cmake` provides a function
-`catch_add_sharded_tests(TEST_BINARY)` that splits tests from `TEST_BINARY`
+`Catch3ShardTests.cmake` provides a function
+`catch3_add_sharded_tests(TEST_BINARY)` that splits tests from `TEST_BINARY`
 into multiple shards. The tests in each shard and their order is randomized,
 and the seed changes every invocation of CTest.
 
@@ -299,14 +229,14 @@ Currently there are 3 customization points for this script:
 Example usage:
 
 ```
-include(CatchShardTests)
+include(Catch3ShardTests)
 
-catch_add_sharded_tests(foo-tests
+catch3_add_sharded_tests(foo-tests
   SHARD_COUNT 4
   TEST_SPEC "A"
 )
 
-catch_add_sharded_tests(tests
+catch3_add_sharded_tests(tests
   SHARD_COUNT 8
   TEST_SPEC "B"
 )
@@ -318,53 +248,52 @@ from `foo-tests` test binary, filtered by a test spec.
 _Note that this script is currently a proof-of-concept for reseeding
 shards per CTest run, and thus does not support (nor does it currently
 aim to support) all customization points from
-[`catch_discover_tests`](#catch_discover_tests)._
+[`catch3_discover_tests`](#catch3_discover_tests)._
 
 
 ## CMake project options
 
-Catch2's CMake project also provides some options for other projects
+Catch3's CMake project also provides some options for other projects
 that consume it. These are:
 
 * `BUILD_TESTING` -- When `ON` and the project is not used as a subproject,
-Catch2's test binary will be built. Defaults to `ON`.
-* `CATCH_INSTALL_DOCS` -- When `ON`, Catch2's documentation will be
+Catch3's test binaries will be built. Defaults to `ON`.
+* `CATCH3_INSTALL_DOCS` -- When `ON`, Catch3's documentation will be
 included in the installation. Defaults to `ON`.
-* `CATCH_INSTALL_EXTRAS` -- When `ON`, Catch2's extras folder (the CMake
+* `CATCH3_INSTALL_EXTRAS` -- When `ON`, Catch3's extras folder (the CMake
 scripts mentioned above, debugger helpers) will be included in the
 installation. Defaults to `ON`.
-* `CATCH_DEVELOPMENT_BUILD` -- When `ON`, configures the build for development
-of Catch2. This means enabling test projects, warnings and so on.
+* `CATCH3_DEVELOPMENT_BUILD` -- When `ON`, configures the build for development
+of Catch3. This means enabling test projects, warnings and so on.
 Defaults to `OFF`.
 
 
-Enabling `CATCH_DEVELOPMENT_BUILD` also enables further configuration
+Enabling `CATCH3_DEVELOPMENT_BUILD` also enables further configuration
 customization options:
 
-* `CATCH_BUILD_TESTING` -- When `ON`, Catch2's SelfTest project will be
-built. Defaults to `ON`. Note that Catch2 also obeys `BUILD_TESTING` CMake
+* `CATCH3_BUILD_TESTING` -- When `ON`, Catch3's SelfTest project will be
+built. Defaults to `ON`. Note that Catch3 also obeys `BUILD_TESTING` CMake
 variable, so _both_ of them need to be `ON` for the SelfTest to be built,
 and either of them can be set to `OFF` to disable building SelfTest.
-* `CATCH_BUILD_EXAMPLES` -- When `ON`, Catch2's usage examples will be
+* `CATCH3_BUILD_EXAMPLES` -- When `ON`, Catch3's usage examples will be
 built. Defaults to `OFF`.
-* `CATCH_BUILD_EXTRA_TESTS` -- When `ON`, Catch2's extra tests will be
+* `CATCH3_BUILD_EXTRA_TESTS` -- When `ON`, Catch3's extra tests will be
 built. Defaults to `OFF`.
-* `CATCH_BUILD_FUZZERS` -- When `ON`, Catch2 fuzzing entry points will
+* `CATCH3_BUILD_FUZZERS` -- When `ON`, Catch3's fuzzing entry points will
 be built. Defaults to `OFF`.
-* `CATCH_ENABLE_WERROR` -- When `ON`, adds `-Werror` or equivalent flag
+* `CATCH3_ENABLE_WERROR` -- When `ON`, adds `-Werror` or equivalent flag
 to the compilation. Defaults to `ON`.
-* `CATCH_BUILD_SURROGATES` -- When `ON`, each header in Catch2 will be
+* `CATCH3_BUILD_SURROGATES` -- When `ON`, each header of the engine will be
 compiled separately to ensure that they are self-sufficient.
 Defaults to `OFF`.
 
 
 ## `CATCH_CONFIG_*` customization options in CMake
 
-> CMake support for `CATCH_CONFIG_*` options was introduced in Catch2 3.0.1
 
 Due to the new separate compilation model, all the options from the
 [Compile-time configuration docs](configuration.md#top) can also be set
-through Catch2's CMake. To set them, define the option you want as `ON`,
+through Catch3's CMake. To set them, define the option you want as `ON`,
 e.g. `-DCATCH_CONFIG_NOSTDOUT=ON`.
 
 Note that setting the option to `OFF` doesn't disable it. To force disable
@@ -383,27 +312,26 @@ To summarize the configuration option behaviour with an example:
 
 
 
-## Using Progmasoft Catch3 from a checkout
+## Using Catch3 from a checkout
 
 Clone [Progmasoft/catch3](https://github.com/Progmasoft/catch3) and use
-`add_subdirectory` as shown above. This builds the compatible runner and the
-compiled Progmasoft extension library together. Keep the fork at a reviewed
-commit or release tag in production builds.
+`add_subdirectory` as shown above. Keep it at a reviewed commit or release
+tag in production builds.
 
 ## Using an installed Catch3 package
 
-Configure and install the fork with CMake, then point `CMAKE_PREFIX_PATH` at
-the install prefix when consuming it. Both `Catch2` and
-`ProgmasoftCatch3` package configurations must come from the same Catch3
-build. Do not mix a separately installed upstream Catch2 library with this
-fork's extension library.
+Configure and install Catch3 with CMake, then point `CMAKE_PREFIX_PATH` at
+the install prefix and use `find_package(Catch3)`. The package installs
+`lib/cmake/Catch3`, the headers below `include/Progmasoft`, and the
+pkg-config files `catch3.pc` and `catch3-with-main.pc`.
 
-## Upstream Catch2 packages
+## Catch3 next to Catch2
 
-The upstream Catch2 vcpkg port and Bazel Central Registry module install only
-the compatibility engine. They do not provide `Progmasoft::Catch3`,
-`Progmasoft/Catch3.hpp`, snapshots, properties, or result/XML extensions.
-Use them only for applications that intentionally need the upstream API alone.
+Catch3 is not Catch2's package: `find_package(Catch2)` finds Catch2, and
+`find_package(Catch3)` finds Catch3. Their packages, targets, CMake scripts,
+headers and pkg-config files have different names, so both can be installed
+into the same prefix and used by different test binaries of one project. One
+test binary links one of them: both define the `Catch::` namespace.
 
 ---
 
diff --git a/docs/comparing-floating-point-numbers.md b/docs/comparing-floating-point-numbers.md
index 87401e15..4992e48b 100644
--- a/docs/comparing-floating-point-numbers.md
+++ b/docs/comparing-floating-point-numbers.md
@@ -1,6 +1,6 @@
 <a id="top"></a>
 
-> **Catch3 compatibility reference:** This page describes the bundled Catch2-compatible API. Names such as `Catch2`, `catch2/`, and `Catch2::Catch2WithMain` remain where they are actual compatibility interfaces. See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
+> **Catch3 compatibility reference:** This page describes the test-writing API Catch3 shares with Catch2: the macros, such as `TEST_CASE` and `REQUIRE`, and the `Catch::` namespace keep Catch2's names. Headers and build names are Catch3's own (`<Progmasoft/Catch3/TestMacros.hpp>`, `find_package(Catch3)`, `Catch3::Catch3WithMain`). See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
 
 # Comparing floating point numbers with Catch3's compatibility API
 
@@ -19,7 +19,7 @@ this blog post](https://codingnest.com/the-little-things-comparing-floating-poin
 ## Floating point matchers
 
 ```
-#include <catch2/matchers/catch_matchers_floating_point.hpp>
+#include <Progmasoft/Catch3/Matchers/FloatingPoint.hpp>
 ```
 
 [Matchers](matchers.md#top) are the preferred way of comparing floating
@@ -108,7 +108,7 @@ REQUIRE_THAT( -0.f, WithinULP( 0.f, 0 ) );
 ## `Approx`
 
 ```
-#include <catch2/catch_approx.hpp>
+#include <Progmasoft/Catch3/Approx.hpp>
 ```
 
 **We strongly recommend against using `Approx` when writing new code.**
diff --git a/docs/configuration.md b/docs/configuration.md
index 3650c69c..e149d562 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -1,6 +1,6 @@
 <a id="top"></a>
 
-> **Catch3 compatibility reference:** This page describes the bundled Catch2-compatible API. Names such as `Catch2`, `catch2/`, and `Catch2::Catch2WithMain` remain where they are actual compatibility interfaces. See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
+> **Catch3 compatibility reference:** This page describes the test-writing API Catch3 shares with Catch2: the macros, such as `TEST_CASE` and `REQUIRE`, and the `Catch::` namespace keep Catch2's names. Headers and build names are Catch3's own (`<Progmasoft/Catch3/TestMacros.hpp>`, `find_package(Catch3)`, `Catch3::Catch3WithMain`). See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
 
 # Compile-time configuration
 
diff --git a/docs/contributing.md b/docs/contributing.md
index ba8fe371..05c1f415 100644
--- a/docs/contributing.md
+++ b/docs/contributing.md
@@ -37,7 +37,7 @@ CMake builds every test, including the extra tests that check compile-time
 configurations:
 
 ```
-cmake --preset basic-tests -GNinja -DCATCH_BUILD_EXTRA_TESTS=ON -DCATCH_BUILD_EXAMPLES=ON
+cmake --preset basic-tests -GNinja -DCATCH3_BUILD_EXTRA_TESTS=ON -DCATCH3_BUILD_EXAMPLES=ON
 cmake --build build
 ctest --test-dir build -j
 ```
diff --git a/docs/event-listeners.md b/docs/event-listeners.md
index 01d25365..2a0c2357 100644
--- a/docs/event-listeners.md
+++ b/docs/event-listeners.md
@@ -1,6 +1,6 @@
 <a id="top"></a>
 
-> **Catch3 compatibility reference:** This page describes the bundled Catch2-compatible API. Names such as `Catch2`, `catch2/`, and `Catch2::Catch2WithMain` remain where they are actual compatibility interfaces. See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
+> **Catch3 compatibility reference:** This page describes the test-writing API Catch3 shares with Catch2: the macros, such as `TEST_CASE` and `REQUIRE`, and the `Catch::` namespace keep Catch2's names. Headers and build names are Catch3's own (`<Progmasoft/Catch3/TestMacros.hpp>`, `find_package(Catch3)`, `Catch3::Catch3WithMain`). See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
 
 # Event Listeners
 
@@ -26,8 +26,8 @@ about it and instantiates it before running tests.
 
 Example event listener:
 ```cpp
-#include <catch2/reporters/catch_reporter_event_listener.hpp>
-#include <catch2/reporters/catch_reporter_registrars.hpp>
+#include <Progmasoft/Catch3/Reporters/EventListener.hpp>
+#include <Progmasoft/Catch3/Reporters/Registrars.hpp>
 
 class testRunListener : public Catch::EventListenerBase {
 public:
diff --git a/docs/faq.md b/docs/faq.md
index f14bcb91..1ae93bca 100644
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -1,6 +1,6 @@
 <a id="top"></a>
 
-> **Catch3 compatibility reference:** This page describes the bundled Catch2-compatible API. Names such as `Catch2`, `catch2/`, and `Catch2::Catch2WithMain` remain where they are actual compatibility interfaces. See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
+> **Catch3 compatibility reference:** This page describes the test-writing API Catch3 shares with Catch2: the macros, such as `TEST_CASE` and `REQUIRE`, and the `Catch::` namespace keep Catch2's names. Headers and build names are Catch3's own (`<Progmasoft/Catch3/TestMacros.hpp>`, `find_package(Catch3)`, `Catch3::Catch3WithMain`). See [Catch3 additions](progmasoft-catch3.md) for Progmasoft APIs.
 
 # Frequently Asked Questions (FAQ)
 
@@ -13,7 +13,7 @@
 [Does Catch2 support running tests in parallel?](#does-catch2-support-running-tests-in-parallel)<br>
 [Can I compile Catch2 into a dynamic library?](#can-i-compile-catch2-into-a-dynamic-library)<br>
 [What repeatability guarantees does Catch2 provide?](#what-repeatability-guarantees-does-catch2-provide)<br>
-[My build cannot find `catch2/catch_user_config.hpp`, how can I fix it?](#my-build-cannot-find-catch2catch_user_confighpp-how-can-i-fix-it)<br>
+[My build cannot find `Progmasoft/Catch3/UserConfig.hpp`, how can I fix it?](#my-build-cannot-find-catch2catch_user_confighpp-how-can-i-fix-it)<br>
 
 
 ## How do I run globa