docs: 112 snippet tags are compiled but never included in any page

[alandefreitas]

doc/modules/ROOT/examples/unit/snippets.cpp defines tags via // tag::NAME[] / // end::NAME[] so they can be included in AsciiDoc pages with include::example$unit/snippets.cpp[tag=NAME,indent=0]. The snippets are also compiled and run as part of the unit-test suite, so they exercise the library and stay in sync with the API.

Today, 112 tags are defined and tested but never referenced by any documentation page. They are pure dead weight: they contribute to compile time and test execution but no reader ever sees them.

How to reproduce

From the repo root:

comm -23 \
  <(grep -hoE '// tag::[A-Za-z_0-9]+\[\]' doc/modules/ROOT/examples/unit/snippets.cpp \
     | sed 's|// tag::||; s|\[\]||' | sort -u) \
  <(grep -rhoE 'tag=[A-Za-z_0-9]+' doc/modules/ROOT/pages/ \
     | sed 's|tag=||' | sort -u)

Findings

Counts grouped by prefix:

count	prefix
22	snippet_parsing_path_*
21	snippet_parsing_authority_*
16	snippet_parsing_query_*
15	snippet_modifying_path_*
7	snippet_parsing_fragment_*
5	snippet_parsing_url_*
5	snippet_components_2*
4	snippet_parse_*
4	snippet_modifying_[1-4]
2	snippet_parsing_scheme_*
2	snippet_headers_*
2	snippet_customization_*
2	snippet_compound_elements_0*
2	snippet_accessing_3*
1	snippet_using_static_pool_1
1	snippet_decoding_2
1	code_charset_1

The largest clusters look like material for dedicated "Parsing the path / authority / query / fragment" and "Modifying the path" tutorial sections that were either removed or never written. The compiled snippets are now orphans.

Motivation

This is the structural cause of #998. The doc page said "The following example parses a string literal containing a URI" but the included snippet (code_urls_parsing_1) is only the string_view declaration; the actual parse_uri call is in code_urls_parsing_2, which was misused in a different section that claimed to show "two equivalent statements". The transposition went unnoticed because:

1. There is no build-time check that page prose matches snippet content.
2. There is no build-time check that defined tags are ever consumed.

Even fixing #998 by hand leaves the underlying invisibility: any future rename, refactor, or rewrite can transpose another pair the same way.

Proposed fix

Two independent steps:

• Resolve the existing orphans
• Add a CI lint