DD b13 — TELES Must Not Expand RST Comment Markers#

Date: 2026m04d04

Status: Fixed. Rule codified here for all future TELES implementations.

The Bug#

On 2026m04d04, the TELES title-underline fixer script (teles-fix-titles.py, stored in hell/ll/other/b/14/) was run to fix 138 “Title underline too short” warnings. The script correctly extended heading underline/overline characters to match title width. However, it also matched .. (two dots) as a heading line — because . was in the set of valid RST heading characters — and extended it to match the indented comment text that followed.

Before (correct RST comment):

..
   Language-INDEPENDENT substitution definitions.
   Loaded via rst_prolog in conf.py (not via include).

After (broken — dots become transition/literal text):

.................................................
   Language-INDEPENDENT substitution definitions.
   Loaded via rst_prolog in conf.py (not via include).

Why This Was Catastrophic#

The rst_prolog mechanism in conf.py reads _templates/include-file/rst-dict.rst and rst-dict-en.rst and prepends their content to every RST file. These files use .. comment blocks to hold human-readable documentation between the substitution definitions.

When .. was expanded to ....., the comment syntax broke:

  • .. + indented text = RST comment (invisible in output)

  • ..... + indented text = transition marker + block quote (visible in output)

The result: every page on the site displayed the raw comment text (“Language-INDEPENDENT substitution definitions…”) as visible content. 8 files were affected: 5 template include files and 3 content files.

The Rule#

TELES scripts MUST treat lines shorter than 3 characters as non-heading lines. The RST spec requires heading underlines to be at least as long as the title text, which is always at least 1 character, but the critical safety threshold is 3:

  • .. (2 chars) = RST comment marker. NEVER touch.

  • ... (3 chars) = could be a heading underline for a 1–3 char title. Safe to extend.

The fix in teles-fix-titles.py was changing the minimum length check in is_heading_line() from < 1 to < 3.

Files Affected#

Damaged by the bug (all restored):

  • _templates/include-file/rst-dict.rst (5 comment markers)

  • _templates/include-file/rst-dict-en.rst (3 comment markers)

  • _templates/include-file/rst-dict-definitions-en.rst (4 comment markers)

  • _templates/include-file/page-prefix.rst (1 comment marker)

  • _templates/include-file/rst-code-definitions.rst (1 comment marker)

  • _templates/include-file/footer/cta/none.rst (1 comment marker)

  • _templates/include-file/footer/form-open-std/ff-email-template.rst (1)

  • _templates/include-file/footer/form-shut-std/ff-email-template.rst (1)

  • action/call/fund-researchcity.rst (5 comment markers)

  • action/index.rst (1 comment marker, also had legitimate title fix)

  • matheology/jub/llog/index.rst (1 comment marker, also had legitimate :doc: fix)

Lesson#

RST comment syntax (.. + indented text) is visually similar to a short heading underline. Any automated RST formatter must explicitly exclude the 2-character .. pattern. This is especially dangerous when the formatted files are loaded via rst_prolog because the breakage affects every page on the site, not just the modified file.