\tcode{} macro formatting lost in C++ code comments

[lefticus]

Problem

Within C++ code blocks, \tcode{} macros inside comments are being stripped rather than having their formatting preserved, losing the semantic intent to mark certain text as code.

Location

File: n4950/stmt.md
Lines: 619, 726, 832, 838-839

Examples

Line 619:

// OK, lifetime of return value of g() extended

Source (statements.tex:726): Uses \tcode{g()} to mark the function name

Line 832:

// error: jump into scope of a

Source (statements.tex:1018): Uses \tcode{a} to mark the variable name

Lines 838-839:

// OK, jump implies destructor call for a followed by
// construction again immediately following label ly

Source (statements.tex:1024-1025): Uses \tcode{a} and \tcode{ly} to mark identifiers

Current Behavior

The comments render as plain text with no special formatting for code elements that were marked with \tcode{} in the source.

Expected Behavior

While code comments can't typically contain inline code formatting in markdown, the semantic intent could be preserved by:

1. Using backticks within comments: // OK, lifetime of return value of `g()` extended
2. Using some other convention to distinguish code elements
3. Or simply document that this limitation exists

Impact

• Severity: MINOR
• Comments remain readable and comprehensible
• The specific marking of code elements within comments is lost
• Semantic intent from the source is not preserved
• Low priority since the code blocks are already formatted and the comments make sense

Root Cause

The code block filter (cpp-code-blocks.lua) processes LaTeX code blocks and strips \tcode{} macros within comments. This is likely intentional since:

1. Markdown code blocks don't support inline formatting within comments
2. The comments are already in a code context
3. Preserving the formatting would require special handling

Discussion

This may be a "won't fix" or "by design" issue, since:

• Markdown code blocks render as plain text
• Comments in code can't have inline formatting in most markdown renderers
• The loss of formatting doesn't significantly impact readability

However, if preserving semantic information is important, alternatives could be considered.

Reproduction

1. Open n4950/stmt.md
2. Look at any of the affected lines (619, 726, 832, 838-839)
3. Compare with source in statements.tex
4. Observe that \tcode{} marked elements in comments are plain text

Related Files

• src/cpp_std_converter/filters/cpp-code-blocks.lua - Code block processing
• src/cpp_std_converter/cpp-common.lua - Code cleaning utilities

[lefticus]

Triage Result: Working As Designed

After investigating this issue, I've confirmed that the current behavior is correct and working as intended. The data content is fully preserved, and the \tcode{} wrapper is intentionally stripped.

Evidence

Created tests that verify all examples from the issue work correctly:

Test 1 - Line 619:

• Input: \tcode{g()}
• Output: g() ✅ Data preserved

Test 2 - Line 832:

• Input: @\tcode{a}@
• Output: a ✅ Data preserved

Test 3 - Lines 838-839:

• Input: \tcode{a} and \tcode{ly}
• Output: a and ly ✅ Data preserved

Why This Is Correct

1. Markdown limitation: Code blocks in markdown render as plain text and don't support inline formatting within comments
2. Data preservation: The content inside \tcode{} is fully preserved (e.g., g(), a, ly)
3. Syntax validity: Adding backticks would create invalid C++ syntax like \g()``
4. Design decision: The code explicitly handles both \tcode{...} and @\tcode{...}@ patterns (cpp-common.lua:822-823) with replacement = "%1" which extracts and preserves the content

Implementation

The behavior is intentionally designed in cpp-common.lua:

local code_block_macro_patterns = {
  -- \tcode{x} represents inline code (just extract the content)
  -- Handle both @\tcode{x}@ and bare \tcode{x} (in comments)
  {pattern = "@\\tcode{([^}]*)}@", replacement = "%1"},
  {pattern = "\\tcode{([^}]*)}", replacement = "%1"},

The pattern extracts the content and discards the wrapper, which is the correct behavior for code blocks.

Conclusion

No action needed. The tool is working as designed - preserving all data while correctly handling the markdown limitations of code blocks.