From 1df58cf33e0ffd0d6fdd381df8acf0075a25e4c6 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Wed, 30 Sep 2026 22:28:40 +0200 Subject: [PATCH 1/3] Goal 5's omission-note sentence moves to the plain flavour's spellings decision --- README.md | 8 +++----- docs/decisions.md | 2 ++ 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index bc0b91b..2620b37 100644 --- a/README.md +++ b/README.md @@ -40,11 +40,9 @@ In priority order. flavour's directive form carries only what CommonMark cannot hold. 5. **Lossy conversion keeps the content.** `adfToPlainMarkdown` and `plainMarkdownToAdf` drop what plain markdown cannot hold — format, design, structure — never content: what a reader of the - rendered document sees or follows, its text, images and link targets. Content the document only - references is marked where it stood, by a note that reads as the converter's and names what was - left out. The lossy pair creates and exports; it never saves back over the document it read — - a document's identity (task, mention, media ids) survives a round trip only through the lossless - pair. + rendered document sees or follows, its text, images and link targets. The lossy pair creates and + exports; it never saves back over the document it read — a document's identity (task, mention, + media ids) survives a round trip only through the lossless pair. 6. **What happens is what the audience expects.** Where the goals leave a choice, a conversion takes the one its audience would predict, reading the input as written. 7. **Failures are values.** Nothing throws, and `code` is a closed list — as much a contract as diff --git a/docs/decisions.md b/docs/decisions.md index ce5be06..eb7ea66 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -158,6 +158,8 @@ renderer confirming each shape. Reader panels settled `error` as an error panel, delimiter, so `は==日本語==で` (3 of 3), `==한국어==에서만` and `iPhone==専用==` (6 of 7) highlight, the external image's two forms (6 of 7), the omission notes and a rule opening a list item dropping (3 of 3), and a list's numbering overflowing into bullets (3 of 3, 5 of 7). +Content the document only references is marked where it stood, by a note that reads as the +converter's and names what was left out. Reading takes other tools' spellings, since it reads their output and writes none of them. Rejected: `~sub~` and `^sup^` (`~2~` is a strike on GitHub, so `subsup` drops), underline and colour spellings, raw HTML (`
`, ``), MkDocs `!!!` and the `:::` admonition family, -- 2.52.0 From 32df10464976172f64de9400c7ae02abae1b8ca0 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Wed, 30 Sep 2026 22:29:38 +0200 Subject: [PATCH 2/3] review: Goal 5 keeps content the document holds, the notes bullet names when each fires --- README.md | 13 +++++++------ docs/decisions.md | 3 +-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/README.md b/README.md index 2620b37..efadb57 100644 --- a/README.md +++ b/README.md @@ -39,10 +39,10 @@ In priority order. 4. **Output a person can edit.** A node CommonMark can spell gets that spelling; the lossless flavour's directive form carries only what CommonMark cannot hold. 5. **Lossy conversion keeps the content.** `adfToPlainMarkdown` and `plainMarkdownToAdf` drop what - plain markdown cannot hold — format, design, structure — never content: what a reader of the - rendered document sees or follows, its text, images and link targets. The lossy pair creates and - exports; it never saves back over the document it read — a document's identity (task, mention, - media ids) survives a round trip only through the lossless pair. + plain markdown cannot hold — format, design, structure — never content the document holds: what + a reader of the rendered document sees or follows, its text, images and link targets. The lossy + pair creates and exports; it never saves back over the document it read — a document's identity + (task, mention, media ids) survives a round trip only through the lossless pair. 6. **What happens is what the audience expects.** Where the goals leave a choice, a conversion takes the one its audience would predict, reading the input as written. 7. **Failures are values.** Nothing throws, and `code` is a closed list — as much a contract as @@ -144,8 +144,9 @@ read replaces mentions, attachments and macros with text. | `placeholder` | nothing | — | - Content the document only references leaves an italic note naming it where it stood: - `_(image not included)_`, `_(jira-issues-table not included)_`, `_(synced block not included)_`, - `_(link card not included)_`, `_(extension not included)_`. + `_(image not included)_`, `_(synced block not included)_`, `_(link card not included)_` for a card + with no URL, and an extension's key, `_(jira-issues-table not included)_`, or + `_(extension not included)_` where it has none. - `backgroundColor`, `code`, `em`, `link`, `strike` and `strong` stay; every other mark drops, keeping its text, and so does a mark the flavour cannot spell where it stands. - A newline in text is a hard break and in an expand's title a space, edge whitespace outside a diff --git a/docs/decisions.md b/docs/decisions.md index eb7ea66..b6a3f9a 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -158,8 +158,7 @@ renderer confirming each shape. Reader panels settled `error` as an error panel, delimiter, so `は==日本語==で` (3 of 3), `==한국어==에서만` and `iPhone==専用==` (6 of 7) highlight, the external image's two forms (6 of 7), the omission notes and a rule opening a list item dropping (3 of 3), and a list's numbering overflowing into bullets (3 of 3, 5 of 7). -Content the document only references is marked where it stood, by a note that reads as the -converter's and names what was left out. +An omission note reads as the converter's, never as the author's. Reading takes other tools' spellings, since it reads their output and writes none of them. Rejected: `~sub~` and `^sup^` (`~2~` is a strike on GitHub, so `subsup` drops), underline and colour spellings, raw HTML (`
`, ``), MkDocs `!!!` and the `:::` admonition family, -- 2.52.0 From e949f2099c92e3d43cf9c2aa3a3f8e636bbf4d8a Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Wed, 30 Sep 2026 22:30:09 +0200 Subject: [PATCH 3/3] review: the notes bullet states when each note fires, syncBlock named --- README.md | 11 ++++++----- docs/decisions.md | 4 ++-- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index efadb57..e43453f 100644 --- a/README.md +++ b/README.md @@ -137,16 +137,17 @@ read replaces mentions, attachments and macros with text. | `table` | a pipe table: the first row its header, a cell's blocks on one line, a span kept under its header by empty cells | — | | `decisionList` | a bullet list | — | | `mention`, `status`, `emoji`, `date` | their text: `@` kept, a mention with none `@` and its id, an emoji its `shortName` without, a date `2026-09-13` in UTC | — | -| `inlineCard`, `blockCard`, `embedCard` | a link to the card's URL | — | +| `inlineCard`, `blockCard`, `embedCard` | a link to the card's URL, else its name | — | | external `media` | `![alt](url)` in a block, `[alt](url)` inline | — | | stored `media`, `mediaInline`, `extension`, `inlineExtension` | their `alt` or `text` | — | | `layoutSection`, `bodiedExtension`, `bodiedSyncBlock`, `multiBodiedExtension`, `extensionFrame`, `caption`, a node this version does not know | its blocks or its text | — | | `placeholder` | nothing | — | -- Content the document only references leaves an italic note naming it where it stood: - `_(image not included)_`, `_(synced block not included)_`, `_(link card not included)_` for a card - with no URL, and an extension's key, `_(jira-issues-table not included)_`, or - `_(extension not included)_` where it has none. +- Content the document only references, with no text of its own to keep, leaves an italic note + naming it where it stood: `_(image not included)_` for stored media with no `alt`, + `_(link card not included)_` for a card with neither URL nor name, an extension with no `text` + its key, `_(jira-issues-table not included)_`, or `_(extension not included)_` without one, and + `_(synced block not included)_` for a `syncBlock`. - `backgroundColor`, `code`, `em`, `link`, `strike` and `strong` stay; every other mark drops, keeping its text, and so does a mark the flavour cannot spell where it stands. - A newline in text is a hard break and in an expand's title a space, edge whitespace outside a diff --git a/docs/decisions.md b/docs/decisions.md index b6a3f9a..a1d0d34 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -156,8 +156,8 @@ MkDocs, Docusaurus, Typora, Joplin, Logseq, Bear, Notion, Azure DevOps and Disco renderer confirming each shape. Reader panels settled `error` as an error panel, the `==` bounds (3 of 3) and a Han, Hangul, kana, Thai, Lao, Khmer or Myanmar character on either side bounding a delimiter, so `は==日本語==で` (3 of 3), `==한국어==에서만` and `iPhone==専用==` (6 of 7) highlight, -the external image's two forms (6 of 7), the omission notes and a rule opening a list item -dropping (3 of 3), and a list's numbering overflowing into bullets (3 of 3, 5 of 7). +the external image's two forms (6 of 7), a rule opening a list item dropping and the omission +notes (3 of 3), and a list's numbering overflowing into bullets (3 of 3, 5 of 7). An omission note reads as the converter's, never as the author's. Reading takes other tools' spellings, since it reads their output and writes none of them. Rejected: `~sub~` and `^sup^` (`~2~` is a strike on GitHub, so `subsup` drops), underline and colour -- 2.52.0