[johnml1135]

Start here: docs/formats/README.md, the index. It lists every format SIL.TextEditing reads or writes, with its purpose, file extension or clipboard name, and whether it is shipped or planned.

This PR adds user-facing format documentation in docs/formats/:

• fieldworks-markdown.md: the FieldWorks Markdown profile of Pandoc Markdown. It covers the front matter, runs and writing systems, classes and attribute order, property keys, quoting, styles, empty and special paragraphs, divs, the five link forms and project paths, pictures, glossed examples, escapes, NFD/NFC, limits, the unsupported Pandoc constructs and the Pandoc reader flags.
• record-files.md: the YAML frame and its keys, quoting, | and |-, the body, partial files, the schema as data, and the JSON Schema export (contentMediaType, x-fieldworks-blocks).
• clipboard.md: the forms and their ids, copy, paste order, the writing-system rule, Copy as and backends. Word HTML/RTF (R-3, Q65–Q72) and tables (R-4, Q73–Q79) are in sections marked planned.
• tables.md: how tables are stored and written today, and the planned real-tables design.
• findings.md: every finding id (fwmd.*, fwmd.yaml.*, fwmd.record.*, textediting.lcm.*) with its severity, meaning, usual fix and a fixture case.

Checkable. Every example is copied from a conformance fixture, and FormatDocsTests (in SIL.TextEditing.Markdown.Tests) keeps the docs honest:

• every fwmd.*/textediting.* id literal in src must have a row in findings.md, and every id in a table of findings.md or tables.md must still be in src;
• every <!-- fixture marker must be well-formed, or the test fails;
• each example marked <!-- fixture: <file> | <case name> | markdown|canonical|file --> must equal that case's text;
• each <!-- fixture-excerpt: <file> --> block must be part of that fixture file.

No fixture cases were added and no library code changed. The README gets one line that links to the index.

Code compared with the older spec (be90c389b) and with code comments

Where they differ, the docs describe the code.

• The spec's gdr.* ids are now fwmd.*. gdr.abstract.block-syntax is now fwmd.field.block-syntax. gdr.ws.defaults-changed is retired, and the front matter's defaults win.
• Spellings: {v} became .v, {empty} became []{.empty}, cs=/style= became custom-style=, cs=none became .nostyle, and broken became .broken. [[kind:Name]] and link= became path links in five forms. fw:picture/ became /files/pictures/...{guid=}. \uXXXX and s6="..." became character references and sNx hex. Bare values gained : and /, and keys may hold -. One-line fences became Pandoc divs. The table styles are named by the host.
• Stale comments (the code is right):
  • RecordFileWriter's summary says every rich value is |-, but R-8 writes | for fields of paragraphs.
  • RecordField.ContentMediaType says references are text/x-fieldworks-markdown, but the code returns -inline.
  • MarkdownDiagnosticIds says link.ambiguous and link.broken are reported by hosts, but ObjectBuilder reports both.
  • ADR 0029 and the README say the Markdown library "will provide" the clipboard form. None ships yet.

Next: the FieldWorks Markdown clipboard form (#168) and the fwmd CLI (#161); file issues for the stale comments.

🤖 Generated with Claude Code