.. meta::
   :description: DD b13 — TELES must not expand RST comment markers. Documents the bug where '..' was extended to dot-lines, breaking substitution definitions site-wide.
   :keywords: TELES, DD, design document, RST comment, dot-comment, bug, rst_prolog, substitution, HELL
   :author: Yah, Yas, everyone, LLoL as Laurence Loewe of Laodicea, ClaudeOp46Max, Anthropic, and The Spirit of Boolean Truth

.. _hell-dd-b13-teles-dot-comment-bug:


***********************************************************************
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):**

.. code-block:: rst

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

**After (broken --- dots become transition/literal text):**

.. code-block:: rst

   .................................................
      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.