[markbac]

Closes #218.

What it does

[[LISTTABLE]] tables hold what a pipe table cannot: several paragraphs, bullet and numbered lists, merged cells and blocks such as diagrams in a cell.

[[LISTTABLE: header, widths=8,52,40]]
| Step | What to do | Check |
| 1 | Fit the batteries.<br>Before you go:<br>- Firmware is current<br>  - and signed | Light flashes green. |
| 2 | Pair the node:<br>1. Hold the button.<br>2. Choose it in the app. | ^ |
| 3 | The first reading:<br>[[BLOCK: reading]] | < |

[[BLOCK: reading]]
```dot
digraph reading { rankdir=LR; Sensor -> Gateway -> Broker; }
```
[[ENDBLOCK]]

• <br> starts a paragraph, - a bullet, 1. a numbered item, and two spaces nest an item.
• < merges with the cell on the left, ^ with the cell above.
• header makes row 1 the header row; widths= sets relative column widths.
• [[BLOCK: name]] puts a diagram, picture or code from elsewhere in the same file into a cell, without a caption.

How

• Conversion (listtable.py, driven by directives.py): each table becomes a pandoc grid table, with row and column spans, while each file's directives are expanded. It runs after conditions and variables and before diagrams, so warnings name the right file and line inside includes. A wrapped word that looks like a list marker is escaped.
• listtable.lua (all formats and sites): moves block contents into their cells, without figure captions. In Word it adds a hidden bookmark so the finishing step knows a rich table.
• Word finishing (docx_post.py, docx_finish.py):
  • Rich and headerless tables keep pandoc's widths in a fixed layout, and their body rows may split across pages.
  • Only a real header row is formatted and repeated.
  • Pictures are made no wider than their cell.
  • Ordinary tables are unchanged.
• docxcompose bug, worked around: when merging into the template, docxcompose gave every list in one table the same numbering, so numbered items showed as bullets. Lists are now added one at a time.
• Import (docx_import.py): a Word table with paragraphs or lists in cells, merged cells or no header row imports as [[LISTTABLE]] with its widths. Other tables still import as pipe tables.
• Lint and check:
  • Table and block mistakes are directive problems.
  • Lint reads each cell paragraph as separate prose.
  • A caption before the marker counts.
  • Pictures and diagrams in blocks need no caption.
• Build report: a rich_tables count per source (schema updated).
• VS Code extension 2.2.0: highlights py-doc directives and {{variables}} in Markdown.
• CI: the tool-image workflow also runs on pandoc-code changes and checks the example's rich table in a Word build made with the image's pandoc.
• Docs: user guide (writing, writing documents, import, lint, projects), architecture, requirements FR-029 and FR-064 with traceability, README, and an example guide table that uses every feature.

Testing

• python -m pytest: 1961 passed, 29 skipped (pandoc 3.1.3 and Graphviz on the host).
• ruff check ., ruff format --check ., py-doc lint docs --strict, and cd examples && py-doc lint docs poster --strict are clean.
• cd editors/vscode && npm run lint && npm test: 18 passed.
• I built the example guide to Word and viewed it through LibreOffice. Merges, nested and numbered lists, and the diagram in its cell all render correctly.

Still to check by hand in Word

• A tall row splitting across a page (T-09).
• The highlight character styles, which LibreOffice does not draw.
• Header-row shading: header rows look blank in LibreOffice for ordinary tables too, so this predates the change.
• The Word build with pandoc 3.8 runs in the tool-image workflow, not locally.

---

Generated by Claude Code