.. meta::
   :description: Why the compiler cannot auto-break equations, how to use LaTeX line breaks and alignment anchors in RST math blocks, and where to decide them.
   :keywords: LaTeX, equations, RST math block, line breaks, alignment anchor, SISYF compiler, PoR source, matheology, Sphinx, auto-break, checklist
   :author: Yah, Yas, everyone, LLoL as Laurence Loewe of Laodicea, ClaudeOp46Max, Anthropic, and Spirit of Boolean Truth
   :og:card:title: LaTeX Equations —<br>Author Guide for Math Blocks
   :og:card:description: Line breaks and alignment anchors in RST math blocks must be set in the PoR source. The compiler copies them faithfully to every depth view.

.. SOCIAL-CARD-QUALITY-COMPARE --- OO (default effort) vs PP (max effort), 2026-03-26
   OO :description: How to write and format LaTeX equations in matheology RST pages, including line breaks, alignment anchors, and multi-line formulas.
   OO :keywords: LaTeX, equations, math, RST, formatting, line breaks, alignment, compiler, matheology, AHA, Sphinx
   OO :og:card:title: LaTeX Equations in<br>Matheology Pages
   OO :og:card:description: How RST math blocks work, how to break long equations across lines, and how to use alignment anchors in compiled pages.
   PP :description: Why the compiler cannot auto-break equations, how to use LaTeX line breaks and alignment anchors in RST math blocks, and where to decide them.
   PP :keywords: LaTeX, equations, RST math block, line breaks, alignment anchor, SISYF compiler, PoR source, matheology, Sphinx, auto-break, checklist
   PP :og:card:title: LaTeX Equations —<br>Author Guide for Math Blocks
   PP :og:card:description: Line breaks and alignment anchors in RST math blocks must be set in the PoR source. The compiler copies them faithfully to every depth view.

.. SOCIAL-CARD-REVIEW --- generated by Claude Opus 4.6, 2026-03-26
   dv_ClaOp46_PP_2026m03d26 --- max-effort rewrite, read full page.
   :description: 146 chars | :og:card:title: 44 chars (excl <br>)
   - [ ] PP title more compelling than OO title
   - [ ] PP description more accurate than OO description
   - [ ] Description hooks without misleading
   - [ ] Keywords specific to this page's actual content
   - [ ] No language rule violations
   - [ ] Character counts verified

.. _compiler-aha-equations:

*********************************************************************
AHA: LaTeX Equations in Matheology Pages
*********************************************************************

.. note::

   **Created:** Phase 2I-4 (2026-03-25).


.. contents:: On this page
   :depth: 2
   :local:


----


1. How RST math blocks work
==============================

The ``.. math::`` directive passes its content to LaTeX for rendering.
RST-level line breaks (pressing Enter in your editor) are **ignored** ---
LaTeX concatenates all lines into a single expression. This means:

.. code-block:: rst

   .. math::

      \forall x \in A :
      P(x) \wedge Q(x)

renders identically to:

.. code-block:: rst

   .. math::

      \forall x \in A : P(x) \wedge Q(x)

Both produce one long horizontal line. If the formula is wider than the
page, the reader gets an ugly horizontal scrollbar.


2. How to break long equations
================================

Use explicit LaTeX markers inside the ``.. math::`` block:

- ``\\`` --- line break (start a new line)
- ``&`` --- alignment anchor (lines align at the ``&`` position)

Example from the PoR source for a19:

.. code-block:: rst

   .. math::

      \forall t\; \exists!\, h^* \in H :\;
      & \text{MaxCausalInfluence}(h^*, t, W_{\text{future}}) \\
      & \wedge\; \forall h \neq h^* : \\
      & \quad \text{CausalInfluence}(h, t, W_{\text{future}})
        < \text{CausalInfluence}(h^*, t, W_{\text{future}})

The ``&`` at the start of each continuation line makes them align neatly.
The ``\\`` at the end of a line tells LaTeX to start a new one.


3. Where to make line-break decisions
=======================================

**In the PoR source file --- once.**

The PoR files (``pet/axioms.rst``, ``jub/axioms.rst``, etc.) are the
single place where a human decides where formulas should break. The
cross-model compiler then copies math blocks character-for-character
into every compiled depth view (expert, easy, etc.).

This means:

- If a formula looks right in the PoR source, it will look right
  everywhere.
- If a formula needs a line break, fix it in the PoR source and
  recompile.
- The compiler never invents line breaks and never removes them.

See the compiler spec rule at §9.3.1 (LaTeX Math Block Preservation)
in :ref:`sisyf-compiler-skill`.


4. Why the compiler cannot auto-break equations
=================================================

Three reasons:

1. **Rendered width depends on the viewer.** Browser window size, PDF
   page margins, font size --- there is no single "page width" at
   compile time.

2. **Where to break is a semantic decision.** Breaking
   ``\forall x \in A : P(x) \wedge Q(x)`` after the colon is natural;
   breaking it inside ``P(x)`` is ugly. No character-count heuristic
   handles this reliably.

3. **One source of truth.** If the compiler modified math content, the
   PoR source and compiled output would diverge. The next recompile
   would overwrite the fix, and the cycle would repeat. Keeping the
   decision in the PoR source avoids this.


5. Quick checklist for authors
================================

- Write your ``.. math::`` block in the PoR source.
- If the formula fits on one line comfortably, leave it as-is.
- If it overflows, add ``\\`` at logical break points and ``&`` for
  alignment.
- Use ``\bigl(`` / ``\bigr)`` for brackets that span multiple terms
  (rather than plain ``(`` / ``)``).
- Build (``make html``) and check the rendered page.
- The fix propagates to all compiled views on the next compile run.