From 1f7d11ea3e886c4c8489e213a187dda1e493fe46 Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Tue, 29 Sep 2026 23:37:39 +0200 Subject: [PATCH] 10f - review: the position id and carry entries and the errors intro stated truly --- README.md | 4 ++-- docs/decisions.md | 13 ++++++------- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 7c39d6e..be56770 100644 --- a/README.md +++ b/README.md @@ -165,8 +165,8 @@ read replaces mentions, attachments and macros with text. ## The errors -An ADF node type this version does not know is not an error: it is carried opaquely and restores -unchanged ([`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#unknown-nodes-ride-the-carry)). +An ADF node type this version does not know is not an error: the lossless pair carries it opaquely +and restores it unchanged ([`docs/decisions.md`](https://gitea.larvit.se/larvit/adf-codec/src/branch/main/docs/decisions.md#unknown-nodes-ride-the-carry)). `ConvertError` is `{ code, message, path, position? }`. `code` is the exported `ConvertErrorCode`, stable across minors and safe to `switch` on exhaustively with no `default`; `message` is free text diff --git a/docs/decisions.md b/docs/decisions.md index 8a834d5..5fcc49f 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -50,8 +50,8 @@ An unknown ADF node is carried opaquely — raw JSON rides a dedicated syntax in restores to a deep-equal node. The round-trip holds for documents newer than the library. So does a known node no section spells where it stands: a markdown serializer spells a node by type without checking its position, and refusing loses a document ADF itself keeps in an `unsupportedBlock`. -Where a container's own spelling cannot hold the child it has — a `bulletList` outside `listItem`, -a `codeBlock` outside text — the error result names that instead. +Where a container's own spelling cannot hold the child it has — a `bulletList` holding other than +`listItem`, a `codeBlock` other than text — the error result names that instead. ## Foreign HTML sorts three ways @@ -131,11 +131,10 @@ accepted. node with no `localId`. `plainMarkdownToAdf` gives each `taskList`, `taskItem` and `blockTaskItem` lacking one a `localId` -in the editor's UUID v4 shape, hashed (cyrb128) from the whole markdown and the node's position in -document order, skipping any id the document holds. A site rejecting a missing `localId` takes the -document, the same markdown reads to the same ids every run, and different markdown to ids no other -document shares. The same markdown pasted twice into one document repeats its ids: determinism -wins over that case. A node the carry restores stays deep-equal (§Unknown nodes ride the carry): its +in the editor's UUID v4 shape, hashed from the whole markdown and the node's order among those it +mints, skipping any id the document holds: the same markdown reads to the same ids every run, +different markdown to different ids. The same markdown pasted twice into one document repeats its +ids: determinism wins over that case. A node the carry restores stays deep-equal (§Unknown nodes ride the carry): its ids are only skipped. ## A callout title keeps its link targets