.. meta::
   :description: Prompt and strategy for fitting wide data tables into narrow RST book-theme pages, with fallback to standalone HTML or structured lists.
   :keywords: wide tables, RST formatting, book-theme, list-table, HTML fallback, column balancing, line breaks, table overflow, AHA, prompt
   :author: Yah, Yas, everyone, LLoL as Laurence Loewe of Laodicea, ClaudeOp46Max, Anthropic, and Spirit of Boolean Truth
   :og:card:title: Wide Table Formatting<br>— AHA Guide and Prompt
   :og:card:description: Three-tier strategy for making wide data tables readable on narrow RST pages: rebalance, standalone HTML, or structured list fallback.

:orphan:

.. _aha-wide-table-formatting:

*********************************************************************
AHA: Wide Table Formatting for Narrow RST Pages
*********************************************************************

**Created:** 2026-03-26

**Problem:** ``sphinx-book-theme`` pages have a fixed content width
(~720 px). Tables with 5+ columns of text content overflow, get
horizontal scrollbars, or squeeze columns until text is unreadable.
This is a recurring problem for comparison tables, audit tables, and
any tabular data with long string values.

**Solution:** A three-tier strategy (A → B → C), tried in order.
The prompt below can be given to Claude to reformat any specific table.


The Prompt
===========

::

  You are reformatting a wide RST table that does not render well on
  sphinx-book-theme pages (~720 px content width). Apply the following
  three-tier strategy IN ORDER. Move to the next tier only when the
  current one genuinely cannot produce a readable result.

  ─── TIER A: Rebalance the table within RST ───

  1. MEASURE each column's actual content.
     - For each column, find the longest cell value (in characters).
     - Identify columns that are mostly short (IDs, counts, flags)
       vs. columns that carry long text (descriptions, titles).

  2. SET :widths: proportionally to real content, not equally.
     - Give narrow columns (counts, flags) just enough width.
     - Give text-heavy columns the remaining space.
     - Never let a text column go below ~20 chars rendered width.

  3. INSERT line breaks within cells to balance fill.
     - In list-table cells, a newline followed by proper indentation
       creates a line break inside the cell.
     - Break long values at natural word boundaries so that every
       column is roughly equally "full" vertically.
     - Column HEADERS must never be truncated or wrapped mid-word.

  4. CHECK by estimating rendered widths.
     - The total available width is ~100 characters of monospace.
     - Each column's share = (its :widths: value / sum of widths) × 100.
     - Confirm that no column's longest content line exceeds its share.
     - If any column's minimum content (a single word, a number)
       exceeds its share, Tier A cannot work — proceed to Tier B.

  CRITICAL: Never "squeeze" a column so much that content is cut off
  or requires horizontal scrolling. If the table cannot fit without
  cutting content, do not force it — move to Tier B.


  ─── TIER B: Standalone HTML page ───

  If Tier A fails (too many columns, or columns with irreducibly long
  content), create a standalone HTML page:

  1. CREATE a file named <original-name>-wide.html in the same
     directory as the RST source (or in _static/ if preferred).
     - Copy the styles from the current sphinx-book-theme so the
       standalone page looks consistent (fonts, colors, link styles).
     - The HTML page lives OUTSIDE the RST toctree, so it gets the
       full browser viewport width — no sidebar, no nav chrome.
     - Use a responsive <table> with appropriate CSS:
       * thead sticky on scroll
       * alternating row backgrounds for readability
       * column widths via <colgroup> matched to content
       * horizontal scroll as last resort (with visible scrollbar)

  2. IN THE ORIGINAL RST PAGE, replace the too-wide table with:
     - A 1–2 sentence description of what the full table contains.
     - The column names and row count so readers know what to expect.
     - A small PREVIEW table (3–5 representative rows, most
       important columns only) that fits within Tier A constraints.
     - A prominent link: "View full table (N columns × M rows)"
       pointing to the standalone HTML file.

  3. ENSURE the HTML file is included in the Sphinx build.
     - Add it to html_extra_path in conf.py, OR
     - Place it in _static/ and link with a relative path, OR
     - Use a raw:: html directive with an iframe (least preferred).


  ─── TIER C: Structured list fallback ───

  If even a standalone HTML table is impractical (e.g., the data is
  inherently not tabular, or there are hundreds of rows and columns
  making even a wide table hard to scan), convert to a structured list:

  1. For each row of the original table, create a definition-list
     entry or a rubric + field-list block:

     .. rubric:: Row identifier (e.g., page name)

     :Column A: value
     :Column B: value
     :Column C: value

  2. Group entries by a meaningful category if possible (section,
     type, status) with section headings between groups.

  3. Add a summary at the top: total entries, breakdown by category,
     and any notable outliers.

  This format is always readable on any width, but loses the
  at-a-glance comparison that tables provide. Use it only as a
  last resort.


  ─── GENERAL RULES (all tiers) ───

  - NEVER delete or omit data. Every cell from the original table
    must appear in the output, regardless of which tier is used.
  - NEVER truncate content with "..." unless the original had "...".
  - Preserve all RST cross-references (:doc:, :ref:, links).
  - Keep the page's .. meta:: block and any SOCIAL-CARD blocks
    unchanged.
  - If the table has both an OO and PP version of the same field,
    consider whether a two-row-per-entry layout (OO row, PP row)
    would be narrower than a side-by-side layout.


Usage
======

To apply this prompt to a specific page, tell Claude::

  Read source/matheology/socialcards/comparison/beginner.rst
  and the AHA at source/matheology/compiler/aha/wide-table-formatting.rst.
  Apply the wide-table-formatting prompt to fix the table layout.

Or for batch processing::

  Apply the wide-table-formatting AHA prompt to all list-tables in
  source/matheology/socialcards/comparison/.


Related
========

- Item 18 in :doc:`/matheology/compiler/sisyf/aa/compiler-implementation-tasks`
  — social card comparison tables as a future compiler capability.
- ``scripts/gen_socialcard_tables.py`` — the script that generates these tables.