docs: glitches spotted while reviewing #1304

docs/modules/ROOT/nav.adoc

@@ -26,6 +26,7 @@
 ** xref:generators/noop.adoc[No-op]
 ** xref:generators/reference.adoc[Reference]
 * Extensions
+** xref:extensions/index.adoc[Overview]
 ** xref:extensions/handlebars-extensions.adoc[Handlebars Extensions]
 ** xref:extensions/data-driven-generators.adoc[Data-Driven Generators]
 ** xref:extensions/corpus-transforms.adoc[Corpus Transforms]
@@ -40,5 +41,3 @@
 ** xref:contribute/options.adoc[]
 ** xref:contribute/codebase-tour.adoc[]
 ** xref:contribute/docs.adoc[]
-* xref:design-notes.adoc[]
-* xref:license.adoc[]

docs/modules/ROOT/pages/configuration/extraction.adoc

@@ -1,5 +1,7 @@
 = Extraction
 
+MrDocs parses {cpp} with https://clang.llvm.org/docs/LibTooling.html[Clang's libtooling API^], so anything that compiles is in the corpus, including https://en.cppreference.com/w/cpp/language/templates[templates^], https://en.cppreference.com/w/cpp/language/constraints[concepts^], https://en.cppreference.com/w/cpp/language/partial_specialization[partial specializations^], and https://en.cppreference.com/w/cpp/language/coroutines[coroutines^]. Getting a construct into the corpus is the easy part. Rendering it the way a reader expects is where the options on this page come in.
+
 The xref:configuration/filters.adoc[filters] are the gate at the front of the pipeline. They decide which symbols enter the corpus. The options on this page are the next stage: they decide how MrDocs interprets and arranges the symbols that survived the filters. Which inherited members appear on a class page, the order members are listed in, how related declarations are grouped (overload sets, SFINAE expressions, function objects), what MrDocs infers from doc comments (briefs, relations, function metadata), and the escape hatches for headers the compiler cannot find. The xref:configuration/reference.adoc#_extraction_options_reference[Extraction reference] lists every option.
 
 == Ordering members
@@ -27,7 +29,7 @@ The other sort switches (xref:configuration/reference.adoc#sort-members-ctors-1s
 
 == Overload sets
 
-A C++ overload set is many functions sharing a name. xref:configuration/reference.adoc#overloads_option[`overloads`] merges them into a single page so the reader sees the whole set at once instead of one page per signature:
+A C++ overload set is many functions sharing a name. xref:configuration/reference.adoc#overloads_option[`overloads`] merges them into a single page so the reader sees the whole set at once instead of one page per signature. MrDocs picks a canonical signature for the page title and lists each overload underneath with its own parameters. The documentation shared by the page is the union of the metadata the overloads agree on:
 
 .Example
 [source,cpp]
@@ -48,7 +50,7 @@ include::example$snippets/options/overloads/overloads.adoc[tags=!footer]
 
 == SFINAE constraints
 
-xref:configuration/reference.adoc#sfinae_option[`sfinae`] rewrites SFINAE constraints into a readable form instead of the raw `enable_if` machinery:
+A function constrained with https://en.cppreference.com/w/cpp/types/enable_if[`enable_if`^] has a different signature from its unconstrained sibling, but readers care about the constraint, not about the spelling of `typename std::enable_if<...>::type`. xref:configuration/reference.adoc#sfinae_option[`sfinae`] inspects the primary template and its specializations to recover the result type and the controlling expression, lifts the constraint into a "Requires" entry attached to the signature, and renders the return type as if the constraint were not there:
 
 .Example
 [source,cpp]
@@ -69,7 +71,7 @@ include::example$snippets/options/sfinae/sfinae.adoc[tags=!footer]
 
 == Algorithm function objects
 
-xref:configuration/reference.adoc#auto-function-objects_option[`auto-function-objects`] detects the https://en.cppreference.com/cpp/algorithm/ranges#Algorithm_function_objects[Algorithm Function Object (AFO)^] idiom and presents the variable's page as if it were a function, using the call operator's doc comment, parameters, and return type:
+An https://en.cppreference.com/cpp/algorithm/ranges#Algorithm_function_objects[Algorithm Function Object (AFO)^] is a https://en.cppreference.com/w/cpp/language/constexpr[`constexpr`^] variable of an unnamed type whose only public members are `operator()` overloads. The variable is what the caller invokes; the type is an implementation detail. xref:configuration/reference.adoc#auto-function-objects_option[`auto-function-objects`] detects the idiom and presents the variable's page as if it were a function, using the call operator's doc comment, parameters, and return type. When `operator()` is undocumented, the variable's own comment is used instead; the type's comment never is:
 
 .`include/numerics/clamp.hpp`
 [source,cpp]

docs/modules/ROOT/pages/extensions/antora.adoc

@@ -1,6 +1,6 @@
 = Antora extensions
 
-Two Antora extensions connect the xref:page$generators/adoc.adoc[Asciidoc Generator] into an Antora build. One runs Mr.Docs as a stage inside the Antora build. The other registers the resulting Mr.Docs xref:configuration/reference.adoc#tagfile_option[tagfile], so prose on the site can link to C++ symbols.
+Mr.Docs generates the reference and nothing else. Overviews, tutorials, and design notes are written by hand, as ordinary https://asciidoc.org/[AsciiDoc^] next to the generated pages, and the two halves have to be wired together. Two Antora extensions connect the xref:page$generators/adoc.adoc[Asciidoc Generator] into an Antora build. One runs Mr.Docs as a stage inside the Antora build. The other registers the resulting Mr.Docs xref:configuration/reference.adoc#tagfile_option[tagfile], so prose on the site can link to C++ symbols.
 
 [#antora-cpp-reference-extension]
 == C++ reference extension

docs/modules/ROOT/pages/extensions/as-library.adoc

@@ -6,12 +6,20 @@ A {cpp} program can also link the cpp:mrdocs[mrdocs-core] library, drive corpus
 
 == Build integration
 
-cpp:mrdocs[mrdocs-core] is exported through a CMake package config. The `breaking-changes` example below links it exactly this way:
+cpp:mrdocs[mrdocs-core] is exported through a CMake package config. Once Mr.Docs is installed, a consumer locates it with a single `find_package` call. The `breaking-changes` example does this only when it's built outside the Mr.Docs source tree, where the target isn't already defined:
 
 .`examples/library/breaking-changes/CMakeLists.txt`
 [source,cmake]
 ----
-include::example$examples/library/breaking-changes/CMakeLists.txt[tags=package;target]
+include::example$examples/library/breaking-changes/CMakeLists.txt[tag=package,indent=0]
+----
+
+The imported target is `mrdocs::mrdocs-core`. Link it like any other library: it carries the include directories, compile definitions, and transitive dependencies the consumer needs, so no extra setup is required.
+
+.`examples/library/breaking-changes/CMakeLists.txt`
+[source,cmake]
+----
+include::example$examples/library/breaking-changes/CMakeLists.txt[tag=target,indent=0]
 ----
 
 == Building a corpus

docs/modules/ROOT/pages/extensions/corpus-transforms.adoc

@@ -268,7 +268,7 @@ Notice in this example that `s.doc.sees` receives a list of polymorphic types th
 [#reading-files]
 == Reading files
 
-After being presented with the xref:design-notes.adoc[arguments for generated reference documentation], a common objection is that the prose should be mostly written by technical writers, not developers. The rationale is not to clutter the headers, and that technical writers can focus on use cases the users are interested in and dedicate themselves to long tutorials.
+After being presented with the xref:index.adoc#why-generate-from-source[arguments for generated reference documentation], a common objection is that the prose should be mostly written by technical writers, not developers. The rationale is not to clutter the headers, and that technical writers can focus on use cases the users are interested in and dedicate themselves to long tutorials.
 
 A transform extension can bridge the two by also reading documentation from external sources. While developers write documentation in code that is verifiably correct and guaranteed never to drift, a writer keeps the extra documentation alongside the project. The ghostwrite transform extension fills in each symbol's description from the corresponding file. A complete, runnable example lives at `examples/extensions/ghostwriter/`.
 

docs/modules/ROOT/pages/extensions/handlebars-extensions.adoc

@@ -128,13 +128,26 @@ Run that against a small fixture:
 include::example$snippets/extensions/override-code-block/override-code-block.cpp[]
 ----
 
-The base addons still provide every other partial; only `markup/code-block.<format>.hbs` is replaced. The rendered AsciiDoc page now shows the `Listing` caption above each synopsis block; the HTML page would carry the copy-button wrapper through the same mechanism:
+The base addons still provide every other partial; only `markup/code-block.<format>.hbs` is replaced. The rendered AsciiDoc page now shows the `Listing` caption above each synopsis block, and the HTML page wraps each synopsis block in the copy-button wrapper:
 
+[tabs]
+======
+AsciiDoc::
++
 [.adoc-preview]
 ========
 include::example$snippets/extensions/override-code-block/override-code-block.adoc[tags=!footer]
 ========
 
+HTML::
++
+.`override-code-block.html`
+[source,html]
+----
+include::example$snippets/extensions/override-code-block/override-code-block.html[]
+----
+======
+
 === Reordering the Main Template
 
 Mr.Docs provides a partial template for each symbol page that renders the synopsis, doc comment, and examples in a standard order. A common pattern used by projects is to document the description and examples first and then present the synopsis at the end of each page. Besides customizing the ordering of the sections in this main template, a few placeholders such as xref:commands/reference.adoc#cmd-see-below[`@seebelow`] need to be adapted: