Broken cross-references with REF: prefix

[lefticus]

Issue

Some cross-references are broken and showing raw "REF:" prefix instead of resolving to actual links.

Affected Files

• support.md (2 instances)

Examples

From support.md:

REF:some.section.label

Should be a proper markdown link like:

[some.section.label](#some-section-label)

Severity

MAJOR - Broken cross-references impede navigation

Root Cause

Likely a failure in the label resolution phase of conversion, possibly due to:

• Missing label definitions
• Cross-file reference issues
• Label indexer not finding the target

Related Issues

• Cross-reference and linking issues

Context

These appear in the language support library documentation.

[lefticus]

Comprehensive Investigation Results

After a thorough investigation of all annexes and standard files, this issue is significantly more widespread than initially reported. There are two distinct patterns of unresolved cross-references across multiple files and versions.

---

Pattern 1: @@REF:label@@ (Footnote Cross-References)

These appear in footnote definitions and should be converted to proper wikilinks.

n4950 (C++23) - 6 instances

support.md (1 instance):

• Line 1991 (footnote [^29]): main function@@REF:basic.start.main@@ contains no

input.md (5 instances):

• Footnote [^16]: basic_streambuf in this Clause@@REF:stringbuf,filebuf@@, a
• Footnote [^20]: ws(basic_istream&)``@@REF:istream.manip@@.
• Footnote [^21]: dec(ios_base&)``@@REF:basefield.manip@@.
• Footnote [^32]: endl(basic_ostream&)``@@REF:ostream.manip@@.
• Footnote [^33]: dec(ios_base&)``@@REF:basefield.manip@@.

n4659 (C++17) - 11 instances

future.md (Annex D - 3 instances):

• Lines 1911-1912 (footnote [^1]):
  • <cstring> (@@REF:cstring.syn@@)
  • <climits> (@@REF:climits.syn@@)
• Line 1918 (footnote [^3]): <cstring> (@@REF:cstring.syn@@)

input.md (7 instances):

• Similar footnote cross-references as n4950

language.md (1 instance)

---

Pattern 2: Plain REF:label (Code Comment Cross-References)

These appear in C++ code blocks and inline code comments and should be converted to wikilinks.

n4950 (C++23) - 8 instances

support.md (1 instance):

• Line 1991: // p does not point to new objectREF:basic.life because its type is const

utilities.md (3 instances):

• Line 1963: // see REF:func.require
• Line 4376: // see REF:func.require
• Line 4382: // see REF:func.require

iterators.md (2 instances):

• Line 2342: // REF:range.prim.size
• Line 2348: // REF:range.access

thread.md (2 instances):

• Line 1013: // for invoke, see REF:func.invoke
• Line 1249: // for invoke, see REF:func.invoke

n4659 (C++17) - 4 instances

Similar patterns in code comments.

---

Expected Behavior

For @@REF:label@@ in footnotes:

`<cstring>` (@@REF:cstring.syn@@)

Should become:

`<cstring>` [[cstring.syn]]

For plain REF:label in code comments:

// see REF:func.require

Should become:

// see [[func.require]]

---

Total Impact

• n4950: 14 total instances (6 footnotes + 8 code comments)
• n4659: 15 total instances (11 footnotes + 4 code comments)
• Affected files: support.md, input.md, utilities.md, iterators.md, thread.md, language.md, future.md (Annex D)

---

Root Cause

Both patterns likely stem from the label indexer/cross-reference resolution phase failing to resolve certain types of references:

1. Cross-references within footnotes may not be processed by the label indexer
2. Cross-references in code comments may be skipped during link resolution
3. Some reference formats may not match the expected patterns in label_indexer.py

---

Severity

MAJOR - Significantly more widespread than initially reported. These unresolved cross-references break navigation and make specifications harder to follow, especially in critical areas like footnotes explaining API relationships.

---

Related Context

This was discovered during QA investigation of Issue #59 (annex TOC structure). The footnote cross-reference issue affects Annex D (future.md) among other files.

[lefticus]

Fixed in commit 8c95b90. The fix:

1. REF: patterns removed: All REF: and @@REF:@@ patterns are now properly converted to wikilinks

2. Comma-separated refs split: References like [[a,b]] are now split to [[a]], [[b]]

3. Improved readability: Added space after inline code before wikilinks (e.g., `wstring` [[ref]] instead of `wstring`[[ref]])

All 664 tests pass and the fix is applied across all C++ standard versions (n3337, n4140, n4659, n4861, n4950, trunk).