From 856035533e525c097b58418f02cc0f7c4b2b122c Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Sun, 15 Nov 2026 23:03:16 +0100 Subject: [PATCH] =?UTF-8?q?Answer=20stability=20round=201:=200=20?= =?UTF-8?q?=F0=9F=94=B4,=202=20=F0=9F=9F=A1=20(0=20misread);=20read=20fore?= =?UTF-8?q?ign=20HTML=20best=20effort,=20never=20refused,=20and=20scope=20?= =?UTF-8?q?the=20htmlToAdf=20decision=20to=20item=20137=20with=20the=20dia?= =?UTF-8?q?lect=20read=20first?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 4 ++-- README.md | 6 +++--- docs/decisions.md | 48 +++++++++++++++++++++++------------------- docs/kovetskiy-mark.md | 4 ++-- spec/flavour.md | 2 +- todo.md | 41 +++++++++++++++++++----------------- 6 files changed, 56 insertions(+), 49 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f9b971d..eaad46f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,7 +21,7 @@ In `docs/decisions.md`: - Unknown nodes ride the carry - The carry fence names the node type - A code block is a fence per text node -- Foreign HTML sorts three ways +- Foreign HTML reads best effort and is never refused - Names stay text - Directives under `!adf:` - CommonMark is a subset @@ -94,7 +94,7 @@ In `docs/decisions.md`: - The real-world corpus holds anonymized documents from sites whose licence it records - The feature table is a section per corpus example, led by a summary table - Plain text is blocks a blank line apart, with `• ` and `1.` markers and nesting indented -- Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer drops it instead +- Jira wiki markup carries what it cannot spell in Jira's `{adf}` macro, and a lossy writer keeps only its content - `htmlToAdf` reads any HTML, with no option and no second call ## 1. Nothing about any consumer in the library diff --git a/README.md b/README.md index d40811b..436dcdf 100644 --- a/README.md +++ b/README.md @@ -286,9 +286,9 @@ which is free text. - **LLM/agent pipeline** — hands documents to a model as markdown and writes the edits back. Relies on the round-trip and on markdown a reader half-knowing the lossless flavour can still edit. -Behind those apps, the people who read and write the markdown and the HTML: product -managers, engineers and support agents working in Atlassian products through a plugin or another -UI. They know markdown and not ADF, and rely on every spelling saying what it means to them. +Behind those apps, the people who read and write the markdown, the HTML and the Jira wiki markup: +product managers, engineers and support agents working in Atlassian products through a plugin or +another UI. They know markdown and not ADF, and rely on every spelling saying what it means to them. Also behind them, the people who read a document's plain text as they read an email, whether it arrives in an email, a notification or a search hit. They see no markup, and rely on text that diff --git a/docs/decisions.md b/docs/decisions.md index 7a14dc2..2edd175 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -161,25 +161,23 @@ node, so each node keeps its own text. The fences carry one info string, since A language, and none is empty beside another, since a text node holds text. The grammar: `spec/flavour.md` §The CommonMark blocks, the `codeBlock` bullet. -## Foreign HTML sorts three ways +## Foreign HTML reads best effort and is never refused -2026-08-23, the sort 2026-09-20, the maintainer. Goals 1 and 5. Valid while ADF holds no node -for a bare container, a comment or a script. Lands with `todo.md` item 137. +2026-08-23, the sort 2026-09-20, best effort 2026-11-15, the maintainer. Goals 7 and 12. Valid while +ADF holds no node for a bare container, a comment or a script. Lands with `todo.md` item 137. -Every foreign element `htmlToAdf` and the markdown readers read sorts one of three ways, never a -silent drop of content: +HTML from emails, CMSs and editors guarantees nothing, so no foreign element is refused. Each reads +one of two ways: - A container around document content that ADF has no node for unwraps to its children, its own attributes dropped: `
text
` keeps `text`, losing the alignment. -- Content ADF cannot hold is an error result naming it. A comment is one: a person wrote those - words, and neither of Atlassian's schemas holds them — `annotation`'s `inlineComment` carries an - id, `placeholder` is the editor's own hint, `extension` names a vendor app. -- What is not document content drops whole: `