From 80e1124f39cfd20bacf7943a74c4fdc3b745beac Mon Sep 17 00:00:00 2001 From: Lilleman auf Larv Date: Fri, 9 Oct 2026 02:19:27 +0200 Subject: [PATCH] Name each markdown call by its flavour: a goal, the decision and the panel's pick of portable --- AGENTS.md | 3 ++- README.md | 1 + docs/decisions.md | 41 +++++++++++++++++++++++++++++------------ todo.md | 1 + 4 files changed, 33 insertions(+), 13 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 059d422..63f7e6c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,8 @@ otherwise relitigate. Using the library: `README.md`. What is still to build: `t In `docs/decisions.md`: -- Plain markdown is a flavour of the grammar +- Each call names its flavour +- Portable markdown is a flavour of the grammar - The round-trip is the product - Markdown in is a canonical fixpoint - Equality is deep diff --git a/README.md b/README.md index 4fa92bc..cfdd6cc 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,7 @@ The most useful ADF conversion library available, judged by these goals, in prio 4. **Each format reads and writes as its standard says.** 5. **Our markdown is CommonMark, extended only where CommonMark has no spelling.** 6. **No surprises: output reads and edits the way its audience expects.** + 1. **A function's name says what its markdown does where it goes.** 7. **Lossy conversion drops form, never content.** 8. **Runs in any JavaScript engine, with no runtime dependencies and nothing to configure or connect.** 9. **Fast, and linear in the document's size as JSON.** diff --git a/docs/decisions.md b/docs/decisions.md index 2047f95..c8745c8 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -1,13 +1,31 @@ # Decisions -## Plain markdown is a flavour of the grammar +## Each call names its flavour -2026-09-27, the maintainer. Goal 2. Valid while the plain flavour's spellings are ones the markdown -grammar can read and write. +2026-10-09, the maintainer; names by a developer panel, 2026-10-09. Goals 4, 5 and 6.1. Valid while +each flavour has a standard or a spec of its own. -The lossy pair is the plain flavour: the markdown grammar's reader and writer with the flavour set, -its spellings — alerts, callouts, task markers, `==` — read and written there, so a marker line and -a backslash reach them intact; what the flavour cannot spell reduces ADF→ADF ahead of the writer. +A function's name says which markdown it reads or writes, and a reader reads that flavour alone: + +| Call | Flavour | +| --- | --- | +| `adfToLosslessMarkdown`, `losslessMarkdownToAdf` | the lossless flavour, `spec/flavour.md` | +| `commonMarkToAdf` | CommonMark as its spec says: a directive, a pipe table, `~~`, `==` and an `adf:` fence read as CommonMark reads them | +| `adfToPortableMarkdown`, `portableMarkdownToAdf` | CommonMark, GFM's pipe tables, `~~`, alerts and task markers, and Obsidian's callouts and `==`; no directive and no `adf:` fence | + +No `adfToCommonMark`: the portable writer serves every persona a CommonMark writer would. The panel +picked `portable` 4 of 7 over `plain` 3, `gfm` and `rendered` none: the export readers read it as +"renders anywhere, lossy", and three readers read `plain` as holding no tables or alerts. + +## Portable markdown is a flavour of the grammar + +2026-09-27, the maintainer. Goal 2. Valid while the portable flavour's spellings are ones the +markdown grammar can read and write. + +The lossy pair is the portable flavour: the markdown grammar's reader and writer with the flavour +set, its spellings — alerts, callouts, task markers, `==` — read and written there, so a marker line +and a backslash reach them intact; what the flavour cannot spell reduces ADF→ADF ahead of the +writer. ## The round-trip is the product @@ -103,8 +121,7 @@ rule a code language follows — leaves the info string `adf:` and keeps `type` info string opening `adf:` is reserved, so a `codeBlock` whose language opens so takes the `language` attribute, and `carry` is an ordinary language. A body holding `type` under a named type, or a fence whose info string is `adf:` alone while its body's `type` could be spelled in the info -string, is `unsupported-node-shape`. The reservation claims a fence CommonMark reads as code until -`todo.md` item 43 gives CommonMark its own reader. +string, is `unsupported-node-shape`. The reservation is the lossless flavour's alone. ## A code block is a fence per text node @@ -159,10 +176,10 @@ opener nests by itself and leaf versus container falls out of the node's content 2026-08-23, the maintainer. Goal 5. Valid while prose rarely writes the shapes the carve-outs claim. -Plain CommonMark is a subset, with carve-outs (`spec/flavour.md`): literal text shaped like a -directive, a pipe table or a `~~` pair is claimed, and so is a code fence whose info string opens -`adf:` (§The carry fence names the node type) — plus one image gap. `todo.md` item 43 ends the -claims, giving CommonMark its own reader, and `todo.md` item 65 ends the image gap. +CommonMark is a subset of the lossless flavour, with carve-outs (`spec/flavour.md`): literal text +shaped like a directive, a pipe table or a `~~` pair is claimed, and so is a code fence whose info +string opens `adf:` (§The carry fence names the node type) — plus one image gap, which `todo.md` +item 65 ends. `commonMarkToAdf` claims none of them (§Each call names its flavour). ## Tables diff --git a/todo.md b/todo.md index 2e33b7b..19d20c6 100644 --- a/todo.md +++ b/todo.md @@ -16,6 +16,7 @@ | 4 | 0.67 | | 5 | 0.56 | | 6 | 0.44 | +| 6.1 | 0.44 | | 7 | 0.33 | | 8 | 0.22 | | 9 | 0.11 |