mirror of
https://github.com/larvit/adf-codec.git
synced 2026-11-19 14:45:44 +01:00
Answer prose round 1: the spec names each title and destination, the writing verdict is its own decision citing item 100, items 99 and 101 state what holds, and the migration and changelog rows say what they replace
This commit is contained in:
@@ -27,6 +27,7 @@ In `docs/decisions.md`:
|
|||||||
- Tables
|
- Tables
|
||||||
- Links
|
- Links
|
||||||
- An image reads as an image only alone in its paragraph, else as its alt text linked; a link text holding no node that takes marks reads as its destination, then its hard breaks
|
- An image reads as an image only alone in its paragraph, else as its alt text linked; a link text holding no node that takes marks reads as its destination, then its hard breaks
|
||||||
|
- A linked image is written `[](href)`, a captioned image as its directive
|
||||||
- Ids stay site-local
|
- Ids stay site-local
|
||||||
- Portable task ids come from position
|
- Portable task ids come from position
|
||||||
- A block a task item cannot hold stands after its task list
|
- A block a task item cannot hold stands after its task list
|
||||||
|
|||||||
+2
-2
@@ -60,8 +60,8 @@
|
|||||||
list's own indentation, ends the list, as CommonMark reads it; `0.1.0` read one list. See
|
list's own indentation, ends the list, as CommonMark reads it; `0.1.0` read one list. See
|
||||||
`MIGRATION.md`.
|
`MIGRATION.md`.
|
||||||
- **Breaking:** `adfToLosslessMarkdown` writes a centered, uncaptioned external image whose one
|
- **Breaking:** `adfToLosslessMarkdown` writes a centered, uncaptioned external image whose one
|
||||||
mark is a link holding only `href` and `title` as `[](href "title")`. Convert stored
|
mark is a link holding only `href` and `title` as `[](href "title")`, where it wrote the
|
||||||
markdown per `MIGRATION.md`.
|
`mediaSingle` directive. Convert stored markdown per `MIGRATION.md`.
|
||||||
- Fix the time `adfToLosslessMarkdown` and `adfToPortableMarkdown` take on text holding a long run of
|
- 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
|
`*`, `_`, `~` 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.
|
run, and a run of 20000 `*` takes milliseconds where it took seconds.
|
||||||
|
|||||||
+1
-1
@@ -60,7 +60,7 @@ function migrateMarkdown(stored: string) {
|
|||||||
| --- | --- |
|
| --- | --- |
|
||||||
| `:::panel info` … `:::`, the fence longer per nesting level | `!adf:panel info` … `!adf:/panel` at any depth |
|
| `:::panel info` … `:::`, the fence longer per nesting level | `!adf:panel info` … `!adf:/panel` at any depth |
|
||||||
| `::media {id=a type=file}` | `!adf:media {id=a type=file}` |
|
| `::media {id=a type=file}` | `!adf:media {id=a type=file}` |
|
||||||
| `:::mediaSingle {layout=center}`, `::media {alt=a marks="[{\"attrs\":{\"href\":\"/v\"},\"type\":\"link\"}]" type=external url=u}`, `:::` | `[](/v)` |
|
| `:::mediaSingle {layout=center}` … `:::` around `::media {alt=a marks="[{\"attrs\":{\"href\":\"/v\"},\"type\":\"link\"}]" type=external url=u}` | `[](/v)` |
|
||||||
| `::taskItem TODO {localId=i}`: an empty `caption`, `decisionItem`, `paragraph` or `taskItem`, or an empty `heading` carrying `localId` | `!adf:taskItem TODO {localId=i}` then `!adf:/taskItem` |
|
| `::taskItem TODO {localId=i}`: an empty `caption`, `decisionItem`, `paragraph` or `taskItem`, or an empty `heading` carrying `localId` | `!adf:taskItem TODO {localId=i}` then `!adf:/taskItem` |
|
||||||
| `:mention[@Mikael]{id=5b10a2}` | `!adf:mention[@Mikael]{id=5b10a2}` |
|
| `:mention[@Mikael]{id=5b10a2}` | `!adf:mention[@Mikael]{id=5b10a2}` |
|
||||||
| the `adf` code fence and `:adf{json="…"}` | the `adf:<type>` code fence, its JSON without `type`, and `!adf:carry{json="…"}` |
|
| the `adf` code fence and `:adf{json="…"}` | the `adf:<type>` code fence, its JSON without `type`, and `!adf:carry{json="…"}` |
|
||||||
|
|||||||
+9
-3
@@ -241,9 +241,15 @@ The same panel confirmed the other readings on 2026-10-09: a title as the captio
|
|||||||
text as linked alt text, and an empty link text as its URL, each 3 of 3; `[]()` as nothing, 5 of 7.
|
text as linked alt text, and an empty link text as its URL, each 3 of 3; `[]()` as nothing, 5 of 7.
|
||||||
Their CommonMark suite exceptions are `node-model` (§The CommonMark suite checks three ways).
|
Their CommonMark suite exceptions are `node-model` (§The CommonMark suite checks three ways).
|
||||||
|
|
||||||
Writing, a writer panel of a product manager, an engineer and a support agent on 2026-10-11, 3 of
|
## A linked image is written `[](href)`, a captioned image as its directive
|
||||||
3: `adfToLosslessMarkdown` writes an image only a link marks as `[](href)`, and a
|
|
||||||
captioned image as the `!adf:caption` directive, since a title reads as hover text, not a caption.
|
2026-10-11, a writer panel of a product manager, an engineer and a support agent, 3 of 3 on each.
|
||||||
|
Goal 6. Valid while the audience reads a title as hover text.
|
||||||
|
|
||||||
|
`adfToLosslessMarkdown` writes a `media` whose only mark is a link as `[](href)`, which
|
||||||
|
each reader expected before seeing the options. A captioned image keeps the `!adf:caption`
|
||||||
|
directive: each reader read `` as hover text, not a caption. Every reader still
|
||||||
|
reads that title as the caption; `todo.md` item 100 puts that reading back to a reader panel.
|
||||||
|
|
||||||
## Ids stay site-local
|
## Ids stay site-local
|
||||||
|
|
||||||
|
|||||||
+6
-6
@@ -310,12 +310,12 @@ the destination, `alt` the description's plain-text content when non-empty — a
|
|||||||
it contributing its own text, a node spelling its text in the content slot contributing that text,
|
it contributing its own text, a node spelling its text in the content slot contributing that text,
|
||||||
and a break of either kind a space. A non-empty title, ``, adds a `caption`
|
and a break of either kind a space. A non-empty title, ``, adds a `caption`
|
||||||
holding the title as one text node, and a link whose entire text is the image,
|
holding the title as one text node, and a link whose entire text is the image,
|
||||||
`[](href)`, marks the `media`. `adfToLosslessMarkdown` emits the image form only for the
|
`[](href)`, marks the `media`. `adfToLosslessMarkdown` writes `` only for this
|
||||||
bare shape — those attrs and no others, no marks on the `mediaSingle`, no caption, and a
|
shape: a `mediaSingle` with those attrs and no others, no marks and no caption, holding a `media`
|
||||||
`media` carrying nothing beyond `alt`, `type` and `url` and no mark but a link holding nothing
|
with no attrs beyond `alt`, `type` and `url`. The `media` may carry one mark, a link with no attrs
|
||||||
beyond `href` and `title`, spelled `[](href "title")` — and only where CommonMark spells
|
beyond `href` and `title`, written `[](href "title")`. Where CommonMark cannot spell the
|
||||||
it: a destination, a title or a description the image form cannot hold, an empty `alt` included,
|
image's alt text or URL, or the link's `href` or title, the directive form is written instead; an
|
||||||
takes the directive form instead.
|
empty `alt` counts as one CommonMark cannot spell.
|
||||||
|
|
||||||
`mediaInline` carries a media `collection` + `id`, never a URL, so anywhere else an image reads as
|
`mediaInline` carries a media `collection` + `id`, never a URL, so anywhere else an image reads as
|
||||||
its alt text linked to its destination, the link titled by the image's title: beside other
|
its alt text linked to its destination, the link titled by the image's title: beside other
|
||||||
|
|||||||
@@ -26,8 +26,8 @@
|
|||||||
| ID | Release | Exempt | Item | R | S | A | G | Goals | Score |
|
| ID | Release | Exempt | Item | R | S | A | G | Goals | Score |
|
||||||
|---|---|---|---|---|---|---|---|---|---|
|
|---|---|---|---|---|---|---|---|---|---|
|
||||||
| 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 | 5 | 6 | 4 | 13.0 |
|
| 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 | 5 | 6 | 4 | 13.0 |
|
||||||
| 99 | 0.2.1 | defect | **Keep the link target of a linked external image standing inline or in a table cell, in the spelling a reader panel picks, in `adfToPortableMarkdown`.** | 3 | 3 | 6 | 7 | 7 | 12.9 |
|
| 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 | 6 | 7 | 7 | 12.9 |
|
||||||
| 100 | 0.2.1 | question | **Put the reading of an image's title as its caption back to a reader panel, now that a writer panel reads a title as hover text.** | 3 | 3 | 4 | 5 | 4, 6 | 10.9 |
|
| 100 | 0.2.1 | decision | **Put the reading of an image's title as its caption back to a reader panel, now that a writer panel reads a title as hover text.** | 3 | 3 | 4 | 5 | 4, 6 | 10.9 |
|
||||||
| 60 | 0.2.1 | decision | **Collect the questions `parse/` asks `emit/` into one named module.** | 3 | 4 | 2 | 6 | 2 | 10.7 |
|
| 60 | 0.2.1 | decision | **Collect the questions `parse/` asks `emit/` into one named module.** | 3 | 4 | 2 | 6 | 2 | 10.7 |
|
||||||
| 59 | 0.2.1 | decision | **Group the directive grammar into `src/markdown/directive/`, move `Read<T>` to `result.ts`, and move `Flavour` and `flavourClaims` to `markdown/flavour.ts`.** | 3 | 5 | 2 | 6 | 2 | 10.4 |
|
| 59 | 0.2.1 | decision | **Group the directive grammar into `src/markdown/directive/`, move `Read<T>` to `result.ts`, and move `Flavour` and `flavourClaims` to `markdown/flavour.ts`.** | 3 | 5 | 2 | 6 | 2 | 10.4 |
|
||||||
| 62 | 0.2.1 | decision | **Move the portable flavour's reading out of `parse/` and its writing out of `emit/` into `markdown/portable/`, so `emit/` no longer imports `portable/`.** | 4 | 5 | 2 | 6 | 2 | 9.4 |
|
| 62 | 0.2.1 | decision | **Move the portable flavour's reading out of `parse/` and its writing out of `emit/` into `markdown/portable/`, so `emit/` no longer imports `portable/`.** | 4 | 5 | 2 | 6 | 2 | 9.4 |
|
||||||
@@ -77,12 +77,13 @@
|
|||||||
may reject the document. Replace `InlineNodeModel.takesMarks` (`src/adf/inline-nodes.ts`) with the
|
may reject the document. Replace `InlineNodeModel.takesMarks` (`src/adf/inline-nodes.ts`) with the
|
||||||
mark types a node takes, and have the emitter carry a node holding another.
|
mark types a node takes, and have the emitter carry a node holding another.
|
||||||
|
|
||||||
### 99. Keep the link target of a linked external image standing inline or in a table cell, in the spelling a reader panel picks, in `adfToPortableMarkdown`.
|
### 99. Write a linked external image standing inline or in a table cell in the spelling a reader panel picks, in `adfToPortableMarkdown`.
|
||||||
|
|
||||||
`mediaLeaves` (`src/markdown/portable/inline-reduction.ts`) writes such an image `[alt](url)`, dropping
|
`mediaLeaves` (`src/markdown/portable/inline-reduction.ts`) writes such an image `[alt](url)`, dropping
|
||||||
the link's `href`; README §Portable markdown says link targets stay (Goal 7). `[](href)`
|
the link's `href`; README §Portable markdown says link targets stay (Goal 7). `[](href)`
|
||||||
there reads back as `[alt](href)`, so it breaks the byte-for-byte rewrite: keeping one target is the
|
there reads back as `[alt](href)`, breaking the byte-for-byte rewrite, so only one of `url` and
|
||||||
panel's pick.
|
`href` can survive; a reader panel picks which. If it picks `url`, the README names the dropped
|
||||||
|
`href` where it says link targets stay.
|
||||||
|
|
||||||
### 100. Put the reading of an image's title as its caption back to a reader panel, now that a writer panel reads a title as hover text.
|
### 100. Put the reading of an image's title as its caption back to a reader panel, now that a writer panel reads a title as hover text.
|
||||||
|
|
||||||
@@ -124,15 +125,16 @@ commonmark.js avoids the backtick cost by caching backtick runs by length.
|
|||||||
### 101. Name the CommonMark spelling to write in the refusal of a directive whose node CommonMark spells.
|
### 101. Name the CommonMark spelling to write in the refusal of a directive whose node CommonMark spells.
|
||||||
|
|
||||||
`directiveNode` (`src/markdown/parse/markdown-to-adf.ts`) refuses `!adf:mediaSingle` holding a linked
|
`directiveNode` (`src/markdown/parse/markdown-to-adf.ts`) refuses `!adf:mediaSingle` holding a linked
|
||||||
image with "mediaSingle takes the CommonMark spelling, not the directive form"; the README tells the
|
image as `unsupported-node-shape`: "mediaSingle takes the CommonMark spelling, not the directive
|
||||||
reader to write the spelling the message names, and for `[](href "title")` none is named.
|
form". README §The errors says to fix what the message names, and the message names no spelling,
|
||||||
|
here `[](href "title")`.
|
||||||
|
|
||||||
### 92. Lower the reading cost of the files a chunk reads most before its first commit.
|
### 92. Lower the reading cost of the files a chunk reads most before its first commit.
|
||||||
|
|
||||||
The last five chunks' median is 168135 new input tokens before their first commit, the five before
|
The last five chunks' median is 168135 new input tokens before their first commit, the five before
|
||||||
them 97329. Files read most over the last five chunks, counting opens and searches: `docs/decisions.md` 28, `README.md`
|
them 97329. Files read most over the last five chunks, counting opens and searches:
|
||||||
27, `todo.md` 26, `CHANGELOG.md` 20, `src/markdown/parse/blocks.ts` 15,
|
`docs/decisions.md` 28, `README.md` 27, `todo.md` 26, `CHANGELOG.md` 20,
|
||||||
`src/markdown/portable/adf-to-portable-markdown.ts` 12, `spec/flavour.md` 10,
|
`src/markdown/parse/blocks.ts` 15, `src/markdown/portable/adf-to-portable-markdown.ts` 12, `spec/flavour.md` 10,
|
||||||
`src/markdown/parse/portable-markdown-to-adf.test.ts` 10, `src/markdown/emit/line-escaping.ts` 9,
|
`src/markdown/parse/portable-markdown-to-adf.test.ts` 10, `src/markdown/emit/line-escaping.ts` 9,
|
||||||
`src/markdown/parse/markdown-to-adf.test.ts` 8.
|
`src/markdown/parse/markdown-to-adf.test.ts` 8.
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user