From d5b9356a29f13f69517ac389bafb2efcc9668d95 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Wed, 14 Oct 2026 10:00:07 +0200 Subject: [PATCH] Record the marks and colwidth spellings in the spec, decisions, changelog and migration guide --- AGENTS.md | 1 + CHANGELOG.md | 4 ++++ MIGRATION.md | 2 ++ docs/decisions.md | 14 ++++++++++++++ todo.md | 13 ------------- 5 files changed, 21 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b1a3f17..ee5af56 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -16,6 +16,7 @@ In `docs/decisions.md`: - A list right after one of its kind takes the other marker - An empty key spells `empty` - `-0` is spelled `-0` +- A block's marks are named, and `colwidth` is a comma list - Empty markdown is a document of no blocks - Unknown nodes ride the carry - The carry fence names the node type diff --git a/CHANGELOG.md b/CHANGELOG.md index 7b36fd6..2f9046b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -66,6 +66,10 @@ - **Breaking:** `adfToLosslessMarkdown` writes a centered, uncaptioned external image whose one mark is a link holding only `href` and `title` as `[![alt](url)](href "title")`, where it wrote the `mediaSingle` directive. Convert stored markdown per `MIGRATION.md`. +- **Breaking:** `colwidth` is spelled as its widths joined by commas, `colwidth="340,420"`, where it + was a JSON array, and a block's `marks` names each mark with its attributes, + `marks="breakout{mode=wide}"`, where it was a JSON array. The JSON array stays only for a block + mark the flavour does not list. Convert stored markdown per `MIGRATION.md`. - Fix the time `adfToLosslessMarkdown` and `adfToPortableMarkdown` take on text holding a long run of `*`, `_`, `~` or backticks, or a heading ending in a long run of `#`: the time is linear in the run, and a run of 20000 `*` takes milliseconds where it took seconds. diff --git a/MIGRATION.md b/MIGRATION.md index 76bb29e..45025c9 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -67,6 +67,8 @@ function migrateMarkdown(stored: string) { | `\:` keeps a directive literal | `\!adf:` keeps a directive literal | | `:adf{json="…"}` carrying a link for its `collection`, `id` or `occurrenceKey` | `!adf:link[text]{attrs}` | | `::listBreak` between two lists of a kind | no separator: adjacent lists of a kind alternate `- ` and `* `, or `1.` and `1)` | +| `colwidth="[340,420]"` | `colwidth="340,420"` | +| `marks="[{\"attrs\":{\"mode\":\"wide\"},\"type\":\"breakout\"}]"` on a block | `marks="breakout{mode=wide}"`; the JSON array stays for a mark the flavour does not list | A colon run and `:name[` are plain text now, and `adf` an ordinary code block language; text holding an unescaped `!adf:` and a code fence whose info string opens `adf:` are claimed instead. diff --git a/docs/decisions.md b/docs/decisions.md index aa861ca..e267ace 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -100,6 +100,20 @@ holding no `content` key. A writer panel chose the spelling, 5 of 7. The grammar `-0` is spelled `-0` wherever the flavour writes a number or a JSON value, since JSON's grammar reads it back as `-0`. The grammar: `spec/flavour.md` §Block nodes and §The CommonMark blocks. +## A block's marks are named, and `colwidth` is a comma list + +2026-10-03 for `colwidth`, 5 of 7, and 2026-10-14 for `marks`, 3 of 3: writer panels of product +managers, engineers and support agents. Goal 6. Valid while ADF types these attributes as +`src/adf/` does. + +`colwidth` is its widths joined by commas, `colwidth="340,420"`, where it was a JSON array. A +block's `marks` names each mark with its `{attrs}`, in order, +`marks="indentation{level=2} fragment{localId=f1 name=\"Price list\"}"`, chosen over the escaped +JSON array and an unquoted one. All three writers first sketched a key per mark, `{align=center}`, +which loses the marks' order and can clash with the node's own attributes. A mark `src/adf/` does not +type keeps the whole array as JSON, the general form (§Readable spellings take the `try` prefix). +The grammar: `spec/flavour.md` §Block nodes. + ## Empty markdown is a document of no blocks 2026-10-03, a writer panel and the maintainer. Goals 1 and 6. Valid while ADF's schema requires diff --git a/todo.md b/todo.md index 16c83fb..7095591 100644 --- a/todo.md +++ b/todo.md @@ -25,8 +25,6 @@ | ID | Release | Exempt | Item | R | S | C | A | G | Goals | Score | |---|---|---|---|---|---|---|---|---|---|---| -| 52 | 0.2.0 | | **Spell `colwidth` as a comma list, `colwidth="340,420"`.** | 3 | 3 | 3 | 5 | 6 | 6 | 11.5 | -| 53 | 0.2.0 | | **Put a block's `marks` spelling to the writer panel and adopt its pick.** | 4 | 5 | 4 | 5 | 6 | 6 | 10.0 | | 111 | 0.2.1 | | **Split README's `unsupported-node-shape` error-table row into one bullet per cause group, each carrying its remedy.** | 2 | 2 | 1 | 5 | 5 | 3 | 15.3 | | 89 | 0.2.1 | | **Build a `date`, `emoji`, `inlineCard`, `mention` or `status` holding no mark Atlassian's schema withholds from it, in every reader.** | 4 | 4 | 4 | 5 | 6 | 4 | 13.0 | | 99 | 0.2.1 | defect | **Write a linked external image standing inline or in a table cell in the spelling a reader panel picks, in `adfToPortableMarkdown`.** | 3 | 3 | 5 | 6 | 7 | 7 | 12.9 | @@ -73,17 +71,6 @@ ## Details -### 52. Spell `colwidth` as a comma list, `colwidth="340,420"`. - -A writer panel chose it on 2026-10-03, 5 of 7, over today's `colwidth="[340,420]"`. Breaking: -`MIGRATION.md`'s Spellings table gains its row. - -### 53. Put a block's `marks` spelling to the writer panel and adopt its pick. - -Today `marks="[{\"attrs\":{\"mode\":\"wide\"},\"type\":\"breakout\"}]"`, the marks array as -escaped JSON. Breaking where the panel picks another spelling: `MIGRATION.md`'s Spellings table -gains its row. - ### 111. Split README's `unsupported-node-shape` error-table row into one bullet per cause group, each carrying its remedy. The row's "Fires when" cell holds about a dozen causes in four groups (parsing, each writer, both